REST API 设计：构建优雅的 Web 服务接口

RESTful API 是现代 Web 服务的标准接口设计风格。良好的 API 设计能提升开发效率、降低维护成本。本文系统讲解 REST API 设计原则与最佳实践。

一、REST 架构风格

REST（Representational State Transfer）是一种软件架构风格，核心原则包括：

资源：一切皆资源，通过 URI 标识。

统一接口：使用标准 HTTP 方法操作资源。

无状态：每个请求包含所有必要信息。

分层系统：客户端无需知道连接的是哪层服务器。

二、URL 设计规范

2.1 资源命名

# 推荐：使用名词复数
GET /users
GET /users/123
GET /users/123/orders

# 不推荐：使用动词
GET /getUsers
GET /getUserById?id=123

2.2 层级关系

# 一对多关系
GET /users/123/orders          # 用户的所有订单
GET /users/123/orders/456      # 特定订单

# 避免过深层级（建议不超过3层）
GET /orgs/1/depts/2/teams/3/users/4

2.3 查询参数

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

# 分页
GET /users?page=2&limit=20
GET /users?offset=40&limit=20

# 排序
GET /users?sort=created_at:desc
GET /users?sort=name:asc,age:desc

# 字段选择
GET /users?fields=id,name,email

# 搜索
GET /users?q=john

三、HTTP 方法使用

GET    /users       # 获取用户列表
GET    /users/123   # 获取单个用户
POST   /users       # 创建用户
PUT    /users/123   # 完整更新用户
PATCH  /users/123   # 部分更新用户
DELETE /users/123   # 删除用户

3.1 幂等性

幂等操作：多次执行结果相同。GET、PUT、DELETE 是幂等的，POST 不是。

# PUT 完整更新（幂等）
PUT /users/123
{
  "name": "张三",
  "email": "zhang@example.com",
  "age": 25
}

# PATCH 部分更新（非幂等）
PATCH /users/123
{
  "age": 26
}

四、状态码设计

# 成功响应
200 OK              # 成功
201 Created         # 创建成功
204 No Content      # 删除成功（无返回体）

# 客户端错误
400 Bad Request     # 请求参数错误
401 Unauthorized    # 未认证
403 Forbidden       # 无权限
404 Not Found       # 资源不存在
409 Conflict        # 资源冲突
422 Unprocessable   # 验证失败

# 服务端错误
500 Internal Error  # 服务器错误
503 Service Unavailable  # 服务不可用

五、响应格式设计

5.1 成功响应

{
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhang@example.com"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

5.2 列表响应

{
  "data": [
    {"id": 1, "name": "张三"},
    {"id": 2, "name": "李四"}
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5
  },
  "links": {
    "first": "/users?page=1",
    "prev": null,
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}

5.3 错误响应

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ]
  }
}

六、版本管理

6.1 URL 版本

/api/v1/users
/api/v2/users

6.2 Header 版本

GET /users
Accept: application/vnd.myapi.v2+json

七、认证与授权

# Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API Key
X-API-Key: your-api-key

# OAuth 2.0
Authorization: Bearer access_token

八、安全最佳实践

1. 使用 HTTPS 加密传输

2. 敏感数据脱敏处理

3. 实施速率限制

4. 输入验证与清理

5. 避免在 URL 中传递敏感信息

6. 记录访问日志，监控异常

九、总结

RESTful API 设计遵循简单、一致、可预测的原则。好的 API 设计应该是自解释的，让开发者无需翻阅文档就能理解如何使用。

设计原则总结：

1. 资源用名词，操作用 HTTP 方法

2. URL 简洁清晰，层级合理

3. 正确使用状态码

4. 统一响应格式

5. 做好版本管理

6. 注重安全性

本文链接：https://www.kkkliao.cn/?id=779 转载需授权！