用途:在定义新接口契约、为已知消费方选择 REST/GraphQL/tRPC,或调整分页、错误、鉴权与兼容性行为时,按消费方与部署约束做 API 设计决策,而非套用固定模式。
主要能力:内容按文件组织,可按需选择性阅读。api-style.md 提供 REST 与 GraphQL、tRPC 的决策树;rest.md 讲资源命名、HTTP 方法与状态码;response.md 讲信封模式、错误格式与分页;graphql.md 讲 schema 设计与安全;trpc.md 面向 TypeScript 全栈单仓;versioning.md 讲 URI/Header/Query 版本策略;auth.md 覆盖 JWT、OAuth、Passkey、API Key;rate-limiting.md 讲令牌桶与滑动窗口;documentation.md 讲 OpenAPI/Swagger 实践;security-testing.md 对照 OWASP API Top 10 做鉴权与授权测试。
使用方式:先记录消费方与已部署版本、预期负载大小、访问规则、兼容义务和一个具体操作,再阅读相关内容,比较现实选择,给出请求/响应示例与拒绝场景。辅助脚本用于本地启发式源码扫描:python3 skills/api-patterns/scripts/api_validator.py <project_path>。
适用场景:新接口契约设计、API 风格选型、分页与错误约定变更、版本演进规划、鉴权与限流方案选择。限制:该脚本最多用正则与浅层 JSON/YAML 检查扫描 15 个匹配文件,输出仅为分类提示,不是 OpenAPI 校验、授权审计或部署批准;GraphQL 查询形状、tRPC 推断与 HTTP 方法名本身不保证资源授权或向后兼容;限流无法独自防止资源耗尽。安全测试仅限授权的本地/测试目标。