RESTful 开发规范

RESTful API 核心概念与开发规范

REST（Representational State Transfer，表述性状态转移）不是一种技术，而是一种设计风格，核心是资源（Resource） 为中心，通过HTTP方法对资源进行操作。以下是完整且实用的开发规范：

1. 核心原则

• 资源为中心：API命名以名词（资源）为核心，而非动词。比如用户资源用/users，而非/getUsers。
• HTTP方法语义化：用HTTP方法表达对资源的操作，而非在URL中体现操作。

  HTTP方法	含义	典型场景
  GET	获取资源	查询用户列表、单个用户信息
  POST	创建资源	新增用户、提交订单
  PUT	全量更新资源	替换整个用户信息
  PATCH	部分更新资源	仅修改用户的手机号
  DELETE	删除资源	删除某个用户

• 无状态：每个请求必须包含所有必要信息，服务器不存储客户端状态（如会话），便于扩展。

2. URL设计规范

（1）资源命名

• 用复数名词表示资源集合（行业通用惯例）：
  ✅ /users（用户列表）、/orders（订单列表）
  ❌ /user、/order
• 嵌套资源用/分隔（表示从属关系）：
  ✅ /users/123/orders（ID为123的用户的所有订单）
  ❌ /userOrders?userId=123
• 避免冗余：
  ✅ /products
  ❌ /api/products/api（重复api）、/getProducts（包含动词）

（2）版本控制

API迭代时需兼容旧版本，推荐在URL中显式指定版本：
✅ /v1/users、/v2/orders
（也可通过HTTP请求头Accept: application/vnd.company.v1+json实现，URL方式更直观）

（3）过滤、排序、分页

通过查询参数实现，而非修改URL路径：

• 过滤：/users?status=active（查询活跃用户）
• 排序：/users?sort=name&order=desc（按名称降序）
• 分页：/users?page=2&size=10（第2页，每页10条）
• 字段筛选：/users?fields=id,name,email（仅返回指定字段）

3. HTTP状态码规范

返回语义化的状态码，让客户端快速判断请求结果：

状态码	类别	典型场景
200	成功	GET/PUT/PATCH请求成功
201	创建成功	POST创建资源成功
204	无内容	DELETE删除资源成功
400	客户端错误	请求参数格式错误
401	未授权	缺少token或token无效
403	禁止访问	token有效但无权限
404	资源不存在	请求的/users/999不存在
405	方法不允许	对/users发DELETE请求
500	服务器错误	后端代码异常

4. 响应格式规范

返回统一的JSON格式，便于客户端解析，示例如下：

（1）成功响应（200）

{
  "code": 0,        // 自定义业务码（0表示成功）
  "message": "success",
  "data": {         // 业务数据（单个资源/列表）
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "timestamp": 1735689600000  // 请求时间戳（毫秒）
}

（2）列表响应（带分页）

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [       // 数据列表
      {"id": 1, "name": "张三"},
      {"id": 2, "name": "李四"}
    ],
    "pagination": {  // 分页信息
      "page": 1,
      "size": 10,
      "total": 200,
      "pages": 20
    }
  },
  "timestamp": 1735689600000
}

（3）错误响应（400/401等）

{
  "code": 40001,     // 自定义错误码（区分具体错误）
  "message": "请求参数错误：手机号格式不正确",
  "details": [       // 可选：详细错误信息
    {
      "field": "phone",
      "error": "手机号必须为11位数字"
    }
  ],
  "timestamp": 1735689600000
}

5. 其他最佳实践

• 请求头规范：
  • 传递token：Authorization: Bearer {token}（Bearer认证）
  • 指定数据格式：Content-Type: application/json
• 幂等性：GET/PUT/DELETE请求需保证幂等（多次调用结果一致），POST不保证（避免重复创建）。
• 命名风格：URL用蛇形（snake_case） 或短横线（kebab-case），避免驼峰：
  ✅ /user_orders、/user-orders
  ❌ /userOrders
• 文档化：用Swagger/OpenAPI自动生成API文档，便于前后端协作。