API 模式决策指南

解决什么问题

很多 API 设计会直接默认 REST，或只照搬资源命名，导致客户端需求不清、响应格式不一致、版本策略缺失，鉴权与限流常被后补。这个技能把 API 模式当作场景决策问题：先确认调用方，再在 REST、GraphQL、tRPC 之间选择，最后补齐响应结构、版本管理、鉴权、限流、文档与安全测试。

技能如何工作

它不按“固定规范”灌输，而是提供一份内容地图，按任务读取相关文件。核心能力包括：

• api-style.md：REST、GraphQL、tRPC 的决策路径。
• rest.md：资源命名、HTTP 方法、状态码。
• response.md：信封模式、错误格式、分页。
• auth.md 与 rate-limiting.md：JWT、OAuth、Passkey、API Keys、令牌桶、滑动窗口。
• security-testing.md：围绕 OWASP API Top 10 做鉴权与授权测试。

使用时可按检查清单推进：确认 API 调用方、选择风格、统一响应格式、规划版本、定义鉴权、添加限流、编写文档。资料也列出反模式，例如避免 /getUsers、响应格式不一致、暴露内部错误、跳过限流，并提供 scripts/api_validator.py 用于端点校验。

适用边界

它适合在接口设计、评审或迁移前建立决策依据，尤其适合 TypeScript 全栈、内部 API、开放平台等场景。它不是后端实现框架，也不替代数据库设计、安全加固或组织内部规范；如果项目已有强制标准，应以组织规范为准，用它补充决策理由和检查项。