【后端 · API设计】RESTful API 设计原则与规范

资源的 URI：   /users/123
资源的表述：   {"id": 123, "name": "Alice", "email": "alice@example.com"}
状态转移：     DELETE /users/123  ->  资源从"存在"变为"不存在"

客户端（前端）          服务器（后端）
  React/Vue      <->    FastAPI/Django
  移动端 App      <->    API 服务
  第三方服务      <->    微服务

# 无状态（REST 推荐）
GET /users/123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# 有状态（传统 Session）
GET /users/123
Cookie: session_id=abc123  # 服务器需要记住这个 session

# 服务器响应头
Cache-Control: max-age=3600        # 缓存 1 小时
ETag: "abc123"                     # 资源版本标识

# 客户端条件请求
If-None-Match: "abc123"            # 资源未变化则返回 304

// HATEOAS 示例
{
  "id": 123,
  "name": "Alice",
  "links": [
    {"rel": "self",    "href": "/users/123",         "method": "GET"},
    {"rel": "update",  "href": "/users/123",         "method": "PATCH"},
    {"rel": "delete",  "href": "/users/123",         "method": "DELETE"},
    {"rel": "orders",  "href": "/users/123/orders",  "method": "GET"}
  ]
}

客户端 -> 负载均衡 -> API 网关 -> 认证服务 -> 业务服务 -> 数据库

# 正确：名词 + HTTP 方法表达操作
GET    /api/v1/users          # 获取用户列表
POST   /api/v1/users          # 创建用户
GET    /api/v1/users/123      # 获取用户
PUT    /api/v1/users/123      # 更新用户
DELETE /api/v1/users/123      # 删除用户

# 错误：URL 中包含动词
GET    /api/v1/getUsers
POST   /api/v1/createUser
DELETE /api/v1/deleteUser/123

POST   /api/v1/users/123/activate      # 激活用户
POST   /api/v1/orders/456/cancel       # 取消订单
POST   /api/v1/reports/export          # 导出报告
POST   /api/v1/auth/login              # 登录（动作，非资源）
POST   /api/v1/auth/logout             # 登出

# 正确
GET /users
GET /users/123
GET /products
GET /orders

# 避免
GET /user          # 单数不清晰：是获取一个还是列表？
GET /user/123      # 语义：/user 资源下的 123？

# 合理：用户 -> 订单（1 层嵌套）
GET /users/123/orders
GET /users/123/orders/456

# 过深：应扁平化
GET /users/123/orders/456/items/789/details

# 改为扁平设计
GET /items/789
GET /items?order_id=456
GET /orders/456/items

# 正确
GET /user-profiles
GET /order-items
GET /api/v1/user-accounts

# 避免
GET /user_profiles    # 下划线在某些字体中不易辨识
GET /userProfiles     # 驼峰不适合 URL
GET /UserProfiles     # 大写字母在 URL 中不规范

# 过滤
GET /users?status=active&role=admin

# 排序
GET /users?sort_by=created_at&order=desc

# 分页
GET /users?page=1&page_size=20

# 搜索
GET /users?keyword=alice

# 字段选择（减少响应体积）
GET /users?fields=id,name,email

# 组合
GET /users?status=active&sort_by=name&order=asc&page=1&page_size=10

# 获取列表
GET /api/v1/users?page=1&page_size=20 HTTP/1.1
Accept: application/json

# 获取单个资源
GET /api/v1/users/123 HTTP/1.1
Accept: application/json

# 响应
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60

{"id": 123, "name": "Alice", "email": "alice@example.com"}

POST /api/v1/users HTTP/1.1
Content-Type: application/json

{"name": "Bob", "email": "bob@example.com"}

# 响应
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/124

{"id": 124, "name": "Bob", "email": "bob@example.com", "created_at": "2026-05-26T10:00:00Z"}

PUT /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{"name": "Alice Updated", "email": "alice.new@example.com", "age": 26}

# 响应
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "Alice Updated", "email": "alice.new@example.com", "age": 26}

PATCH /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{"age": 27}

# 响应
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "Alice Updated", "email": "alice.new@example.com", "age": 27}

DELETE /api/v1/users/123 HTTP/1.1

# 响应（无返回体）
HTTP/1.1 204 No Content

# 或者返回删除的资源
HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "name": "Alice", "deleted": true}

201 Created 场景：
POST /users -> 创建成功 -> 返回新用户 + Location 头

202 Accepted 场景：
POST /reports/generate -> 提交生成任务 -> 返回任务 ID
GET /reports/tasks/456 -> 查询任务状态

204 No Content 场景：
DELETE /users/123 -> 删除成功 -> 无返回体

401 Unauthorized（未认证）：
  "你是谁？请先证明身份。"
  -> 缺少认证信息
  -> Token 无效或过期
  -> 客户端应重新登录

403 Forbidden（无权限）：
  "我知道你是谁，但你没有权限。"
  -> 认证通过，但权限不足
  -> 普通用户访问管理员接口
  -> 客户端不应重试

// 成功响应
{
  "code": 200,
  "message": "success",
  "data": { ... }
}

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

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {"id": 1, "name": "Alice"},
      {"id": 2, "name": "Bob"}
    ],
    "pagination": {
      "total": 100,
      "page": 1,
      "page_size": 20,
      "total_pages": 5
    }
  }
}

偏移分页（Offset Pagination）：
  GET /users?page=1&page_size=20
  GET /users?page=2&page_size=20
  优点：支持跳页
  缺点：深页性能差（OFFSET 100000 很慢）、数据变动导致错位

游标分页（Cursor Pagination）：
  GET /users?page_size=20
  GET /users?page_size=20&cursor=eyJpZCI6MjB9
  优点：性能稳定、无数据错位
  缺点：只能前后翻页，不能跳页

/api/v1/users      # v1 版本
/api/v2/users      # v2 版本（不兼容变更）

# v1 版本标记为 deprecated，设置过渡期
# 响应头：
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: </api/v2/users>; rel="successor-version"

# 用户 CRUD
GET    /api/v1/users                    # 用户列表（分页、过滤、排序）
POST   /api/v1/users                    # 创建用户
GET    /api/v1/users/{id}               # 获取用户详情
PATCH  /api/v1/users/{id}               # 更新用户信息
DELETE /api/v1/users/{id}               # 删除用户

# 用户子资源
GET    /api/v1/users/{id}/orders        # 用户的订单列表
GET    /api/v1/users/{id}/posts         # 用户的文章列表

# 用户动作
POST   /api/v1/users/{id}/activate      # 激活用户
POST   /api/v1/users/{id}/deactivate    # 停用用户
POST   /api/v1/users/{id}/reset-password # 重置密码

# 商品
GET    /api/v1/products                 # 商品列表
GET    /api/v1/products/{id}            # 商品详情
GET    /api/v1/products/{id}/reviews    # 商品评价

# 购物车
GET    /api/v1/cart                     # 获取购物车
POST   /api/v1/cart/items               # 添加商品到购物车
PATCH  /api/v1/cart/items/{id}          # 更新购物车商品数量
DELETE /api/v1/cart/items/{id}          # 从购物车移除

# 订单
GET    /api/v1/orders                   # 订单列表
POST   /api/v1/orders                   # 创建订单（下单）
GET    /api/v1/orders/{id}              # 订单详情
POST   /api/v1/orders/{id}/pay          # 支付订单
POST   /api/v1/orders/{id}/cancel       # 取消订单
POST   /api/v1/orders/{id}/confirm      # 确认收货