名称: api-patterns 描述: API设计原则和决策制定。REST vs GraphQL vs tRPC 选择，响应格式，版本控制，分页。 允许工具: 读，写，编辑，全局，搜索 许可证: MIT 元数据: 版本: “1.0.0” 领域: 架构 触发词: API模式，REST，GraphQL，tRPC，版本控制，分页，响应格式 角色: 架构师 范围: 系统设计 输出格式: 代码 相关技能: api-design-principles, api-security-best-practices
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 monorepo，类型安全 | 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 <项目路径> |