玉衡 (yuheng-api-design) · API 设计与契约治理
一、定位
玉衡 是 API 设计与契约治理 skill。把"接口设计"从"写完代码补文档"反转为 API-first：
先定契约、再评审、后实现、终验一致。核心价值在于让接口可评审、可测试、可治理，尤其适合
微服务改造与金融系统接口标准化。
二、何时使用
- API 设计 / 接口设计 / 接口规范 / 接口文档
- RESTful 设计 / GraphQL 选型 / OpenAPI / Swagger
- 接口契约 / 契约测试 / 接口治理 / 接口版本管理
- 微服务接口定义 / 跨团队接口对齐 / API 评审
三、前置信息
| 输入 | 说明 | 缺失时 |
|---|---|---|
| 业务需求 | 接口要服务的业务场景与调用方 | 问一个阻塞性问题 |
| 技术栈 | 语言/框架（影响 OpenAPI 生成方式） | 默认通用，实现时再定 |
| 治理基线 | 公司/团队现有接口规范（可选） | 默认采用通用 REST 最佳实践 |
四、工作流（agent 执行）
步骤 1 资源建模 : 从业务名词识别核心资源（Resource），定义资源层级与关系。
避免"动词式 URI"，把动作建模为资源操作或子资源。
步骤 2 风格决策 : REST vs GraphQL 二选一（读多写少/客户端多样 → GraphQL；CRUD 为主 → REST）。
明确分页、幂等、错误码、鉴权、限流策略。
步骤 3 契约编写 : 产出 OpenAPI 3.x 文档（YAML/JSON），字段含描述、类型、校验、示例。
GraphQL 则产出 Schema（SDL）。
步骤 4 接口评审 : 按下方"评审清单"逐条过，标记 阻断/建议/通过。
步骤 5 契约测试 : 用契约测试（Pact/Spring Cloud Contract/OpenAPI 校验）固化契约，
产出可被 CI 执行的用例。
步骤 6 版本治理 : 定版本策略（URI /v1 /v2 或 Header），登记 breaking change 清单。
步骤 7 交付 : 输出 OpenAPI 文档 + 治理规范 + 评审记录。
五、接口评审清单（必过）
- 资源命名：名词复数、层级清晰、无动词 URI。
- HTTP 语义：GET/POST/PUT/PATCH/DELETE 使用正确，幂等性明确（PUT/DELETE 幂等，POST 非幂等）。
- 错误码统一：业务错误码与 HTTP 状态码映射清晰，错误响应体结构统一。
- 分页与过滤：统一分页参数（limit/offset 或 cursor），过滤/排序可扩展。
- 安全：鉴权方式、敏感字段脱敏、输入校验、防越权（水平/垂直）。
- 版本兼容：新增字段不破坏旧客户端（向后兼容），breaking change 有迁移路径。
- 文档完整：每个字段有描述、类型、示例，无"裸字段"。
六、质量门控
- 契约必须先于实现冻结，实现与契约不一致必须改其一并留痕。
- 每个接口必须有明确的错误码与鉴权声明，禁止"裸奔"接口。
- 分页/幂等/版本策略三项必须显式声明，不能默认省略。
七、输出格式
# API 设计文档
接口资源总览 / 风格决策说明（REST/GraphQL + 理由）
## OpenAPI 契约（完整 YAML 或链接）
## 评审记录（阻断项/建议项/通过项）
## 契约测试用例清单
## 版本与 breaking change 登记
八、目录
references/rest-best-practices.md— REST 命名/状态码/幂等/分页最佳实践references/openapi-guide.md— OpenAPI 3.x 编写要点references/review-checklist.md— 完整评审清单与反模式
九、免责声明
本 skill 产出的是设计规范与契约，具体落地须结合团队技术栈与既有规范，不替代架构评审。
