RESTful API设计规范与最佳实践

RESTful API设计规范与最佳实践

一个好的API设计可以让前后端协作更加顺畅，让系统更易维护和扩展。RESTful是目前最流行的API设计风格，但很多开发者对REST的理解存在偏差。本文将介绍RESTful API的设计规范和实战经验。

一、URL设计规范

// 资源命名 - 使用名词复数
GET    /api/users           // 获取用户列表
GET    /api/users/123       // 获取单个用户
POST   /api/users           // 创建用户
PUT    /api/users/123       // 更新用户（全量）
PATCH  /api/users/123       // 更新用户（部分）
DELETE /api/users/123       // 删除用户

// 嵌套资源
GET    /api/users/123/orders       // 用户的订单
POST   /api/users/123/orders       // 为用户创建订单
GET    /api/users/123/orders/456    // 用户的特定订单

// 筛选、排序、分页
GET /api/users?status=active&sort=-created_at&page=1&per_page=20
GET /api/orders?amount_min=100&amount_max=1000&fields=id,amount,status

// 动作转为资源
POST /api/users/123/password/reset     // 重置密码
POST /api/orders/123/cancel            // 取消订单
POST /api/files/upload                  // 上传文件

二、响应格式规范

// 成功响应
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

// 列表响应（带分页）
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}

// 错误响应
{
  "code": 40001,
  "message": "参数验证失败",
  "errors": [
    { "field": "email", "message": "邮箱格式不正确" },
    { "field": "age", "message": "年龄必须大于0" }
  ]
}

三、状态码使用

// 2xx 成功
200 OK              // 成功
201 Created         // 创建成功
204 No Content      // 删除成功，无返回内容

// 4xx 客户端错误
400 Bad Request     // 参数错误
401 Unauthorized    // 未认证
403 Forbidden       // 无权限
404 Not Found       // 资源不存在
409 Conflict        // 资源冲突（如重复创建）
422 Unprocessable   // 参数验证失败
429 Too Many Requests // 请求频率超限

// 5xx 服务端错误
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable

四、版本控制与文档

// URL版本控制（推荐）
/api/v1/users
/api/v2/users

// API文档 - Swagger/OpenAPI
// openapi.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        200:
          description: 成功

好的API设计需要站在使用者的角度思考，保持一致性和可预测性。设计API时先写文档，让前端同学参与评审，再动手实现。记住：API是前后端的契约，一旦发布就要保持向后兼容。