orval

Orval OpenAPI 最佳实践

使用 Orval 根据 OpenAPI 规范生成类型安全的 TypeScript 客户端的综合指南。包含 8 个类别中的 42 条规则，并按影响排序，为自动化配置、客户端生成和测试设置提供指导。

适用场景

在以下情况下参考这些指南：

• 为新项目配置 Orval
• 设置基于 OpenAPI 的 TypeScript 客户端生成
• 将 React Query、SWR 或 Vue Query 与生成的钩子集成
• 为身份验证和错误处理创建自定义 mutator
• 为测试生成 MSW 模拟

按优先级划分的规则类别

优先级	类别	影响	前缀
1	OpenAPI 规范质量	CRITICAL	spec-
2	配置架构	CRITICAL	orvalcfg-
3	输出结构与组织	HIGH	output-
4	自定义客户端与 Mutator	HIGH	mutator-
5	查询库集成	MEDIUM-HIGH	oquery-
6	类型安全与验证	MEDIUM	types-
7	模拟生成与测试	MEDIUM	mock-
8	高级模式	LOW	adv-

快速参考

1. OpenAPI 规范质量（CRITICAL）

• spec-operationid-unique - 使用唯一且具有描述性的 operationId
• spec-schemas-reusable - 在 components 中定义可复用的 schemas
• spec-tags-organization - 使用 tags 组织操作
• spec-response-types - 明确定义所有响应类型
• spec-required-fields - 明确标记必填字段

2. 配置架构（CRITICAL）

• orvalcfg-mode-selection - 根据 API 大小选择输出模式
• orvalcfg-client-selection - 根据框架要求选择客户端
• orvalcfg-separate-schemas - 将 schemas 分离到专用目录中
• orvalcfg-input-validation - 在生成前验证 OpenAPI 规范
• orvalcfg-baseurl-setup - 正确配置基础 URL
• orvalcfg-prettier-format - 启用自动代码格式化

3. 输出结构与组织（HIGH）

• output-file-extension - 为生成的代码使用不同的文件扩展名
• output-index-files - 生成 index 文件，便于清晰导入
• output-naming-convention - 配置统一的命名约定
• output-clean-target - 启用清理模式，确保重新生成结果一致
• output-headers-enabled - 在生成的函数中启用 headers

4. 自定义客户端与 Mutator（HIGH）

• mutator-custom-instance - 使用自定义 mutator 配置 HTTP 客户端
• mutator-error-types - 从 mutator 导出自定义错误类型
• mutator-body-wrapper - 导出用于请求转换的 body 类型包装器
• mutator-interceptors - 使用拦截器处理横切关注点
• mutator-token-refresh - 在 mutator 中处理令牌刷新
• mutator-fetch-client - 使用 fetch mutator 减小打包体积

5. 查询库集成（MEDIUM-HIGH）

• oquery-hook-options - 全局配置默认查询选项
• oquery-key-export - 导出查询键以便失效缓存
• oquery-infinite-queries - 为分页端点启用无限查询
• oquery-suspense-support - 启用 suspense 模式，提供流式 UX
• oquery-signal-cancellation - 传递 AbortSignal 以取消请求
• oquery-mutation-callbacks - 使用生成的 mutation 选项类型

6. 类型安全与验证（MEDIUM）

• types-zod-validation - 生成 Zod schemas 以进行运行时验证
• types-zod-strict - 启用 Zod strict 模式，确保更安全的验证
• types-zod-coerce - 使用 Zod 强制转换进行类型转换
• types-use-dates - 启用 useDates 以生成 Date 类型
• types-bigint-support - 启用 useBigInt 以支持大整数

7. 模拟生成与测试（中）

• mock-msw-generation - 生成用于测试的 MSW 处理程序
• mock-use-examples - 使用 OpenAPI 示例创建逼真的模拟
• mock-delay-config - 配置模拟响应延迟
• mock-http-status - 为所有 HTTP 状态码生成模拟
• mock-index-files - 生成模拟索引文件，便于设置

8. 高级模式（低）

• adv-input-transformer - 使用输入转换器预处理规范
• adv-operation-override - 按操作覆盖设置
• adv-output-transformer - 使用输出转换器修改生成的代码
• adv-form-data-handling - 配置表单数据序列化

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板
• 示例：spec-operationid-unique

相关技能

• 如需使用生成的钩子，请参阅 tanstack-query 技能
• 如需模拟生成的 API 客户端，请参阅 test-msw 技能
• 如需进行架构验证，请参阅 zod 技能

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md