api-engineering

API 工程

API 工程（api-engineering，兼容 slug: api）负责本技能描述范围内的定位、执行、验证和交接边界；旧短 slug 仅作兼容 alias/URL 主键，不作为规范技能名。

定位：把 API 从“能调通”收敛为“契约可验证、消费者可迁移、状态码可观测、失败可回滚”。先拿需求、消费者、版本、契约和线上证据，再设计 REST/GraphQL/gRPC/Event 边界；不凭记忆改公开契约。

快速总则

• API 是跨端契约，不是控制器函数；任何字段、状态码、错误 code、认证 scope、分页语义、事件 schema 改动都要查生产方、消费方、SDK、Mock、OpenAPI、网关、缓存、监控和发布回滚。
• 先定资源语义和失败语义，再写接口；REST 用资源和 HTTP 语义，GraphQL 用聚合和按需取数，gRPC 用强类型内网 RPC，Event/Webhook 用异步事实通知。
• OpenAPI/JSON Schema/Proto/GraphQL schema/AsyncAPI 是契约源；示例、Mock、typed clients、contract test 必须与真实响应同源或可校验。
• 新端点默认认证；资源 id、子资源 id、批量 id、GraphQL node id、事件订阅都要对象级授权，防 BOLA/IDOR。
• POST 创建、支付、扣减、状态流转、Webhook、AI tool action 必须有幂等键、重放防护、并发冲突处理和补偿查询。
• 破坏性变更必须版本化、双字段/双路由过渡、灰度、Deprecation/Sunset 或等价公告；内部 API 也要说明消费者和回滚点。
• 错误模型必须稳定：HTTP status、业务 code、Problem Details/type、字段级错误、request_id、重试语义不能漂移。
• 统一表示：id 格式、时间一律 ISO 8601/RFC 3339 + 时区、金额用最小货币单位或 decimal string、单位写入字段名/Schema、locale/language/currency 显式传递；枚举新增默认兼容，客户端必须容忍未知枚举。
• 证据不足先补证据；无法确认消费者时按公开破坏性变更处理，不硬删旧契约。

强制执行流程：需求 → 资源 → 契约 → 消费者 → 门禁

1. 需求拆解：先列业务目标、消费者、用户旅程、禁止项、读写频率、数据敏感级别、兼容范围、回滚要求和验收样本；缺消费者证据按公开 API 处理。
2. API 选型：必须说明 REST/GraphQL/gRPC/Event/Webhook/SSE 的选择理由；长耗时、最终一致、批量导入导出、回调结果默认评估 202 + operation resource 或事件化。
3. 资源建模：列资源、子资源、关系、动作、状态、所有者、权限边界；命令型动作优先转成资源状态流转，不能把控制器函数直接暴露成 API。
4. 状态机建模：涉及订单、任务、审批、支付、库存、AI tool action 时，必须列状态、事件、允许迁移、终态、非法迁移、补偿和并发冲突。
5. 契约草案：实现前产出 method/path 或 schema/operation、请求、响应、错误示例、分页/过滤/排序、权限 scope、幂等、限流和可观测字段。
6. 消费者对账：列前端、App、SDK、第三方、后台任务、BI、Webhook、Mock、文档和缓存使用矩阵；未确认消费者时不得删除或收紧契约。
7. 兼容判定：字段、枚举、错误、状态码、排序、分页、scope、limit/quota 任一变化都要判定兼容等级、迁移窗口、旧端策略和回滚点。
8. 契约门禁：OpenAPI/Schema/Proto/GraphQL/AsyncAPI 必须与 Mock、SDK、示例、contract test 和真实响应校验同源或可自动比对。
9. 测试交接：交给 tst 的最小包包括成功/边界/异常/权限/并发/重放/旧端/contract/灰度回滚场景。
10. 停止条件：无消费者清单、无契约草案、无错误模型、无权限边界、无兼容判定、无回滚点或安全边界不清时，不进入实现。

单技能开发闭环门禁

• 实现前门禁：每个新增/修改接口必须先落一页契约说明，至少包含 method/path、输入 DTO、输出 DTO、错误码、权限、分页/过滤/排序、幂等、兼容性、验证样本和回滚点；没有这页契约，不允许直接写 controller。
• Controller 门禁：controller 只做协议适配、认证上下文、DTO 解析、错误映射和 response envelope；业务规则、状态机、权限判断、DB model 更新、第三方副作用不得堆在 controller 函数里。
• DTO 门禁：请求 DTO、响应 DTO、内部实体、DB model、事件 payload 必须分层；禁止把请求体直接绑定内部实体后保存，禁止把 DB model 原样返回给外部 API。
• 输入门禁：未知字段、重复字段、大小写差异、空对象、超大 body/header、content-type 不匹配、数组超限、嵌套深度、非法 enum、时区/金额/单位都要有固定处理策略和测试。
• 输出门禁：响应只返回契约字段；默认不暴露内部 id、审计字段、租户字段、权限字段、软删字段、实验字段、第三方原始错误和调试信息。
• 错误门禁：同一失败只能有一个稳定 HTTP status + 业务 code；message/detail 可变，客户端只能依赖 code、status、retryable 和字段级错误。
• 权限门禁：先认证，再租户隔离，再对象级授权，再字段级授权，再动作授权；批量、导出、搜索、缓存、异步任务和 webhook 补偿查询也要走同一权限链。
• 写入门禁：任何写接口必须回答“谁可写、可写哪些字段、写入前状态、写入后状态、并发冲突、幂等重放、失败补偿、审计日志、回滚策略”。
• 兼容门禁：旧客户端、SDK、Mock、OpenAPI、文档、网关缓存、监控分桶、告警阈值和灰度开关必须同步；只改服务端实现不算完成。
• 验收门禁：不能只测 happy path；最少覆盖成功、字段缺失/null/零值、非法字段、权限失败、对象越权、并发、重复请求、旧端 contract、SDK/Mock 和回滚验证。
• 证据门禁：完成前必须给出契约 diff、真实请求/响应样本、schema 校验或 contract test、错误样本、权限样本、灰度指标/日志 request_id、回滚开关或旧版本路径。