RESTful 架构与最佳实践

什么是 RESTful

RESTful (Representational State Transfer) 是一种软件架构风格，用于设计网络应用程序的接口。它基于 HTTP 协议，使用标准的 HTTP 方法 (GET, POST, PUT, DELETE 等) 来操作资源。

RESTful 核心原则

1. 资源导向：将数据或服务抽象为资源
2. 统一接口：使用标准的 HTTP 方法
3. 无状态：每个请求包含所有必要信息
4. 可缓存：响应应明确是否可缓存
5. 分层系统：客户端无需知道是否直接连接服务器
6. 按需代码（可选）：可下载并执行客户端脚本

RESTful 最佳实践

1. 资源命名规范

• 使用名词而非动词表示资源
  • 好: /users
  • 不好: /getUsers
• 使用复数形式
  • 好: /products
  • 不好: /product
• 层级关系表达
  • /users/{userId}/orders

2. HTTP 方法使用

3. 状态码使用

• 2xx 成功
  • 200 OK - 常规成功
  • 201 Created - 资源创建成功
  • 204 No Content - 成功但无返回内容
• 3xx 重定向
  • 301 Moved Permanently
  • 304 Not Modified
• 4xx 客户端错误
  • 400 Bad Request - 请求错误
  • 401 Unauthorized - 未认证
  • 403 Forbidden - 无权限
  • 404 Not Found - 资源不存在
• 5xx 服务端错误
  • 500 Internal Server Error
  • 503 Service Unavailable

4. 版本控制

• URL 路径中: /v1/users
• 请求头中: Accept: application/vnd.myapi.v1+json

5. 过滤、排序和分页

• 过滤: /users?role=admin
• 排序: /users?sort=-createdAt,name (desc by createdAt, asc by name)
• 分页: /users?page=2&limit=20

6. 响应格式

• 使用 JSON 作为主要数据格式
• 包含自描述信息 (HATEOAS)
• 错误响应示例:

{
  "error": {
    "code": "invalid_param",
    "message": "Email format is invalid",
    "target": "email"
  }
}

7. 安全实践

• 使用 HTTPS
• 认证: OAuth2, JWT
• 输入验证
• 速率限制
• CORS 配置

8. 性能优化

• 支持条件请求 (ETag, Last-Modified)
• 部分响应 (字段选择)
• 压缩响应
• 缓存控制头

示例 API 设计

GET    /articles          - 获取文章列表
POST   /articles          - 创建新文章
GET    /articles/{id}     - 获取特定文章
PUT    /articles/{id}     - 更新整篇文章
PATCH  /articles/{id}     - 部分更新文章
DELETE /articles/{id}     - 删除文章
GET    /articles/{id}/comments - 获取文章评论

遵循这些最佳实践可以帮助您设计出更加规范、易用且安全的 RESTful API。

理解RESTful架构