引言

RESTful API是现代Web服务的标准设计风格。本文介绍RESTful API的设计规范和最佳实践。

一、REST基础

1.1 REST原则

  1. 客户端-服务器：分离关注点
  2. 无状态：每个请求独立
  3. 可缓存：响应可被缓存
  4. 统一接口：标准化接口
  5. 分层系统：层次化架构
  6. 按需代码：可选，服务器可返回可执行代码

1.2 HTTP方法

1
2
3
4
5
GET     - 查询资源
POST    - 创建资源
PUT     - 更新资源（完整）
PATCH   - 更新资源（部分）
DELETE  - 删除资源

二、URL设计

2.1 命名规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 使用名词复数
GET /api/users
GET /api/products

# 资源嵌套
GET /api/users/123/orders
GET /api/posts/456/comments

# 使用小写字母和连字符
GET /api/user-profiles
GET /api/order-items

# 避免动词
❌ GET /api/getUsers
✅ GET /api/users

❌ POST /api/createUser
✅ POST /api/users

2.2 查询参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 分页
GET /api/users?page=1&size=20

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

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

# 搜索
GET /api/users?search=alice

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

三、请求示例

3.1 创建资源

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
POST /api/users HTTP/1.1
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com",
  "age": 25
}

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

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "age": 25,
  "created_at": "2022-12-28T14:15:00Z"
}

3.2 查询资源

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 查询列表
GET /api/users?page=1&size=10

# 响应
{
  "data": [
    {
      "id": 1,
      "name": "Alice"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 100
  }
}

# 查询单个
GET /api/users/123

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

3.3 更新资源

1
2
3
4
5
6
7
8
9
10
11
12
13
# PUT - 完整更新
PUT /api/users/123
{
  "name": "Alice Updated",
  "email": "alice.new@example.com",
  "age": 26
}

# PATCH - 部分更新
PATCH /api/users/123
{
  "name": "Alice Updated"
}

3.4 删除资源

1
2
3
4
DELETE /api/users/123

# 响应
HTTP/1.1 204 No Content

四、状态码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 2xx 成功
200 OK              # 成功
201 Created         # 创建成功
204 No Content      # 成功但无返回内容

# 3xx 重定向
301 Moved Permanently   # 永久重定向
302 Found              # 临时重定向
304 Not Modified       # 资源未修改

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

# 5xx 服务器错误
500 Internal Server Error  # 服务器错误
502 Bad Gateway           # 网关错误
503 Service Unavailable   # 服务不可用

五、错误处理

5.1 错误响应格式

1
2
3
4
5
6
7
8
9
10
11
12
{
  "error": {
    "code": 40001,
    "message": "用户名已存在",
    "details": [
      {
        "field": "username",
        "message": "该用户名已被注册"
      }
    ]
  }
}

5.2 验证错误

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "error": {
    "code": 42201,
    "message": "验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      },
      {
        "field": "age",
        "message": "年龄必须大于0"
      }
    ]
  }
}

六、版本控制

1
2
3
4
5
6
7
8
9
10
# 方式1：URL路径
GET /api/v1/users
GET /api/v2/users

# 方式2：请求头
GET /api/users
Accept: application/vnd.myapi.v1+json

# 方式3：查询参数
GET /api/users?version=1

七、安全性

7.1 认证

1
2
3
4
5
6
7
# Bearer Token
GET /api/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# API Key
GET /api/users
X-API-Key: your-api-key

7.2 HTTPS

1
2
# 强制使用HTTPS
# 避免敏感信息通过HTTP传输

7.3 限流

1
2
3
4
5
6
7
8
# 响应头
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640707200

# 超过限制
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

八、最佳实践

1
2
3
4
5
6
7
8
9
10
1. 使用HTTPS
2. 提供API文档（Swagger/OpenAPI）
3. 支持CORS
4. 实现限流
5. 版本控制
6. 使用JWT认证
7. 统一错误格式
8. 日志记录
9. 监控告警
10. 缓存支持

总结

RESTful API设计核心：

  1. 资源导向：URL表示资源
  2. HTTP方法：标准化操作
  3. 状态码：语义化响应
  4. 统一格式：请求和响应规范

参考资料