# API 开发与设计 — 快速参考使用此技能来设计、实现和记录生产级 API（REST、GraphQL、gRPC 和 tRPC）。将其应用于合约设计 (OpenAPI)、版本控制/弃用、身份验证/授权、速率限制、分页、错误模型和开发人员文档。 **现代最佳实践（2026 年 1 月）**：HTTP 语义和可缓存性 (RFC 9110)、问题详细信息错误模型 (RFC 9457)、OpenAPI 3.1+、合约优先 + 重大更改检测、强 AuthN/Z 边界、显式版本控制/弃用以及默认可操作 API（幂等性、速率限制、可观察性、跟踪上下文）。 ** ** ## 默认执行清单 * 根据约束（公共与内部、性能、客户端查询灵活性）选择 API 样式。 * 首先定义合约（OpenAPI 或 GraphQL 模式；gRPC 的 protobuf）。 * 定义错误模型（RFC 9457 + 稳定错误代码 + 跟踪 ID）。 * 定义 AuthN/AuthZ 边界（范围/角色/租赁）和威胁模型。 * 为所有列表端点定义分页/过滤/排序。 * 定义速率限制/配额、幂等策略（尤其是 POST）和重试/退避指导。 * 定义可观察性（W3C 跟踪上下文、请求 ID、指标、日志）和 SLO。 * 在 CI 中添加合同测试 + 重大变更检查。 * 发布带有示例的文档 + 迁移/弃用政策。 ** ** ## 快速参考任务|图案/工具|关键要素|何时使用 ---|---|---|--- **设计 REST API** |宁静的设计 |名词（不是动词）、HTTP 方法、正确的状态代码 |基于资源的API、CRUD操作 **版本API** | URL 版本控制 | `/api/v1/resource`、`/api/v2/resource` |重大变更、客户端迁移 **对结果进行分页** |基于光标的 | `光标=eyJpZCI6MTIzfQ&限制=20` |实时数据，海量采集 **处理错误** | RFC 9457 问题详细信息 | `类型`、`标题`、`状态`、`详细信息`、`错误[]` |一致的错误响应 **验证** | JWT 承载 | `授权：持有者 <令牌>` |无状态身份验证、微服务 **速率限制** |令牌桶| `X-RateLimit-*` 标头，429 个响应 |防止滥用、公平使用 **文档API** |开放API 3.1 | Swagger UI、Redoc、代码示例 |交互式文档、客户端 SDK **灵活查询** | GraphQL |架构优先、解析器、DataLoader |客户端驱动的数据获取 **高性能** | gRPC + Protobuf |二进制协议，流式 |内部微服务 **TypeScript-first** | tRPC |端到端类型安全，无需代码生成 | Monorepos，内部工具 **AI 代理 API** |休息 + MCP |代理经验，机器可读 | LLM/代理消费 ** ** ## 决策树：选择 API 风格用户需求：[API类型] ├─ 第三方公共API？ │ └─ REST with OpenAPI 文档（广泛兼容性） │ ├─ 内部微服务？ │ ├─ 需要高通量？ → **gRPC**（二进制，快速） │ └─ 简单的增删改查？ → **REST**（易于调试） │ ├─ TypeScript monorepo（前端+后端）？ │ └─ **tRPC**（端到端类型安全，无代码生成） │ ├─ 客户需要灵活查询？ │ ├─ 实时更新？ → **GraphQL 订阅** 或 **WebSockets** │ └─ 复杂的数据获取？ → **GraphQL**（避免过度获取） │ ├─ 移动/网络客户端？ │ ├─ 实体类型多？ → **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结构最佳实践（集合与资源端点） * 嵌套资源和操作端点 ** ** ### 分页、过滤和排序 **资源：** [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]() * 令牌桶算法（推荐，允许突发） * 固定窗口与滑动窗口 * 速率限制标头 (`X-RateLimit-*`) * 分级费率限制（免费、付费、企业） * 基于Redis的分布式限速 * 每用户、每端点和每 API 密钥策略 ** ** ## 导航：扩展资源 ### API 设计和最佳实践 * **[api-design-best-practices.md]()** \- 全面的API设计原则 * **[versioning-strategies.md]()** \- URL、标头和查询参数版本控制 * **[api-security-checklist.md]()** \- OWASP API 安全前 10 名 ### GraphQL 和 gRPC * **[graphql-patterns.md]()** \- 模式设计、解析器、N+1 查询、DataLoader * **gRPC 模式** \- 请参阅 [software-backend]() 了解协议缓冲区和服务定义 ### tRPC（TypeScript-First） * **[trpc-patterns.md]()** \- 端到端类型安全、过程、React Query 集成 * 何时使用 tRPC、GraphQL、REST * Auth中间件模式 * 使用 Next.js 进行服务器端渲染 ### OpenAPI 和文档 * **[openapi-guide.md]()** \- OpenAPI 3.1 规范、Swagger UI、Redoc * **模板：** [assets/openapi-template.yaml]() \- 完整的 OpenAPI 规范示例 ### Webhooks 和事件驱动的 API * **[webhook-patterns.md]()** \- Webhook 设计、交付保证、签名验证、重试策略、DLQ ### 实时 API * **[real-time-api-patterns.md]()** \- WebSockets、SSE、长轮询、gRPC 流、协议选择指南 ### API 测试 * **[api-testing-patterns.md]()** \- API 的合约测试、集成测试、负载测试、混沌测试 ### 可选：人工智能/自动化（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、序列化器、简单 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 或标头中的版本 **一般错误** |可怜的DX |具体错误代码+消息 **无速率限制标头** |客户不能退缩|包括 X-RateLimit-* **仅 URL 中的租户 ID** |伪造风险 |根据身份验证令牌进行验证 **泄漏抽象** |紧耦合|设计稳定合约 ** ** ## 可选：人工智能/自动化 > **注意**：人工智能工具可以提供帮助，但合同需要人工审核。 * **OpenAPI linting** — CI/CD 中的 Spectral、Redocly * **重大变更检测** — oasdiff 自动检查 * **SDK 生成** — 来自 OpenAPI 规范的更改 * **合同测试** — Pact、Dredd 自动化 ### 有界声明 * AI 生成的 OpenAPI 规范需要人工审核 * 自动弃用检测需要手动确认 * SDK生成需要类型验证 ** ** ## 外部资源请参阅 [data/sources.json]()： * 官方 REST、GraphQL、gRPC 文档 * OpenAPI/Swagger 工具和验证器 * API 设计风格指南（Google、Microsoft、Stripe） * 安全标准（OWASP API 安全 Top 10） * 测试工具（Postman、Insomnia、Paw） ** ** ## 相关技能该技能与其他专业技能结合使用时效果最佳： ### 后端开发 * **[software-backend]()** \- 生产后端模式（Node.js、Python、Java 框架） * 在实现 API 服务器基础设施时使用 * 涵盖数据库集成、中间件、错误处理 ### 安全与身份验证 * **[software-security-appsec]()** \- 应用程序安全模式 * 对于保护 API 端点至关重要 * 涵盖 OWASP 漏洞、身份验证流程、输入验证 ### 数据库和数据层 * **[data-sql-optimization]()** \- SQL 优化和数据库模式 * 对 API 性能至关重要（查询优化、索引） * 当API与关系数据库交互时使用 ### 测试与质量 * **[qa-testing-strategy]()** \- 测试策略和自动化 * API规范的合同测试 * API端点的集成测试 ### DevOps 和部署 * **[ops-devops-platform]()** \- 平台工程和部署 * API网关配置 * 用于 API 部署的 CI/CD 管道 ### 文档 * **[docs-codebase]()** \- 技术文档标准 * API参考文档结构 * 补充 OpenAPI 自动生成的文档 ### 架构 * **[software-architecture-design]()** \- 系统设计模式 * 具有API的微服务架构 * API网关模式、服务网格集成 ### 性能和可观察性 * **[qa-observability]()** \- 性能优化和监控 * API延迟监控、分布式追踪 * API端点的性能预算 ** ** ## 使用说明 **对于代理：** * 默认应用 RESTful 原则，除非用户请求 GraphQL/gRPC * 始终包含列表端点的分页 * 使用 RFC 9457 格式进行错误响应 * 在所有模板中包含身份验证（JWT 或 API 密钥） * 完整实现的参考框架特定模板 * 链接到相关资源以获得深入指导 **成功标准：** API 是可发现的、一致的、文档齐全的、安全的，并且正确遵循 HTTP/GraphQL 语义。 ** ** ## 时间敏感的建议如果用户询问“最佳”工具/框架、“最新”标准，或者某些内容在 2026 年是否仍然相关，请使用当前环境中可用的任何浏览/搜索工具进行快速网络搜索。如果网络访问不可用，请根据稳定的原则、状态假设（流量、延迟、团队技能、生态系统）进行回答，并避免夸大货币。

开发API设计

包含技能