【研发类-后端开发Skills】api-patterns 技能

📅 发布时间：2026/7/15 20:37:15 👁 浏览次数：

【研发类-后端开发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时考虑未来的变化和扩展

使用限制

仅当任务明确符合上述范围时使用此技能
不要将输出视为环境特定验证、测试或专家审查的替代品
如果缺少所需的输入、权限、安全边界或成功标准，请停止并要求澄清