后端接口的 “隐形契约”：RESTful API 设计规范

在后端开发中，API 不仅是前后端交互的桥梁，更是团队协作的 “隐形契约”—— 一套清晰的 RESTful API 设计规范，能让接口具备可读性、可扩展性和一致性，减少沟通成本。反之，混乱的 API 设计会导致接口难以维护，成为系统迭代的 “绊脚石”。

RESTful API 的核心原则

REST（Representational State Transfer）不是协议或标准，而是一种设计风格，核心原则包括：

• 资源为中心：URL 描述资源（如/users而非/getUserList）
• 动词表操作：用 HTTP 方法表示操作（GET 查询、POST 创建、PUT 更新、DELETE 删除）
• 无状态：每个请求必须包含所有必要信息，服务器不存储客户端状态
• 可缓存：响应应明确是否可缓存，提升性能

实战设计规范

1. URL 命名：资源优先，拒绝动词

正确示例：

• GET /users：获取用户列表
• GET /users/123：获取 ID 为 123 的用户
• POST /users：创建新用户
• PUT /users/123：全量更新用户 123
• PATCH /users/123：部分更新用户 123（如只改手机号）
• DELETE /users/123：删除用户 123

错误示例：

• GET /getUserList（URL 包含动词）
• POST /deleteUser?id=123（用 POST 做删除操作）
• GET /user/123/orders（子资源合理，但避免过深嵌套，建议GET /orders?userId=123）

2. 参数与响应：清晰且一致

查询参数规范：

• 分页参数：?page=1&size=20（页码从 1 开始，size 指定每页条数）
• 排序参数：?sort=createTime,desc&sort=name,asc（按创建时间降序、姓名升序）
• 过滤参数：?status=active&role=admin（过滤状态为活跃的管理员）
• 搜索参数：?q=keyword（全文搜索）

响应格式规范：

统一响应体结构，包含状态码、消息和数据：

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  },
  "timestamp": 1690000000000
}

// 列表响应（带分页）
{
  "code": 200,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "size": 20
  }
}

// 错误响应
{
  "code": 400,
  "message": "参数错误：手机号格式不正确",
  "details": ["手机号必须为11位数字"],
  "timestamp": 1690000000000
}

3. 状态码使用：遵循 HTTP 语义

• 2xx：成功（200 OK - 通用成功，201 Created - 创建成功，204 No Content - 删除成功无返回）
• 4xx：客户端错误（400 Bad Request - 参数错误，401 Unauthorized - 未认证，403 Forbidden - 权限不足，404 Not Found - 资源不存在，409 Conflict - 资源冲突如重复创建）
• 5xx：服务器错误（500 Internal Server Error - 服务器异常，503 Service Unavailable - 服务暂时不可用）

避坑指南

• 避免过度 RESTful：不是所有接口都必须严格遵循 REST，如复杂查询、批量操作可适当灵活（如POST /users/batch-delete）
• 版本兼容：参数新增时设为可选，响应新增字段不影响旧客户端
• 文档同步：API 设计变更后，务必更新 Swagger 等文档，避免 “接口与文档两张皮”