1. 简介

REST(Representational State Transfer)是一种软件架构风格,它定义了如何标识和访问资源。从 Google Trends 的趋势来看,REST API 的关注度极高。在现代互联网中,几乎每个 Web 服务都会用到 RESTful API。本文将深入讲解 REST 的核心概念以及与 HTTP 协议相关的实践要点。

2. REST 架构

REST 是一种非标准化的架构风格(比如不同于 SOAP),它提供了高度的灵活性。比如,分页机制没有统一的实现方式。但 REST 定义了一组核心约束,只要在开发 RESTful API 时遵循这些约束,就能构建出结构清晰、可维护的接口。

2.1. 核心约束

统一接口(Uniform Interface)
资源应通过 URI(Uniform Resource Identifier)唯一标识。客户端通过 URI 操作资源,而资源的表示形式应包含所有操作所需的信息。比如,客户端可以通过 URI 获取资源的完整表示,并据此进行修改或删除操作。

客户端-服务器架构(Client-Server Architecture)
客户端与服务器职责分离。客户端通过 URI 获取资源,无需关心服务器如何处理请求;服务器处理逻辑和返回数据,也不依赖客户端的 UI 实现。这种分离使得前后端可以独立演进,接口可复用性强。

无状态(Statelessness)
每次请求都必须包含处理所需的所有信息,服务器不保存客户端的状态。这提高了系统的可用性和可扩展性,但也对客户端提出了更高的要求。

可缓存性(Cacheability)
服务器响应应标明是否可缓存及缓存时间。对静态或低频更新的数据进行缓存,可以显著减少网络请求,提升性能(如使用 Spring Cache)。

分层系统(Layered System)
REST API 可以由多个层级组成,比如业务逻辑层、数据访问层、网关层等。客户端无需知道是否直接连接后端服务器,这种设计提升了系统的扩展性和安全性。

按需代码(Code on Demand)
这是唯一一个可选约束。服务器可以返回可执行代码(如 JS 脚本)供客户端运行。但实际中很少使用。

3. HTTP 协议

虽然 REST 可用于其他协议,但在实际开发中,几乎都基于 HTTP。因此,我们重点讲解 HTTP 协议及其在 REST 中的应用。

HTTP 是万维网的基础协议,定义了客户端与服务器之间的通信规则。它是无状态的,采用请求-响应模式。

3.1. 请求结构

一个完整的 HTTP 请求通常包括:

  • 请求行(Method + Path + HTTP Version)
  • 零个或多个 Header
  • 一个空行
  • 可选的 Body

例如,一个 GET 请求可能如下:

GET /api/users/123 HTTP/1.1
Host: example.com
Accept: application/json

3.2. 常用 HTTP 方法

方法 用途说明
GET 获取资源,不改变资源状态,无请求体
POST 创建资源,数据在 Body 中,服务器返回新资源 URI
PUT 更新资源,替换整个资源,是幂等操作
DELETE 删除资源
PATCH 部分更新资源(不常用)
HEAD 获取资源头部信息(不常用)
OPTIONS 获取服务器支持的方法(不常用)

⚠️ GET vs POST vs PUT

  • GET 用于读取,幂等且安全
  • POST 用于创建,非幂等
  • PUT 用于更新,幂等

3.3. 常见 HTTP 状态码

类别 范围 示例 说明
1xx 信息类 100 Continue 请求已接收,继续处理
2xx 成功类 200 OK, 201 Created 请求成功处理
3xx 重定向 301 Moved Permanently 需要客户端跳转
4xx 客户端错误 400 Bad Request, 404 Not Found 客户端请求有误
5xx 服务端错误 500 Internal Server Error 服务器内部错误

4. Richardson 成熟度模型

Richardson 成熟度模型用于评估 RESTful API 的设计质量,分为四个等级:

Level 0:POX(Plain Old XML)

  • 仅使用 GET 和 POST
  • 没有明确的资源概念
  • 接口命名类似方法名,如:
POST /api/createUser
GET /api/findUser

⚠️ 这种设计只是把 HTTP 当作传输通道,没有发挥 REST 的优势。

Level 1:资源化

  • 有了资源的概念,URI 表示资源
  • 但依然只使用 POST 和 GET
POST /api/users/create
GET /api/users/{id}/find

Level 2:使用标准方法

  • 使用 GET、POST、PUT、DELETE 等标准方法
  • 返回更准确的状态码
  • 接口更语义化
POST /api/users
PUT /api/users/{id}
GET /api/users/{id}

✅ 这是大多数 RESTful API 所处的层级。

Level 3:HATEOAS(Hypermedia as the Engine of Application State)

  • 接口返回中包含相关资源的 URI
  • 客户端可自动导航,实现“自描述”接口
  • 示例:
{
  "id": 12345,
  "firstname": "some-firstname",
  "lastname": "some-lastname",
  "age": 39,
  "links": {
    "address": "users/12345/address"
  }
}

⚠️ HATEOAS 虽然更符合 REST 的理想模型,但增加了接口设计和客户端解析的复杂度,实际项目中使用较少。

5. 总结

REST 是一种轻量、灵活、广泛采用的 Web 架构风格。它基于 HTTP 协议,强调资源的统一标识、无状态交互、可缓存性和分层设计。通过 Richardson 成熟度模型可以评估 API 的设计质量,Level 2 是目前大多数项目的目标层级。虽然 Level 3 更符合 REST 的理念,但因复杂度较高,实际应用中并不常见。

掌握 REST 的核心原则和 HTTP 的使用方式,是构建高质量 API 的基础。在设计接口时,建议遵循标准方法和语义化 URI,提升可维护性和可扩展性。


原始标题:The REST Architecture