Sky-Cube 接口协议定义Skill
适用场景
架构设计阶段,制定接口协议作为前后端并行开发与联调的契约。
执行步骤
- 确定风格与规范:REST(默认)/ GraphQL(复杂查询场景)。
- 定义通用约定:URL 规范、请求/响应包装、分页参数、时间格式。
- 设计错误码体系:分段(通用/业务/第三方),每码有语义与处理建议。
- 定义鉴权方案:Token 类型、传递方式、刷新机制。
- 定义版本策略:URL 版本(/v1/)或 Header 版本,全项目统一。
- 逐接口输出契约:方法、路径、入参、出参、错误码、示例。
规范要点
- URL 用名词复数(/orders),动作交给 HTTP 方法;避免动词 URL(如 /getOrder)。
- 响应包装结构统一:{ code, message, data, traceId },列表数据统一分页结构。
- 错误码分段管理:如 1xxx 通用、2xxx 用户域、3xxx 订单域,语义唯一不复用。
- 入参出参字段:snake_case(后端)/camelCase(前端映射)在文档中同时给出。
- 每个接口必须有成功示例与至少一个失败示例。
- 幂等接口(支付/提交类)必须设计幂等键(如 Idempotency-Key Header)。
输出模板
## 接口:创建订单 POST /v1/orders
请求头: Authorization: Bearer <token>, Idempotency-Key: <uuid>
请求体: { "items": [...], "address_id": 123 }
响应: { "code": 0, "message": "success", "data": { "order_no": "..." } }
错误码: 2001 库存不足 | 2002 地址无效
自检清单
- URL 命名规范统一
- 响应包装与分页结构统一
- 错误码分段且语义唯一
- 幂等接口有幂等键
- 每接口含成功与失败示例