REST接口

定义

REST，全称 Representational State Transfer，中文是表述性状态转移。它是由 Roy Fielding 博士在 2000 年提出的一种软件架构风格，而不是一个硬性的标准或协议。

设计符合 REST 架构风格的 API 或 Web 服务，就被称为 RESTful API 或 REST 接口。

思想

REST 的核心思想非常简单：将所有需要操作的事物抽象为“资源”。使用 URL 来定位资源，用 HTTP 方法来操作资源。

• 资源可以是一段文本、一张图片、一个用户、一条订单数据，或者任何可以描述的对象
• 每个资源在互联网上都有一个唯一的标识符，这就是我们熟悉的 URI
• 不同操作用不同的 HTTP 动词表示，不在 URL 中写“动词”，而是写“名词”

例如：

• https://api.example.com/users （用户集合资源）
• https://api.example.com/users/123 （ID 为 123 的单个用户资源）
• https://api.example.com/orders/456 （ID 为 456 的订单资源）

约束

要被称为 RESTful，一个接口需要满足以下六个架构约束中的几个（尤其是前五个）：

• 客户端-服务器：前后端分离，各自独立演化
• 无状态：这是最关键的特性之一。服务器不会保存客户端的任何会话状态。每一次从客户端发来的请求都必须包含所有服务器处理该请求所需的信息（如身份认证 token、参数等）
• 可缓存：响应必须被显式或隐式地标记为可缓存或不可缓存，以减少客户端-服务器之间的交互，提高性能
• 统一接口：这是 REST 系统设计的基本出发点，它又包含以下几个子原则：
  • 资源标识：每个资源都有唯一的 URI
  • 操作资源通过表述：客户端通过操作资源的表述（如 JSON、XML）来操作资源本身
  • 自描述的消息：每个消息（请求或响应）都包含足够的信息来描述如何处理自己
  • HATEOAS：超媒体作为应用状态引擎（这是最高级的约束，实践中不一定严格遵循）
• 分层系统：系统可由多层组成，客户端无需知道它是直接与终端服务器通信还是与中间的代理、负载均衡器等通信
• 按需代码：服务器可以临时扩展或自定义客户端的功能，如通过传输 JS 代码（唯一可选的约束）

规则

示例

操作类型	HTTP 方法	URL 例子	含义
查询资源（列表）	GET	/users	安全且幂等的操作，获取所有用户
查询单个资源	GET	/users/123	安全且幂等的操作，获取 ID 为 123 的用户
新建资源	POST	/users	非幂等操作，每次调用都会创建新资源
更新资源（整体）	PUT	/users/123	幂等操作，用提供的数据完全替换该资源
局部更新资源	PATCH	/users/123	非幂等操作，仅更新提供的字段
删除资源	DELETE	/users/123	幂等操作，删除用户

关键点：

• URL 表示“资源位置”
• 方法表示“要做的动作”
  • GET： 只用于获取数据，是安全和幂等的
  • POST： 用于创建新资源
  • PUT： 用于完整更新资源（客户端提供更新后的完整资源）
  • PATCH： 用于部分更新资源（客户端只提供要修改的字段）
  • DELETE： 用于删除资源
• 返回 JSON 格式的数据
• 无状态（Stateless）：每次请求都是独立的，服务端不保存客户端状态

// 请求

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer your_token_here

{
  "name": "张三",
  "email": "zhangsan@example.com"
}

// 响应

HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/124  // 新创建资源的URI

{
  "id": 124,
  "name": "张三",
  "email": "zhangsan@example.com",
  "createdAt": "2023-10-25T08:00:00Z"
}

对比

对比项	REST 风格	传统接口（RPC/Action 风格）
URL	/users/1	/getUser?id=1
方法	GET / PUT / POST / DELETE	通常都是 POST
含义	操作资源	调用动作（函数）
状态码	标准 HTTP 状态码	常返回自定义 code
可缓存性	高	低

优缺点

优点：

• 简单清晰：通过 URI 和 HTTP 方法就能直观地理解接口的用途
• 松耦合：前后端独立开发，只需约定好接口格式
• 可扩展性强：无状态设计使得服务器可以轻松水平扩展
• 充分利用 HTTP：继承了 HTTP 协议的所有优势，如缓存、安全性等

缺点：

• Over-fetching/Under-fetching：有时客户端只需要部分数据，但接口返回了全部；或者需要多次请求才能拿到完整数据。这催生了 GraphQL 等新技术
• 版本管理：当 API 需要升级时，如何优雅地管理版本是一个挑战（常见做法是在 URI 或 Header 中加入版本号，如 /v1/users）

总结

REST 接口是一种基于 HTTP 的资源设计风格。它使用 URL 表示资源，用不同的 HTTP 方法（GET、POST、PUT、DELETE）表示对资源的操作。特点是无状态、统一接口、可缓存。相比传统接口，REST 更语义化、标准化，也便于前后端分离和自动文档生成。是当今构建 Web API 最主流和公认的规范。