RESTful API 设计规范：写出优雅的接口

好的 API 设计让前端开发事半功倍。遵循 RESTful 规范，能让你的接口清晰、一致、易维护。

RESTful 核心原则

1. 资源导向

一切皆资源，用名词表示：

# 好
GET /users
GET /users/123
GET /users/123/orders

# 不好
GET /getUsers
POST /createUser
GET /getUserOrders

2. 使用 HTTP 方法

GET    - 获取资源
POST   - 创建资源
PUT    - 更新资源（全量）
PATCH  - 更新资源（部分）
DELETE - 删除资源

3. 无状态

每个请求包含所有必要信息，不依赖服务器会话。

URL 设计规范

1. 使用复数名词

GET /users      # 好
GET /user       # 不好

2. 小写字母，连字符分隔

GET /user-profiles    # 好
GET /userProfiles     # 不好
GET /UserProfiles     # 不好

3. 避免深层嵌套

# 好
GET /users/123/orders
GET /orders?user_id=123

# 不好（超过 3 层）
GET /users/123/orders/456/items/789

4. 版本控制

# URL 版本（推荐）
GET /api/v1/users
GET /api/v2/users

# 请求头版本
GET /users
Header: Accept-Version: v1

响应格式规范

1. 统一响应结构

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

// 列表响应
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

// 错误响应
{
  "code": 1001,
  "message": "用户不存在",
  "data": null
}

2. 使用标准 HTTP 状态码

200 OK          - 成功
201 Created     - 创建成功
204 No Content  - 删除成功（无返回值）
400 Bad Request - 请求参数错误
401 Unauthorized - 未授权
403 Forbidden   - 禁止访问
404 Not Found   - 资源不存在
409 Conflict    - 资源冲突
422 Unprocessable Entity - 参数验证失败
500 Internal Server Error - 服务器错误

查询参数规范

1. 分页

GET /users?page=1&pageSize=20
GET /users?limit=20&offset=0

2. 排序

GET /users?sort=created_at&order=desc
GET /users?sort=-created_at  # -表示降序

3. 过滤

GET /users?status=active&role=admin
GET /products?price_min=100&price_max=500
GET /articles?tag=python&tag=django

4. 字段选择

GET /users/123?fields=id,name,email

请求响应示例

创建资源

POST /users
Content-Type: application/json

{
  "name": "张三",
  "email": "zhangsan@example.com",
  "password": "secure_password"
}

# 响应
HTTP/1.1 201 Created
Location: /users/123

{
  "code": 0,
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com"
  }
}

更新资源

# 全量更新
PUT /users/123
{
  "name": "李四",
  "email": "lisi@example.com"
}

# 部分更新
PATCH /users/123
{
  "name": "李四"
}

删除资源

DELETE /users/123

# 响应
HTTP/1.1 204 No Content

错误处理

1. 统一错误格式

{
  "code": 1001,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    },
    {
      "field": "password",
      "message": "密码长度至少 8 位"
    }
  ]
}

2. 常见错误码

{
  "1000": "参数错误",
  "1001": "资源不存在",
  "1002": "资源已存在",
  "2001": "未登录",
  "2002": "权限不足",
  "3001": "服务器内部错误"
}

安全规范

1. 认证授权

# 使用 Bearer Token
Authorization: Bearer <token>

# 或使用 API Key
X-API-Key: <your-api-key>

2. 速率限制

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

3. 敏感数据

• 密码永远不要返回
• 使用 HTTPS
• 敏感操作需要二次验证

文档规范

1. 使用 OpenAPI/Swagger

openapi: 3.0.0
info:
  title: 用户 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        200:
          description: 成功

2. 提供示例

每个接口都应该有请求和响应示例。

最佳实践清单

• 使用名词复数作为资源名
• 正确使用 HTTP 方法
• 返回合适的状态码
• 统一响应格式
• 支持分页、排序、过滤
• 提供详细的错误信息
• 使用版本控制
• 编写完整的 API 文档
• 实现认证和限流
• 使用 HTTPS

结语

好的 API 设计是技术实力的体现。遵循 RESTful 规范，让你的接口清晰、一致、易维护，前端开发者会感谢你的。

从现在开始，重新审视你的 API 设计吧！