RESTful API 设计规范

良好的接口规范是前后端高效协作的基础。本文整理我们在商城、会员、园区租赁等项目中沉淀的一套 API 设计约定，新项目可直接沿用。

URL 设计

• 使用名词复数表示资源，路径中不出现动词：

GET    /api/v1/orders          # 订单列表
GET    /api/v1/orders/1001     # 查询指定订单
POST   /api/v1/orders          # 创建订单
PUT    /api/v1/orders/1001     # 更新订单
DELETE /api/v1/orders/1001     # 删除订单

• 多单词使用连字符（kebab-case）：/api/v1/vip-cards
• 层级表达从属关系，不超过两层：/api/v1/members/1001/orders
• 动作类操作无法映射为 CRUD 时，使用动词子路径：POST /api/v1/orders/1001/cancel

版本管理

• 路径版本 /api/v1/...，不兼容变更时升级版本号
• 旧版本保留至少 3 个月过渡期，并提前通知调用方

HTTP 方法与状态码

方法	语义	成功状态码
GET	查询资源	200
POST	创建资源	201
PUT	全量更新	200
DELETE	删除资源	204

常用错误状态码：

• 400 Bad Request：参数校验失败
• 401 Unauthorized：未登录或凭证失效
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 429 Too Many Requests：触发限流

统一响应结构

所有接口返回统一结构，业务错误不再使用 HTTP 状态码区分：

{
  "code": 0,
  "message": "ok",
  "data": { }
}

• code = 0 表示成功，非 0 为业务错误码
• message 为可直接展示给用户的提示文案
• data 为业务数据，无数据时返回 null

分页、过滤与排序

列表接口统一使用 query 参数：

GET /api/v1/orders?page=1&size=20&status=paid&sort=createdAt,desc

分页响应结构：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "page": 1,
    "size": 20,
    "total": 135
  }
}

错误码约定

• 业务错误码使用 5 位数字，按模块分段，例如：
  • 10xxx：通用错误
  • 20xxx：商城 / 订单
  • 30xxx：会员 / 储值
• 错误码必须有对应的文案表，前端根据 code 做针对性提示，兜底展示 message

小结

规范的价值在于"照做即可，不用每次讨论"。新项目接入时，建议把本文链接放进 README，并在代码评审中把接口规范作为检查项之一。