name: orval description: Orval OpenAPI TypeScript客户端生成最佳实践。此技能应用于配置Orval、从OpenAPI规范生成TypeScript客户端、设置React Query/SWR hooks、创建自定义mutators或编写MSW mocks时。触发涉及orval.config.ts、OpenAPI代码生成、API客户端设置或模拟生成的任务。
Orval OpenAPI 最佳实践
使用Orval从OpenAPI规范生成类型安全的TypeScript客户端的综合指南。包含8个类别的42条规则，按影响优先级排序，以指导自动化配置、客户端生成和测试设置。
何时应用
在以下情况下参考这些指南：
- 为新项目配置Orval
- 设置基于OpenAPI的TypeScript客户端生成
- 将React Query、SWR或Vue Query与生成的hooks集成
- 创建用于身份验证和错误处理的自定义mutators
- 生成用于测试的MSW mocks
规则类别按优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | OpenAPI规范质量 | 关键 | spec- |
| 2 | 配置架构 | 关键 | orvalcfg- |
| 3 | 输出结构与组织 | 高 | output- |
| 4 | 自定义客户端和Mutators | 高 | mutator- |
| 5 | 查询库集成 | 中高 | oquery- |
| 6 | 类型安全与验证 | 中 | types- |
| 7 | 模拟生成与测试 | 中 | mock- |
| 8 | 高级模式 | 低 | adv- |
快速参考
1. OpenAPI规范质量 (关键)
spec-operationid-unique- 使用唯一且描述性的operationIdsspec-schemas-reusable- 在组件中定义可重用的模式spec-tags-organization- 使用标签组织操作spec-response-types- 显式定义所有响应类型spec-required-fields- 显式标记必填字段
2. 配置架构 (关键)
orvalcfg-mode-selection- 根据API大小选择输出模式orvalcfg-client-selection- 根据框架要求选择客户端orvalcfg-separate-schemas- 将模式分离到专用目录orvalcfg-input-validation- 在生成前验证OpenAPI规范orvalcfg-baseurl-setup- 正确配置基础URLorvalcfg-prettier-format- 启用自动代码格式化
3. 输出结构与组织 (高)
output-file-extension- 为生成的代码使用不同的文件扩展名output-index-files- 生成索引文件以简化导入output-naming-convention- 配置一致的命名约定output-clean-target- 启用清理模式以实现一致的重生成output-headers-enabled- 在生成的函数中启用头信息
4. 自定义客户端和Mutators (高)
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. 查询库集成 (中高)
oquery-hook-options- 全局配置默认查询选项oquery-key-export- 导出查询键以进行缓存失效oquery-infinite-queries- 为分页端点启用无限查询oquery-suspense-support- 启用suspense模式以改善流式UXoquery-signal-cancellation- 传递AbortSignal以取消请求oquery-mutation-callbacks- 使用生成的突变选项类型
6. 类型安全与验证 (中)
types-zod-validation- 生成Zod模式以进行运行时验证types-zod-strict- 启用Zod严格模式以进行更安全的验证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
相关技能
- 对于使用生成的hooks，参见
tanstack-query技能 - 对于模拟生成的API客户端，参见
test-msw技能 - 对于模式验证，参见
zod技能
完整编译文档
对于扩展了所有规则的完整指南：AGENTS.md