RESTful 规范
一、什么是 RESTful?
RESTful 是一种基于 REST 架构风格设计 Web API 的方式。
REST 的全称是 Representational State Transfer(表述性状态转移),由 Roy Fielding 在 2000 年的博士论文中提出。
在 "RESTful" 这个词中,-ful 是一个英语后缀(suffix),源自单词 "full"。
它的主要作用是将名词转化为形容词,表示“充满……的”、“具有……性质的”或“符合……特征的”。
具体含义
- REST 是名词,指“表述性状态转移”这种架构风格。
- -ful 加在后面,构成形容词 RESTful,意思是“符合 REST 原则的”或“具有 REST 风格的”。
RESTful 并不是一种协议,也不是严格的技术标准,而是一组架构设计约束和原则。
它的核心思想是:把服务端的数据和功能抽象为资源,通过统一的接口(通常是 HTTP)对资源进行操作。
例如,一个用户管理系统:
传统的 RPC 风格 API:
GET /getUser?id=100
POST /createUser
POST /updateUser
POST /deleteUser
RESTful 风格 API:
GET /users/100
POST /users
PUT /users/100
DELETE /users/100
区别在于:
- RPC 风格强调动作,例如
getUser、deleteUser。 - RESTful 风格强调资源,例如
/users/100,通过 HTTP Method 表达操作。
二、RESTful 的核心设计规范
1. URL 表示资源,使用名词而不是动词
RESTful 的 URL 应该描述资源,而不是具体的操作。
例如:
GET /users
GET /users/100
GET /users/100/orders
GET /orders/200
推荐:
/users
/orders
/products
不推荐:
/getUsers
/createOrder
/deleteProduct
通常使用复数名词,例如 /users、/orders,这是一种常见约定,并非 REST 的强制要求。
2. 使用 HTTP Method 表示操作
常见的 HTTP 方法:
| HTTP Method | 含义 | 示例 |
|---|---|---|
| GET | 查询资源 | GET /users/100 |
| POST | 创建资源或提交处理请求 | POST /users |
| PUT | 创建或整体替换指定资源 | PUT /users/100 |
| PATCH | 部分更新资源 | PATCH /users/100 |
| DELETE | 删除资源 | DELETE /users/100 |
例如:
GET /users/100
表示查询 ID 为 100 的用户。
POST /users
Content-Type: application/json
{
"name": "Tom",
"age": 20
}
表示创建用户。
PATCH /users/100
Content-Type: application/json
{
"age": 21
}
表示修改用户的年龄。
3. 正确使用 HTTP 状态码
RESTful API 应通过 HTTP 状态码表达请求的处理结果。
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 OK | 请求成功 | 查询、更新成功 |
| 201 Created | 创建成功 | 创建用户、订单 |
| 202 Accepted | 已接受处理 | 异步任务提交 |
| 204 No Content | 成功但无响应体 | 删除成功 |
| 400 Bad Request | 请求有误 | 参数格式错误 |
| 401 Unauthorized | 未认证 | 未登录、Token 无效 |
| 403 Forbidden | 无权限 | 没有访问权限 |
| 404 Not Found | 资源不存在 | 用户不存在 |
| 409 Conflict | 资源状态冲突 | 版本冲突 |
| 500 Internal Server Error | 服务端错误 | 服务器内部异常 |
例如,查询不存在的用户:
GET /users/999
响应:
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"code": "USER_NOT_FOUND",
"message": "User not found"
}
注意:不建议所有请求都返回 HTTP 200,然后仅使用业务字段表示错误。
因为这样会削弱 HTTP 状态码本身的语义,影响客户端处理、日志分析和监控。
4. 无状态(Stateless)
这是 REST 架构的重要约束。
服务端不应依赖之前请求保存的客户端会话状态,每次请求都应包含处理该请求所需的上下文信息。
例如:
GET /users/100
Authorization: Bearer eyJhbGciOi...
每次请求携带认证信息,服务端能够独立处理请求。
需要注意:
- 无状态不等于服务端不能保存数据。
- 服务端当然可以保存用户信息、订单、数据库记录。
- 无状态强调的是请求处理不依赖服务端保存的客户端会话上下文。
这样更容易实现负载均衡、横向扩容和故障转移。
5. 统一接口(Uniform Interface)
REST 的重要特征是通过统一的方式操作资源,而不是为每个业务设计完全不同的调用规则。
包括:
- 资源通过 URI 唯一标识。
- 客户端通过资源表述(如 JSON)操作资源。
- 消息具有自描述性,如 HTTP Method、状态码、Content-Type。
- 超媒体驱动应用状态(HATEOAS)。
其中 HATEOAS 是完整 REST 架构中经常被忽略的一点。
例如服务端返回一个订单:
{
"id": 100,
"status": "pending",
"links": {
"self": "/orders/100",
"payment": "/orders/100/payment",
"cancel": "/orders/100/cancellation"
}
}
客户端可以根据服务端提供的链接发现当前可执行的操作,而不必完全硬编码所有业务路径。
实际工程中很多所谓的 RESTful API 只遵守资源 URL、HTTP Method 等约定,并没有完整实现 HATEOAS。
6. 其他 REST 架构约束
除了无状态、统一接口,REST 还强调以下约束:
| 约束 | 说明 |
|---|---|
| Client-Server | 客户端和服务端职责分离 |
| Stateless | 请求之间不依赖服务端会话状态 |
| Cacheable | 响应应明确是否可以缓存 |
| Uniform Interface | 使用统一的资源交互接口 |
| Layered System | 支持网关、代理、负载均衡等分层结构 |
| Code on Demand | 可选约束,服务端可以向客户端传递可执行代码 |
这里要注意:REST 并不要求必须使用 JSON,也不强制要求必须基于 HTTP,只是 HTTP 是最常见的实现方式。
三、RESTful 中的幂等性
幂等性(Idempotency)指同一个操作执行一次与执行多次,对服务端目标状态产生的预期效果相同。
这是面试时经常结合 RESTful 考察的知识点。
| HTTP 方法 | 安全性 | 幂等性 |
|---|---|---|
| GET | 是 | 是 |
| POST | 否 | 不保证 |
| PUT | 否 | 是 |
| PATCH | 否 | 不保证 |
| DELETE | 否 | 是 |
注意:这里是 HTTP 方法的语义约定。PATCH 可以被设计为幂等操作,但不天然保证幂等。
PUT 为什么是幂等的?
例如:
PUT /users/100
{
"name": "Tom"
}
连续发送多次,对资源进行相同的替换操作,最终结果相同。
POST 为什么通常不幂等?
例如:
POST /orders
{
"product_id": 100
}
请求发送三次,可能创建三个不同的订单。
实际支付、订单创建等业务中,可以使用 Idempotency-Key 等机制让 POST 请求具备业务幂等性。
DELETE 为什么是幂等的?
DELETE /users/100
无论执行一次还是多次,最终用户资源都不存在。
即使第一次返回 204,第二次返回 404,也不影响该操作的幂等性,因为幂等性不要求每次响应完全一致。
四、RESTful API 设计实例
假设设计一个博客系统,包含用户、文章和评论。
| 需求 | Method | URL |
|---|---|---|
| 获取文章列表 | GET | /articles |
| 获取文章详情 | GET | /articles/123 |
| 创建文章 | POST | /articles |
| 整体替换文章 | PUT | /articles/123 |
| 修改文章标题 | PATCH | /articles/123 |
| 删除文章 | DELETE | /articles/123 |
| 获取文章评论 | GET | /articles/123/comments |
| 新增文章评论 | POST | /articles/123/comments |
还可以使用 Query Parameter 实现过滤、排序和分页:
GET /articles?page=1&page_size=20
GET /articles?author_id=100
GET /articles?sort=created_at&order=desc
这些 URL 都是在查询文章资源,只是查询条件不同。
五、RESTful 和 RPC 的区别
| 对比维度 | RESTful | RPC |
|---|---|---|
| 核心思想 | 面向资源 | 面向操作或函数 |
| API 风格 | /users/100 |
getUser(100) |
| 接口设计 | 通常借助 HTTP Method | 直接描述调用动作 |
| 常见协议 | HTTP | HTTP、HTTP/2、TCP 等 |
| 数据格式 | JSON、XML 等 | Protobuf、JSON 等 |
| 典型场景 | 对外开放 API、Web 服务 | 内部微服务调用 |
例如用户服务:
RESTful:
GET /users/100
RPC:
service UserService {
rpc GetUser(GetUserRequest)
returns (GetUserResponse);
}
实际上 RESTful 和 RPC 并不是完全对立的。
REST 是架构风格,RPC 是远程调用模型。某些基于 HTTP 的 API 即使采用资源形式,本质上也可能带有 RPC 的设计思想。
六、RESTful 的优缺点
优点:
- 接口统一,容易理解和维护。
- 充分利用 HTTP 状态码、缓存等已有机制。
- 客户端和服务端解耦。
- 无状态设计利于服务横向扩展。
- 适合浏览器、移动端、第三方系统等多种客户端。
缺点:
- 对复杂业务操作的表达有时不够自然。
- 某些场景可能出现多次请求或数据过度获取。
- API 版本演进和资源关联设计需要谨慎考虑。
- 对内部高频、低延迟通信场景,gRPC 等方案可能更合适。

浙公网安备 33010602011771号