Orval OpenAPI 最佳实践：42条规则生成类型安全的TypeScript客户端

orval by pproenca/dot-skills

117 周安装量

95 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/pproenca/dot-skills --skill orval

TypeScript 代码生成 API

🇨🇳中文介绍

Orval OpenAPI 最佳实践

使用 Orval 从 OpenAPI 规范生成类型安全的 TypeScript 客户端的综合指南。包含 8 个类别共 42 条规则，按影响优先级排序，以指导自动化配置、客户端生成和测试设置。

适用时机

在以下情况时参考本指南：

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

按优先级划分的规则类别

优先级	类别	影响	前缀
1	OpenAPI 规范质量	关键	`spec-`
2	配置架构	关键	`orvalcfg-`
3	输出结构与组织	高

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1. OpenAPI 规范质量 (关键)

spec-operationid-unique - 使用唯一且描述性的 operationId
spec-schemas-reusable - 在 components 中定义可复用的模式
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 - 正确配置基础 URL
orvalcfg-prettier-format - 启用自动代码格式化

3. 输出结构与组织 (高)

output-file-extension - 为生成的代码使用不同的文件扩展名
output-index-files - 生成索引文件以便清晰导入
output-naming-convention - 配置一致的命名约定
output-clean-target - 启用清理模式以实现一致的重新生成
output-headers-enabled - 在生成的函数中启用 headers

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 模式以获得流式 UX
oquery-signal-cancellation - 传递 AbortSignal 以取消请求
oquery-mutation-callbacks - 使用生成的 mutation 选项类型

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

关于使用生成的钩子，请参阅 tanstack-query 技能
关于模拟生成的 API 客户端，请参阅 test-msw 技能
关于模式验证，请参阅 zod 技能

如需包含所有展开规则的完整指南，请参阅：AGENTS.md

🇺🇸English

Orval OpenAPI Best Practices

Comprehensive guide for generating type-safe TypeScript clients from OpenAPI specifications using Orval. Contains 42 rules across 8 categories, prioritized by impact to guide automated configuration, client generation, and testing setup.

When to Apply

Reference these guidelines when:

Configuring Orval for a new project
Setting up OpenAPI-based TypeScript client generation
Integrating React Query, SWR, or Vue Query with generated hooks
Creating custom mutators for authentication and error handling
Generating MSW mocks for testing

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	OpenAPI Specification Quality	CRITICAL	`spec-`
2	Configuration Architecture	CRITICAL	`orvalcfg-`
3	Output Structure & Organization	HIGH	`output-`
4	Custom Client & Mutators	HIGH	`mutator-`
5	Query Library Integration	MEDIUM-HIGH	`oquery-`
6	Type Safety & Validation	MEDIUM	`types-`
7	Mock Generation & Testing	MEDIUM	`mock-`
8	Advanced Patterns	LOW	`adv-`

Quick Reference

1. OpenAPI Specification Quality (CRITICAL)

spec-operationid-unique - Use unique and descriptive operationIds
spec-schemas-reusable - Define reusable schemas in components
spec-tags-organization - Organize operations with tags
spec-response-types - Define all response types explicitly
spec-required-fields - Mark required fields explicitly

2. Configuration Architecture (CRITICAL)

orvalcfg-mode-selection - Choose output mode based on API size
orvalcfg-client-selection - Select client based on framework requirements
orvalcfg-separate-schemas - Separate schemas into dedicated directory
orvalcfg-input-validation - Validate OpenAPI spec before generation
orvalcfg-baseurl-setup - Configure base URL properly
orvalcfg-prettier-format - Enable automatic code formatting

3. Output Structure & Organization (HIGH)

output-file-extension - Use distinct file extensions for generated code
output-index-files - Generate index files for clean imports
output-naming-convention - Configure consistent naming conventions
output-clean-target - Enable clean mode for consistent regeneration
output-headers-enabled - Enable headers in generated functions

4. Custom Client & Mutators (HIGH)

mutator-custom-instance - Use custom mutator for HTTP client configuration
mutator-error-types - Export custom error types from mutator
mutator-body-wrapper - Export body type wrapper for request transformation
mutator-interceptors - Use interceptors for cross-cutting concerns
mutator-token-refresh - Handle token refresh in mutator
mutator-fetch-client - Use fetch mutator for smaller bundle size

5. Query Library Integration (MEDIUM-HIGH)

oquery-hook-options - Configure default query options globally
oquery-key-export - Export query keys for cache invalidation
oquery-infinite-queries - Enable infinite queries for paginated endpoints
oquery-suspense-support - Enable suspense mode for streaming UX
oquery-signal-cancellation - Pass AbortSignal for request cancellation
oquery-mutation-callbacks - Use generated mutation options types

6. Type Safety & Validation (MEDIUM)

types-zod-validation - Generate Zod schemas for runtime validation
types-zod-strict - Enable Zod strict mode for safer validation
types-zod-coerce - Use Zod coercion for type transformations
types-use-dates - Enable useDates for Date type generation
types-bigint-support - Enable useBigInt for large integer support

7. Mock Generation & Testing (MEDIUM)

mock-msw-generation - Generate MSW handlers for testing
mock-use-examples - Use OpenAPI examples for realistic mocks
mock-delay-config - Configure mock response delays
mock-http-status - Generate mocks for all HTTP status codes
mock-index-files - Generate mock index files for easy setup

8. Advanced Patterns (LOW)

adv-input-transformer - Use input transformer for spec preprocessing
adv-operation-override - Override settings per operation
adv-output-transformer - Use output transformer for generated code modification
adv-form-data-handling - Configure form data serialization

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
Example: spec-operationid-unique

Related Skills

For consuming generated hooks, see tanstack-query skill
For mocking generated API clients, see test-msw skill
For schema validation, see zod skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Weekly Installs

104

Repository

pproenca/dot-skills

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli87

codex86

claude-code83

opencode83

cursor79

github-copilot76

lark-cli 共享规则：飞书资源操作指南与权限配置详解

39,000 周安装