name: api-patterns description: API 设计原则和决策。REST vs GraphQL vs tRPC 选择、响应格式、版本化、分页。 allowed-tools: 读取、写入、编辑、全局搜索、文本搜索
API 模式
2025年的API设计原则和决策。 学会思考，而不是复制固定模式。
🎯 选择性阅读规则
只读取与请求相关的文件！ 检查内容地图，找到所需内容。
📑 内容地图
| 文件 | 描述 | 何时阅读 |
|---|---|---|
api-style.md |
REST vs GraphQL vs tRPC 决策树 | 选择API类型时 |
rest.md |
资源命名、HTTP方法、状态码 | 设计REST API时 |
response.md |
信封模式、错误格式、分页 | 响应结构 |
graphql.md |
模式设计、何时使用、安全 | 考虑GraphQL时 |
trpc.md |
TypeScript 单仓库、类型安全 | TS 全栈项目 |
versioning.md |
URI/头部/查询版本化 | API 进化规划 |
auth.md |
JWT、OAuth、Passkey、API 密钥 | 认证模式选择 |
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> |