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 等方案可能更合适。
posted @ 2026-10-14 20:32  光風霽月  阅读(23)  评论(0)    收藏  举报