关于
API 设计原则与决策方法。REST vs GraphQL vs tRPC 选型、响应格式、版本控制、分页。
name: api-patterns description: "API 设计原则与决策。REST vs GraphQL vs tRPC 选择、响应格式、版本控制、分页。" risk: unknown source: community date_added: "2026-02-27"
API 模式
API 设计原则与 2025 年的决策指南。 学会思考，而非照搬固定模式。
选择性阅读规则
仅阅读与请求相关的文件！ 查看内容地图，找到你需要的内容。
内容地图
| 文件 | 描述 | 何时阅读 |
|------|------|----------|
| api-style.md | REST vs GraphQL vs tRPC 决策树 | 选择 API 类型时 |
| rest.md | 资源命名、HTTP 方法、状态码 | 设计 REST API 时 |
| response.md | 信封模式、错误格式、分页 | 响应结构设计时 |
| graphql.md | Schema 设计、使用场景、安全性 | 考虑 GraphQL 时 |
| trpc.md | TypeScript monorepo、类型安全 | TS 全栈项目时 |
| versioning.md | URI/Header/Query 版本控制 | API 演进规划时 |
| auth.md | JWT、OAuth、Passkey、API Keys | 认证模式选择时 |
| rate-limiting.md | 令牌桶、滑动窗口 | API 保护时 |
| documentation.md | OpenAPI/Swagger 最佳实践 | 文档编写时 |
| security-testing.md | OWASP API Top 10、认证/授权测试 | 安全审计时 |
相关技能
| 需求 | 技能 |
|------|------|
| API 实现 | @[skills/backend-development] |
| 数据结构 | @[skills/database-design] |
| 安全细节 | @[skills/security-hardening] |
决策清单
设计 API 之前：
- [ ] 询问用户 API 的消费者是谁？
- [ ] 为当前上下文选择了 API 风格？（REST/GraphQL/tRPC）
- [ ] 定义了一致的响应格式？
- [ ] 规划了版本控制策略？
- [ ] 考虑了认证需求？
- [ ] 规划了速率限制？
- [ ] 确定了文档方案？
反模式
不要：
- 对所有场景默认使用 REST
- 在 REST 端点中使用动词（/getUsers）
- 返回不一致的响应格式
- 向客户端暴露内部错误
- 跳过速率限制
应该：
- 根据上下文选择 API 风格
- 询问客户端需求
- 充分编写文档
- 使用适当的状态码
脚本
| 脚本 | 用途 | 命令 |
|------|------|------|
| scripts/api_validator.py | API 端点验证 | python scripts/api_validator.py <project_path> |
何时使用
此技能适用于执行概述中描述的工作流或操作。
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为特定环境验证、测试或专家审查的替代品。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停下来寻求澄清。
