【研发类-后端开发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.mdREST vs GraphQL vs tRPC决策树选择API类型时rest.md资源命名、HTTP方法、状态码设计REST API时response.md信封模式、错误格式、分页响应结构设计时graphql.mdSchema设计、使用场景、安全性考虑GraphQL时trpc.mdTypeScript monorepo、类型安全TS全栈项目versioning.mdURI/Header/Query版本控制API演进规划时auth.mdJWT、OAuth、Passkey、API Keys认证模式选择时rate-limiting.md令牌桶、滑动窗口API保护时documentation.mdOpenAPI/Swagger最佳实践文档编写时security-testing.mdOWASP 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.pyAPI端点验证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时考虑未来的变化和扩展使用限制仅当任务明确符合上述范围时使用此技能不要将输出视为环境特定验证、测试或专家审查的替代品如果缺少所需的输入、权限、安全边界或成功标准请停止并要求澄清