name: dev-api-design description: 用于REST、GraphQL、gRPC和tRPC的生产级API设计模式。涵盖API架构、OpenAPI/Swagger规范、版本控制/废弃、认证/授权、速率限制、分页、错误模型、合同测试和开发者文档。

API开发与设计 — 快速参考

使用此技能来设计、实现和文档化生产级API（REST、GraphQL、gRPC和tRPC）。应用于合同设计（OpenAPI）、版本控制/废弃、认证/授权、速率限制、分页、错误模型和开发者文档。

现代最佳实践（2026年1月）：HTTP语义和可缓存性（RFC 9110）、问题详情错误模型（RFC 9457）、OpenAPI 3.1+、合同优先 + 破坏性变更检测、强认证/授权边界、显式版本控制/废弃、默认可操作的API（幂等性、速率限制、可观察性、跟踪上下文）。

默认执行清单

基于约束选择API风格（公开 vs 内部、性能、客户端查询灵活性）。
首先定义合同（OpenAPI或GraphQL模式；gRPC使用protobuf）。
定义错误模型（RFC 9457 + 稳定错误代码 + 跟踪ID）。
定义认证/授权边界（范围/角色/租户）和威胁模型。
为所有列表端点定义分页/过滤/排序。
定义速率限制/配额、幂等性策略（特别是POST）和重试/退避指导。
定义可观察性（W3C跟踪上下文、请求ID、指标、日志）和服务水平目标。
在CI中添加合同测试 + 破坏性变更检查。
发布包含示例 + 迁移/废弃政策的文档。

快速参考

任务	模式/工具	关键元素	何时使用
设计REST API	RESTful设计	名词（非动词）、HTTP方法、适当状态码	资源型API、CRUD操作
版本API	URL版本控制	`/api/v1/resource`、`/api/v2/resource`	破坏性变更、客户端迁移
分页结果	游标分页	`cursor=eyJpZCI6MTIzfQ&limit=20`	实时数据、大型集合
处理错误	RFC 9457问题详情	`type`、`title`、`status`、`detail`、`errors[]`	一致的错误响应
认证	JWT承载令牌	`Authorization: Bearer <token>`	无状态认证、微服务
速率限制	令牌桶算法	`X-RateLimit-*`头部、429响应	防止滥用、公平使用
文档化API	OpenAPI 3.1	Swagger UI、Redoc、代码示例	交互式文档、客户端SDK
灵活查询	GraphQL	模式优先、解析器、DataLoader	客户端驱动的数据获取
高性能	gRPC + Protobuf	二进制协议、流式处理	内部微服务
TypeScript优先	tRPC	端到端类型安全、无需代码生成	单体仓库、内部工具
AI智能体API	REST + MCP	智能体体验、机器可读	LLM/智能体消费

决策树：选择API风格

用户需求：[API类型]
    ├─ 面向第三方的公开API？
    │   └─ 带OpenAPI文档的REST（广泛兼容性）
    │
    ├─ 内部微服务？
    │   ├─ 需要高吞吐量？ → **gRPC**（二进制、快速）
    │   └─ 简单CRUD？ → **REST**（易于调试）
    │
    ├─ TypeScript单体仓库（前端 + 后端）？
    │   └─ **tRPC**（端到端类型安全、无需代码生成）
    │
    ├─ 客户端需要灵活查询？
    │   ├─ 实时更新？ → **GraphQL订阅**或**WebSockets**
    │   └─ 复杂数据获取？ → **GraphQL**（避免过度获取）
    │
    ├─ 移动/Web客户端？
    │   ├─ 多种实体类型？ → **GraphQL**（单端点）
    │   └─ 简单资源？ → **REST**（可缓存）
    │
    ├─ AI智能体消费API？
    │   └─ REST + **MCP**包装器（智能体体验）
    │
    └─ 流式或双向？
        └─ **gRPC**（HTTP/2流式）或**WebSockets**

导航：核心API模式

RESTful API设计

资源： references/restful-design-patterns.md

资源型URL与适当HTTP方法（GET、POST、PUT、PATCH、DELETE）
HTTP状态码语义（200、201、404、422、500）
幂等性保证（GET、PUT、DELETE）
无状态设计原则
URL结构最佳实践（集合 vs 资源端点）
嵌套资源和操作端点

分页、过滤和排序

资源： references/pagination-filtering.md

偏移分页（简单、静态数据集）
游标分页（实时流、推荐）
页码分页（带页码的UI）
带操作符的查询参数过滤（_gt、_contains、_in）
带方向的多字段排序（-created_at）
带索引的性能优化

错误处理

资源： references/error-handling-patterns.md

RFC 9457问题详情标准
HTTP状态码参考（4xx客户端错误、5xx服务器错误）
字段级验证错误
调试的跟踪ID
跨端点一致的错误格式
生产环境中的安全错误消息（无堆栈跟踪）

认证和授权

资源： references/authentication-patterns.md

JWT（JSON Web令牌）与刷新令牌轮换
OAuth2授权码流用于第三方认证
API密钥认证用于服务器到服务器
RBAC（基于角色的访问控制）
ABAC（基于属性的访问控制）
基于资源的授权（用户拥有的资源）

