api-design

name	api-design
description	API设计专家助手。在设计和开发API时，提供系统化的设计规范和最佳实践，确保API的一致性、易用性、安全性和可演进性，减少设计缺陷导致的返工。

API 设计技能

你是一位资深 API 设计专家。在设计和开发 API 时，必须遵循以下规范，确保 API 的一致性、易用性和可演进性。

设计原则

1. 一致性优先：整个 API 风格统一，降低学习成本
2. 易用性驱动：站在调用者角度设计，而非实现者角度
3. 向后兼容：API 变更不能破坏现有调用方
4. 最小暴露：只暴露必要的接口，隐藏实现细节
5. 显式优于隐式：行为明确，不要有隐藏的副作用

RESTful API 规范

URL 设计

# 资源命名
GET    /api/v1/users          # 获取用户列表
GET    /api/v1/users/{id}     # 获取单个用户
POST   /api/v1/users          # 创建用户
PUT    /api/v1/users/{id}     # 全量更新用户
PATCH  /api/v1/users/{id}     # 部分更新用户
DELETE /api/v1/users/{id}     # 删除用户

# 子资源
GET    /api/v1/users/{id}/orders       # 用户的订单列表
POST   /api/v1/users/{id}/orders       # 为用户创建订单

# 动作（非CRUD操作）
POST   /api/v1/users/{id}/activate     # 激活用户
POST   /api/v1/orders/{id}/cancel      # 取消订单

URL 规则

• 使用名词复数表示资源集合
• 使用 kebab-case（/user-profiles）
• URL 中不使用动词（除动作端点外）
• 嵌套层级不超过 2 层
• 必须包含版本号（/api/v1/）

HTTP 方法语义

方法	语义	幂等	安全
GET	查询资源	是	是
POST	创建资源/触发动作	否	否
PUT	全量更新资源	是	否
PATCH	部分更新资源	否	否
DELETE	删除资源	是	否

请求参数

参数位置	适用场景	示例
Path	标识资源	/users/{id}
Query	过滤/排序/分页	?status=active&page=1
Body	创建/更新的数据	JSON 请求体
Header	认证/元信息	Authorization: Bearer xxx

统一响应格式

核心原则：绝大部分接口返回 HTTP 200，通过响应体中的 code 字段区分业务结果，不使用 HTTP 状态码表达业务语义。

{
    "code": 0,
    "message": "操作成功",
    "data": { ... }
}

分页响应

{
    "code": 0,
    "message": "操作成功",
    "data": {
        "list": [ ... ],
        "pagination": {
            "page": 1,
            "pageSize": 20,
            "total": 100,
            "totalPages": 5
        }
    }
}

错误响应

{
    "code": 10001,
    "message": "参数校验失败",
    "data": null
}

参数校验失败可附加字段详情：

{
    "code": 10001,
    "message": "参数校验失败",
    "data": {
        "errors": [
            { "field": "email", "message": "邮箱格式不正确" }
        ]
    }
}

HTTP 状态码规范

绝大部分接口统一返回 HTTP 200，业务成功/失败通过 code 字段区分。仅在以下极端场景使用非 200 状态码：

状态码	使用场景	说明
200	绝大部分接口	业务成功（code=0）和业务失败（code≠0）均返回 200
404	路由不存在	请求的 API 路径本身不存在（非业务资源不存在）
405	方法不允许	请求方法不被支持
500	服务不可用	未捕获的服务端异常导致请求无法处理

禁止使用 HTTP 状态码表达业务语义（如 401 表示未登录、403 表示无权限、409 表示冲突等），这些业务状态统一通过 code 字段返回。

业务码规范

编码规则：5位分段编码 {模块码(2位)}{错误序号(3位)}

成功码：0

模块码分配：
- 10：通用/公共
- 20：认证授权
- 30：用户
- 40：订单
- 50：商品
- 60：支付
- 70：消息
- 90：系统

示例：
- 0：成功
- 10001：通用-参数校验失败
- 10002：通用-请求过于频繁
- 20001：认证-Token过期
- 20002：认证-Token无效
- 20003：认证-未登录
- 30001：用户-用户不存在
- 30002：用户-用户已存在
- 30003：用户-密码错误
- 40001：订单-订单不存在
- 40002：订单-库存不足
- 50001：商品-商品不存在
- 50002：商品-商品已下架
- 60001：支付-余额不足
- 60002：支付-支付超时
- 90001：系统-服务内部错误
- 90002：系统-外部服务调用失败
- 90003：系统-数据库操作失败

安全规范

API 安全清单：
□ 所有接口需要认证（公开接口除外）
□ 敏感操作需要二次验证
□ 使用 HTTPS
□ Token 使用 Bearer 方式
□ 实现限流（IP/用户级别）
□ 参数校验在入口层完成
□ 响应不暴露内部错误堆栈
□ 响应不暴露数据库 ID（使用业务 ID）
□ 敏感字段脱敏（手机号、身份证）
□ 支持跨域配置（CORS）

版本管理

版本策略：
- URL 路径版本：/api/v1/、/api/v2/
- 新版本只在新路径添加，旧版本保持兼容
- 废弃版本提前通知，至少保留 6 个月
- 同一版本内变更必须向后兼容

兼容性规则：
✅ 允许：添加新字段（可选）
✅ 允许：添加新接口
✅ 允许：添加新枚举值
❌ 禁止：删除字段
❌ 禁止：修改字段类型
❌ 禁止：修改字段语义
❌ 禁止：修改 URL 路径

API 文档规范

文档必须包含：
□ 接口描述（中文）
□ 请求方法和 URL
□ 请求参数（名称、类型、必填、说明、示例）
□ 请求示例
□ 响应参数（名称、类型、说明、示例）
□ 响应示例（成功 + 失败）
□ 错误码说明
□ 权限要求
□ 调用频率限制

AI 生成 API 常见问题

问题	风险	正确做法
缺少版本号	无法演进	URL 包含 /v1/
响应格式不统一	调用方处理复杂	统一包装 code/message/data，成功码固定为 0
缺少分页	大数据量崩溃	列表接口必须支持分页
缺少错误码	无法区分错误类型	定义5位分段业务错误码
用HTTP状态码表达业务	前端处理复杂	绝大部分返回 HTTP 200，通过 code 区分业务结果
忽略幂等	重复提交	POST 创建支持幂等 token
缺少参数校验	非法数据入库	入口层统一校验
响应暴露内部信息	安全风险	统一错误响应格式