用途:为 REST 与 GraphQL 等 API 提供契约设计规范,帮助统一资源形态、版本策略与错误响应格式。
主要能力:按 7 个类别组织 14 条规则,每条规则对应 rules/ 下的独立文件并按需加载。API 框架类含 REST 约定、资源建模、OpenAPI 3.1 规范;版本化类含 URL 路径版本(/api/v1/ 前缀)与请求头版本(X-API-Version、内容协商);错误处理类含面向智能体的 RFC 9457 扩展(retryable、error_category、内容协商、token 效率);GraphQL 类含 Strawberry code-first、DataLoader、权限类与订阅;gRPC 类含 Protobuf 服务、流式与拦截器、重试退避;流式类含 SSE 端点与 WebSocket 双向通信、心跳与背压;集成类含 WhatsApp、Telegram 等消息平台与 Payload CMS 模式。
关键决策:公开 API 用 URL 路径版本化;资源名用复数名词与 kebab-case;大数据集用游标分页;错误用 application/problem+json 的 RFC 9457 格式;支持窗口为当前加前一版本;弃用至少提前 3 个月通知、6 个月后下线;GraphQL 用 DataLoader 防 N+1;SSE 每 30 秒保活,WebSocket 每 30 秒 ping-pong;异步生成器用 aclosing() 清理资源。
使用方式:按需查阅对应 rules/ 文件;房屋政策与工作配置见 references/ork-delta.md,完整实现示例见 examples/fastapi-problem-details.md,OpenAPI 模板见 assets/openapi-template.yaml,测试用例见 test-cases.json。
限制:RFC 9457 基础格式、FastAPI 异常处理接线、Pydantic 422 映射、弃用与 Sunset 头机制等上游内容仅提供链接,不在本技能内重述;具体安装命令与收费信息暂未提供。