# 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 方法使用

| 方法   | 用途                     | 幂等性 | 安全性 |
|--------|--------------------------|--------|--------|
| GET    | 获取资源                 | 是     | 是     |
| POST   | 创建资源                 | 否     | 否     |
| PUT    | 更新整个资源             | 是     | 否     |
| PATCH  | 部分更新资源             | 否     | 否     |
| DELETE | 删除资源                 | 是     | 否     |
| HEAD   | 获取资源元数据           | 是     | 是     |
| OPTIONS| 获取资源支持的通信选项   | 是     | 是     |

### 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)
- 错误响应示例:
```json
{
  "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架构](https://www.ruanyifeng.com/blog/2011/09/restful.html "作者： 阮一峰")