【研发类-后端开发Skills】api-patterns 技能
API设计原则和决策制定。REST vs GraphQL vs tRPC选择、响应格式、版本控制、分页。
技能概述
api-patterns 技能是一个专注于API设计原则和决策制定的技能。它帮助开发者学习如何思考API设计，而不是简单地复制固定模式。该技能提供了REST、GraphQL和tRPC之间的选择决策树，以及响应格式、版本控制、分页等最佳实践。
下载地址：https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/api-patterns
核心原则
重要理念：学会思考，而不是复制固定模式。每个API设计决策都应该基于具体上下文和需求。
内容地图
该技能包含多个专题文件，按需阅读：
| 文件 | 描述 | 何时阅读 |
|---|---|---|
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之前，确保完成以下检查：
- 询问用户关于API消费者的情况
- 为当前上下文选择API风格（REST/GraphQL/tRPC）
- 定义一致的响应格式
- 规划版本控制策略
- 考虑身份验证需求
- 规划速率限制
- 定义文档方法
反模式警告
不要做：
- 默认所有情况都使用REST
- 在REST端点中使用动词（/getUsers）
- 返回不一致的响应格式
- 向客户端暴露内部错误
- 跳过速率限制
应该做：
- 根据上下文选择API风格
- 询问客户端需求
- 彻底编写文档
- 使用适当的状态码
相关技能
| 需求 | 技能 |
|---|---|
| API实现 | @[skills/backend-development] |
| 数据结构 | @[skills/database-design] |
| 安全细节 | @[skills/security-hardening] |
可用脚本
| 脚本 | 用途 | 命令 |
|---|---|---|
scripts/api_validator.py | API端点验证 | python scripts/api_validator.py <project_path> |
使用场景
场景1：选择API风格
当需要决定使用REST、GraphQL还是tRPC时，参考api-style.md中的决策树，根据项目特点、团队技能和客户端需求做出选择。
场景2：设计REST API
在设计RESTful API时，参考rest.md了解资源命名规范、HTTP方法正确使用和状态码最佳实践。
场景3：规划API版本控制
当API需要演进和版本管理时，参考versioning.md了解URI、Header和Query版本控制的优缺点。
最佳实践
- 上下文优先：始终根据具体上下文做决策，不要盲目套用模式
- 一致性：在整个API中保持一致的命名、格式和行为
- 文档化：为所有端点提供清晰的文档
- 安全性：从一开始就考虑认证、授权和速率限制
- 可演进性：设计API时考虑未来的变化和扩展
使用限制
- 仅当任务明确符合上述范围时使用此技能
- 不要将输出视为环境特定验证、测试或专家审查的替代品
- 如果缺少所需的输入、权限、安全边界或成功标准，请停止并要求澄清