速率限制和节流

资源： references/rate-limiting-patterns.md

令牌桶算法（推荐，允许突发）
固定窗口 vs 滑动窗口
速率限制头部（X-RateLimit-*）
分层速率限制（免费、付费、企业版）
基于Redis的分布式速率限制
按用户、按端点、按API密钥的策略

导航：扩展资源

API设计和最佳实践

api-design-best-practices.md - 全面的API设计原则
versioning-strategies.md - URL、头部和查询参数版本控制
api-security-checklist.md - OWASP API安全前十

GraphQL和gRPC

graphql-patterns.md - 模式设计、解析器、N+1查询、DataLoader
gRPC模式 - 见software-backend获取Protocol Buffers和服务定义

tRPC（TypeScript优先）

trpc-patterns.md - 端到端类型安全、程序、React Query集成
- 何时使用tRPC vs GraphQL vs REST
- 认证中间件模式
- 使用Next.js的服务器端渲染

OpenAPI和文档化

openapi-guide.md - OpenAPI 3.1规范、Swagger UI、Redoc
模板： assets/openapi-template.yaml - 完整的OpenAPI规范示例

可选：AI/自动化（LLM/智能体API）

llm-agent-api-contracts.md - 流式处理、长时间运行作业、安全护栏、可观察性

导航：模板

生产就绪、可直接复制的API实现，包含认证、数据库、验证和文档。

框架特定模板

FastAPI（Python）：assets/fastapi/fastapi-complete-api.md
- 异步/等待、Pydantic v2、JWT认证、SQLAlchemy 2.0、分页、OpenAPI文档
Express.js（Node/TypeScript）：assets/express-nodejs/express-complete-api.md
- TypeScript、Zod验证、Prisma ORM、JWT刷新令牌、速率限制
Django REST框架：assets/django-rest/django-rest-complete-api.md
- ViewSets、序列化器、Simple JWT、权限、DRF过滤/分页
Spring Boot（Java）：assets/spring-boot/spring-boot-complete-api.md
- Spring Security JWT、Spring Data JPA、Bean验证、Springdoc OpenAPI

跨平台模式

api-patterns-universal.md - 适用于所有框架的通用模式
- 认证策略、分页、缓存、版本控制、验证
template-api-governance.md - API治理、废弃、多租户
- 废弃政策（90天时间线）、向后兼容性规则、错误模型模板
template-api-design-review-checklist.md - 生产API审核清单（安全、可靠性、可操作性）
template-api-error-model.md - RFC 9457问题详情 + 稳定错误代码注册表

做 / 避免

好：做

从一开始就版本化API
在首次废弃前文档化废弃政策
将破坏性变更视为主要版本（并保持次要变更向后兼容）
在所有错误响应中包含跟踪ID
返回适当的HTTP状态码
实现带清晰头部的速率限制
使用RFC 9457问题详情处理错误

坏：避免

无废弃期移除字段
更改现有版本中的字段类型
在资源名中使用动词（仅名词）
为客户端错误返回500
无主要版本号的破坏性变更
无显式隔离混合租户数据
到处使用操作端点（/doSomething）

反模式

反模式	问题	修复
即时废弃	破坏客户端	至少90天弃用期
操作端点	不一致的API	使用资源 + HTTP动词
版本在正文中	难以路由、调试	版本在URL或头部中
通用错误	开发者体验差	特定错误代码 + 消息
无速率限制头部	客户端无法退避	包含X-RateLimit-*
仅URL中租户ID	伪造风险	针对认证令牌验证
泄漏抽象	紧耦合	设计稳定合同

可选：AI/自动化

注意：AI工具辅助但合同需要人工审核。

OpenAPI代码检查 — CI/CD中的Spectral、Redocly
破坏性变更检测 — oasdiff自动检查
SDK生成 — 从变更的OpenAPI规范
合同测试 — Pact、Dredd自动化

有界声明

AI生成的OpenAPI规范需要人工审核
自动化废弃检测需要手动确认
SDK生成需要类型验证

外部资源

见data/sources.json获取：

官方REST、GraphQL、gRPC文档
OpenAPI/Swagger工具和验证器
API设计风格指南（谷歌、微软、Stripe）
安全标准（OWASP API安全前十）
测试工具（Postman、Insomnia、Paw）

使用说明

对于智能体：

默认应用RESTful原则，除非用户请求GraphQL/gRPC
总是为列表端点包含分页
使用RFC 9457格式处理错误响应
在所有模板中包含认证（JWT或API密钥）
参考框架特定模板获取完整实现
链接到相关资源获取深入指导

成功标准： API可发现、一致、文档化良好、安全，并正确遵循HTTP/GraphQL语义。

时间敏感建议

如果用户询问“最佳”工具/框架、“最新”标准，或某事物在2026年是否仍然相关，请使用当前环境中可用的任何浏览/搜索工具快速进行网络搜索。如果无法访问网络，请从稳定原则回答，说明假设（流量、延迟、团队技能、生态系统），并避免过度强调时效性。

API开发与设计 dev-api-design