用途:该技能面向 API 设计的决策与原则,资料定位为 2025 年的 API 设计思路,强调学会思考而非照抄固定模式。它要求先查看内容地图,只读取与当前请求相关的文件。
主要内容按文件划分:api-style.md 提供 REST、GraphQL、tRPC 的决策树,用于选择 API 类型;rest.md 讲解资源命名、HTTP 方法与状态码;response.md 涉及封装模式、错误格式与分页;graphql.md 涉及 Schema 设计、适用场景与安全;trpc.md 面向 TypeScript monorepo 与类型安全;versioning.md 涵盖 URI、Header、Query 三类版本方式;auth.md 覆盖 JWT、OAuth、Passkey、API Keys 的认证模式选择;rate-limiting.md 涉及令牌桶与滑动窗口;documentation.md 介绍 OpenAPI/Swagger 最佳实践;security-testing.md 关注 OWASP API Top 10 与认证授权测试。
使用方式:设计 API 前先确认 API 消费方、为当前场景选定 API 风格、定义一致的响应格式、规划版本策略、评估认证需求、规划限流并确定文档方案。脚本 scripts/api_validator.py 用于 API 端点验证,命令为 python scripts/api_validator.py <project_path>。资料还列出相关技能:API 实现、数据结构、安全细节,但未提供其具体内容。
反模式:不要默认一切都用 REST;REST 端点不要用动词(如 /getUsers);不要返回不一致的响应格式;不要向客户端暴露内部错误;不要跳过限流。
限制:资料未提供适用范围、支持平台、收费、价格或实际效果等信息,暂未提供。