api-patterns

API 模式

与消费方及部署约束相关的 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 实现	@[skills/backend-architect]
数据结构	@[skills/database-design]
安全细节	@[skills/api-security-best-practices]

---

✅ 决策清单

在设计 API 之前：

• 询问过用户关于 API 消费方的情况？
• 针对此上下文选择了 API 风格？（REST/GraphQL/tRPC）
• 定义了统一的响应格式？
• 规划了版本控制策略？
• 考虑了认证需求？
• 规划了速率限制？
• 定义了文档方案？

---

❌ 反模式

不要：

• 默认对所有场景使用 REST
• 在 REST 端点中使用动词（/getUsers）
• 返回不一致的响应格式
• 向客户端暴露内部错误
• 跳过速率限制

要：

• 根据上下文选择 API 风格
• 询问客户端需求
• 详尽地编写文档
• 使用适当的状态码

---

脚本

脚本	用途	命令
scripts/api_validator.py	本地启发式源码扫描（非 schema 验证）	python3 skills/api-patterns/scripts/api_validator.py <project_path>

何时使用

在定义新的端点契约、为已知消费方选择 REST/GraphQL/tRPC，或更改分页、错误、认证或兼容性行为时使用。对于现有契约内的 bug，保留该契约，除非任务授权进行更改。

输入与流程

记录消费方和已部署版本、预期载荷大小、访问规则、兼容性义务以及一个具体操作。阅读地图中的相关文件，比较现实可行的选择，然后指定请求/响应示例和拒绝情况。在构建时共享的类型并不能确保独立部署的客户端保持兼容。

完整示例

输入：一个公开的订单列表在客户端分页浏览时发生变化。选择一个有界分页大小和基于稳定 (created_at, id) 顺序的游标。定义下一个游标的格式、授权过滤条件以及记录被删除或游标无效时的行为。测试两个相同的时间戳和分页之间的插入。预期：在承诺的快照语义内没有重复的 ID；记录新插入的行是否可能出现。

限制

• Python 辅助脚本使用正则表达式和浅层 JSON/YAML 检查，最多扫描 15 个匹配文件。其输出是分类提示，而非 OpenAPI 验证、授权审计或部署批准。
• GraphQL 查询形状、tRPC 推断和 HTTP 方法名称并不强制实施资源授权或向后兼容性。
• 速率限制本身无法防止所有资源耗尽；大小、并发、时间和提供商成本边界取决于具体操作。
• 仅针对已授权的本地/测试目标，使用隔离账户和已定义的范围执行安全检查。