jinjie0703 API Designer - 大厂级 RESTful & RPC 接口契约架构师
当用户需要设计新业务接口、规范前后端数据交互契约、生成 OpenAPI 3.0 (Swagger) 规范、或编写 TypeScript/Pydantic 类型模型时，严格执行以下 SOP。
⚙️ 第 0 步：环境检查（零外部依赖）
本技能使用的脚手架生成器仅依赖 Python 3.9+ 标准库，无需安装任何第三方包：
python --version
🚀 标准操作工作流 (SOP)
第 1 步：业务资源建模与动词映射 (Resource Modeling)
AI 将用户提出的业务需求抽象为标准的 RESTful 资源集合：
- 资源命名：统一使用复数名词及连字符（如
/api/v1/user-orders）； - 层级归属：子资源体现父子从属关系（如
/api/v1/orders/{order_id}/items）； - 动词规范：严禁在 URL 中出现
get_、create_动词，统一使用GET,POST,PUT,PATCH,DELETE。
第 2 步：统一响应体与分页契约设计
所有接口必须遵循大厂统一返回体结构：
{
"code": 0,
"msg": "success",
"data": {},
"trace_id": "req_8f9a2b"
}
- 分页规范：入参使用
page(从 1 起) 与page_size(默认 20)，返回体使用{ list, total, page, page_size, has_more }。
第 3 步：关键写操作注入幂等性与防御设计
针对支付、下单、转账等写操作：
- 在请求头中必须声明
X-Idempotency-Key防重令牌； - 明确指出 HTTP 状态码（如创建成功返回
201 Created，并发冲突返回409 Conflict，限流返回429 Too Many Requests）。
第 4 步：调用代码与契约脚手架生成器 (api_scaffold.py)
AI 将设计的 API 结构组装为 JSON 数据，调用脚本生成全套多端契约：
python .agents/skills/api_designer/scripts/api_scaffold.py \
--api-json api_definition.json \
--output-dir ./generated_api
脚手架自动生成：
openapi.yaml：标准 OpenAPI 3.0 / Swagger 接口规范；contracts.ts：前端开箱即用的 TypeScript 接口类型定义；schemas.py：后端直接可用的 Python Pydantic 请求/响应校验模型；mock_response.json：符合规范的 Mock 测试数据。
📐 输出规范
- 结构严谨、规范统一，符合 RESTful 行业最佳实践；
- 状态码与业务错误码严禁混用（HTTP 状态码表征传输层，JSON
code表征业务层）； - 涉及 URL 路径与字段名加粗显示。