# 接口协议定义Skill

> 前后端接口协议规范制定方法(REST风格、错误码体系、鉴权与版本策略)。当需要制定接口规范文档,统一前后端与第三方集成的契约时使用。

- Skill: `sky-cube/skill-57` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sky-cube/skill-57`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sky-cube/skill-57/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Sky-Cube (https://skillmd.com/u/sky-cube)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sky-cube/skill-57

---

# 接口协议定义Skill

## 适用场景
架构设计阶段,制定接口协议作为前后端并行开发与联调的契约。

## 执行步骤
1. 确定风格与规范:REST(默认)/ GraphQL(复杂查询场景)。
2. 定义通用约定:URL 规范、请求/响应包装、分页参数、时间格式。
3. 设计错误码体系:分段(通用/业务/第三方),每码有语义与处理建议。
4. 定义鉴权方案:Token 类型、传递方式、刷新机制。
5. 定义版本策略:URL 版本(/v1/)或 Header 版本,全项目统一。
6. 逐接口输出契约:方法、路径、入参、出参、错误码、示例。

## 规范要点
- 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 命名规范统一
- [ ] 响应包装与分页结构统一
- [ ] 错误码分段且语义唯一
- [ ] 幂等接口有幂等键
- [ ] 每接口含成功与失败示例