什么是RESTful？

  • RESTful是一种接口设计风格，它的核心思想是“资源导向”，我们可以把服务器上的数据看作一个个资源，每个资源用一个 URL 来表示，然后通过标准的 HTTP 方法去操作它，比如用 GET 获取资源、POST 新增资源、PUT 或 PATCH 更新资源、DELETE 删除资源。它强调接口要简洁、统一，并且无状态，也就是说每个请求都应该包含完成这个请求所需要的所有信息，服务器不会去记住之前发生了什么。在实际项目中，RESTful 这种风格很常见，比如我们做一个用户管理的接口，像 GET /users 是获取用户列表，POST /users 是新增用户，GET /users/1 是查某个用户，整体逻辑清晰，前后端对接也方便。

一个用户管理系统

场景设定：开发一个用户管理系统

假设正在开发一个“用户管理系统”（User Management System），功能包括：

  • 创建新用户
  • 查询用户信息
  • 更新用户资料
  • 删除用户
  • 管理用户与订单的关系

接下来设计一组接口，供前端页面（或移动端 App）调用。

第一原则：资源是主角，URI 是地址

在 RESTful 架构中，系统中“可以被操作的对象”就是资源。

资源的命名用名词而不是动词，并且通常使用复数。

在用户系统中，以下是典型的资源与 URI 映射：

资源类型 URI 示例 说明
用户集合 /users 表示所有用户
单个用户 /users/123 表示 ID 为 123 的用户
用户订单 /users/123/orders 表示该用户的订单列表
单个订单 /orders/456 表示 ID 为 456 的订单

URI 不包含动词，动词行为由 HTTP 方法表达，体现了 REST 的“表述性状态转移”。

第二原则：HTTP方法表达行为

RESTful 利用标准的 HTTP 动词表达行为，不再用路径拼动作名。

我们用一个完整的用户生命周期来说明这些方法的使用：

1. 创建用户（POST）

1
2
3
4
5
6
7
POST /users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com"
}

含义：向 /users 资源集合中添加一个新用户。

返回：

1
2
201 Created
Location: /users/101

2. 获取用户（GET）

1
GET /users/101

获取 ID 为 101 的用户详情。

返回：

1
2
3
4
5
{
  "id": 101,
  "name": "Alice",
  "email": "alice@example.com"
}

3. 更新用户信息（PUT）

1
2
3
4
5
6
7
PUT /users/101
Content-Type: application/json

{
  "name": "Alice Zhang",
  "email": "alice.z@example.com"
}

表示将原有用户整体替换为新数据（字段缺失会被清空）。

4. 局部更新用户（PATCH）

1
2
3
4
5
6
PATCH /users/101
Content-Type: application/json

{
  "email": "alice.new@example.com"
}

🚨 实际项目中，PUT 和 PATCH 经常混用，但原则上 PATCH 更适合字段修改操作。

表示只修改部分字段，其他保持不变。

5. 删除用户（DELETE）

1
DELETE /users/101

服务器会删除用户记录，返回 204 No Content 表示删除成功但无内容返回。

幂等性与安全性解析（很关键）

幂等性（Idempotent）

多次请求的结果与一次请求相同。例如：

  • GET /users/101 —— 获取几次都一样
  • PUT /users/101 —— 相同数据更新多次没影响
  • POST /users —— 每次创建一个新用户 不幂等

安全性（Safe）

不会对服务器状态造成影响。例如：

  • GET 是安全的
  • DELETE、PUT 不是安全的（会改变数据）

RESTful 架构强调幂等和安全，不仅是哲学，也是工程保障（防止重试造成混乱）。

资源之间的关系设计

在我们的例子中，用户与订单存在关系：

  • URI 设计建议：用嵌套 URI 表达从属关系
1
GET /users/101/orders

表示获取 ID 为 101 的用户的所有订单。

1
GET /users/101/orders/555

表示该用户的具体某个订单。

优点是层级清晰、语义明确。

URI 设计原则总结

原则 示例
使用名词、复数形式 /users, /orders
使用嵌套表达从属关系 /users/101/orders
不使用动词 ❌ /getUser, ✅ /users/101
用查询参数做过滤 /users?name=Alice

状态码设计：让前端明白你在干嘛

常用 HTTP 状态码应与接口行为语义一致：

状态码 场景
200 OK 正常响应
201 Created 创建成功（如 POST 创建用户）
204 No Content 删除成功或 PUT 无返回体
400 Bad Request 请求参数错误
401 Unauthorized 未登录或 token 失效
403 Forbidden 登录了但没有权限
404 Not Found 请求资源不存在
500 Internal Server Error 服务器异常

RESTful 的魅力：结构化、表达清晰、贴合协议、无需文档就能猜出接口行为。