一文详解REST风格
一文详解REST风格
-
- 一、REST风格的核心概念
-
- 1.1 什么是REST？
- 1.2 REST与HTTP的关系
- 二、REST风格的核心原则
-
- 2.1 资源为中心，URI表示资源
- 2.2 用HTTP方法表示操作类型
- 2.3 用HTTP状态码表示结果
- 2.4 响应格式标准化
-
- 2.4.1 成功响应
- 2.4.2 错误响应
- 2.5 无状态通信
- 三、RESTful API设计实战案例
-
- 3.1 资源定义
- 3.2 API设计清单
- 3.3 进阶设计：关联资源与过滤排序
-
- 3.3.1 关联资源（如用户的订单）
- 3.3.2 过滤、排序、分页
- 四、常见误区与最佳实践
-
- 4.1 误区1：过度追求“纯REST”
- 4.2 误区2：忽略幂等性设计
- 4.3 最佳实践
REST（Representational State Transfer，表现层状态转移）是一种被广泛采用的Web API架构风格，它并非协议或标准，而是一组设计原则，旨在通过HTTP协议天然特性构建简洁、可扩展、易于理解的API。
一、REST风格的核心概念
1.1 什么是REST？
REST由Roy Fielding在2000年的博士论文中提出，核心是**“以资源为中心”**，将一切数据（如用户、订单、商品）视为“资源”，通过HTTP方法对资源进行操作。
- 资源（Resource）：API操作的对象（如
/users表示用户资源集合，/users/1表示ID为1的用户）； - 表现层（Representation）：资源的展示形式（如JSON、XML，现代API多采用JSON）；
- 状态转移（State Transfer）：通过HTTP方法（GET/POST/PUT/DELETE）实现资源状态的改变，客户端无需了解服务器内部实现。
1.2 REST与HTTP的关系
REST并非独立于HTTP的技术，而是充分利用HTTP协议特性的设计风格：
- 用HTTP方法（GET/POST/PUT/DELETE）表示操作类型；
- 用HTTP状态码（200/201/404/500等）表示请求结果；
- 用HTTP头（如
Content-Type）表示数据格式； - 用URI标识资源（如
/products）。
简言之：REST是“如何正确使用HTTP”的设计指南。
二、REST风格的核心原则
遵循以下原则是设计RESTful API的关键，也是区分“REST风格”与“普通API”的核心。
2.1 资源为中心，URI表示资源
- URI应标识资源（名词），而非操作（动词）；
- 用复数表示资源集合（如
/users），单数表示单个资源（如/users/1）； - 避免在URI中包含版本号、操作动词（如
/getUser、/deleteOrder）。
| 错误URI | 正确URI | 说明 |
|---|---|---|
/getUser?id=1 | /users/1 | 避免动词，用名词+ID表示资源 |
/deleteOrder/1 | /orders/1 | 删除操作通过HTTP方法（DELETE）表示 |
/v1/users | /users（版本放HTTP头） | 避免URI包含版本号 |
2.2 用HTTP方法表示操作类型
HTTP方法本身具有语义，REST通过方法表示对资源的操作：
| HTTP方法 | 操作类型 | 示例URI | 说明 |
|---|---|---|---|
| GET | 查询资源 | /users | 查询用户列表（安全、幂等） |
| GET | 查询资源 | /users/1 | 查询ID为1的用户（安全、幂等） |
| POST | 创建资源 | /users | 新增用户（非幂等，多次调用可能创建多个） |
| PUT | 全量更新资源 | /users/1 | 更新用户全部信息（幂等） |
| PATCH | 部分更新资源 | /users/1 | 更新用户部分信息（如仅修改姓名，幂等） |
| DELETE | 删除资源 | /users/1 |