理解 RESTful API 设计原则

发布于 2025-07-31

REST（Representational State Transfer）是一种软件架构风格，而不是一个标准。当一个API遵循REST的原则时，我们称之为RESTful API。它已经成为现代Web服务设计的黄金标准，因为它提供了简单、可扩展和松耦合的通信方式。

核心原则

一个真正的RESTful API应该遵循以下几个关键原则：

1. 客户端-服务器架构

客户端和服务器的关注点应该分离。客户端负责用户界面和用户体验，而服务器负责存储和处理数据。这种分离使得两端可以独立演进。

2. 无状态 (Stateless)

从客户端到服务器的每个请求都必须包含理解和处理该请求所需的所有信息。服务器不能在两次请求之间存储任何关于客户端的上下文信息。会话状态完全由客户端管理。

3. 统一接口 (Uniform Interface)

这是REST架构风格的核心。它简化和解耦了架构，使得每一部分都可以独立演进。它包含几个子约束：

• 资源标识：通过URI（统一资源标识符）来标识资源，例如 /users/123。
• 通过表述来操作资源：客户端通过资源的表述（如JSON或XML）来操作资源。
• 自描述消息：每个消息都应包含足够的信息来描述如何处理它。

HTTP动词的使用

RESTful API 善于利用HTTP动词来表示对资源的操作：

• GET: 获取资源。
• POST: 创建新资源。
• PUT: 更新或替换整个资源。
• DELETE: 删除资源。
• PATCH: 部分更新资源。

例如，要获取所有用户，你可以发送一个 GET 请求到 /users。要创建一个新用户，你可以发送一个包含用户数据的 POST 请求到 /users。

// GET /api/users/123
{
  "id": 123,
  "name": "Jiang",
  "email": "jiang@example.com"
}

遵循这些原则可以创建出清晰、可预测且易于使用的Web API。