restful编码风格

一、先搞懂：什么是 REST？

• REST：一种软件架构风格（不是标准）
• RESTful：符合 REST 风格的 API 就叫 RESTful API

它的核心思想：把服务器上的所有数据 / 功能，都看作「资源」，用 URL 定位资源，用 HTTP 方法表示操作。

---

二、RESTful 最核心的 5 大原则（必须记住）

1. 一切皆为「资源」

服务器上的所有东西：用户、文章、订单、商品、评论...... 全都是资源 。资源用名词 表示，不用动词。

❌ 错误（动词接口）

plaintext

/getUser
/deleteOrder
/createProduct
/updateArticle

✅ 正确（名词接口）

plaintext

/users
/orders
/products
/articles

2. 使用 URL 定位资源

URL 只用来定位资源在哪里，不表示做什么操作。

规则：

• 复数形式优先（/users 比 /user 更规范）
• 层级清晰
• 用 / 表示层级关系

示例：

plaintext

# 用户列表
/users

# 单个用户
/users/123

# 用户 123 的所有订单
/users/123/orders

# 用户 123 的订单 456
/users/123/orders/456

3. 用 HTTP 方法表示「操作」

这是 RESTful 最经典的设计：URL 不变，通过不同请求方法，表达对资源的不同操作。

表格

HTTP 方法	操作含义	对应数据库	示例
GET	查询 / 获取	SELECT	获取用户、获取订单
POST	新增 / 创建	INSERT	新建用户、下单
PUT	全量更新	UPDATE	替换整个用户信息
PATCH	部分更新	UPDATE	只改用户手机号
DELETE	删除	DELETE	删除用户、取消订单

✅ 标准示例：

plaintext

GET    /users      # 获取所有用户
GET    /users/123  # 获取单个用户
POST   /users      # 新建用户
PUT    /users/123  # 全量更新用户
PATCH  /users/123  # 部分更新用户
DELETE /users/123  # 删除用户

4. 使用标准 HTTP 状态码

RESTful 要求用状态码表达结果，而不是在返回数据里自定义成功失败。

常用状态码：

• 200 OK：成功（查询 / 更新）
• 201 Created：创建成功（POST）
• 204 No Content：删除成功
• 400 Bad Request：参数错误
• 401 Unauthorized：未登录 / 无权限
• 403 Forbidden：禁止访问
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

5. 无状态（Stateless）

**每次请求都是独立的，服务器不保存客户端的状态。**所有需要的信息（身份、参数、上下文），都必须在请求里带过去。

优点：

• 服务器更容易扩展
• 负载均衡更简单
• 接口更稳定

---

三、RESTful URL 设计规范（实战必看）

1. 只用名词，不用动词

✅ Good

plaintext

/users
/orders
/products

❌ Bad

plaintext

/getUsers
/addOrder
/deleteProduct

2. 优先使用复数

✅ /users❌ /user

3. 用斜杠 / 表示层级

plaintext

/users/123/orders
/articles/456/comments

4. 不要用文件扩展名

✅ /users/123❌ /users/123.json /users/123.xml

5. 查询参数用？携带

分页、筛选、排序，都用查询参数：

plaintext

# 分页
/users?page=1&size=10

# 筛选
/orders?status=paid

# 排序
/articles?sort=create_time,desc

---

四、一个完整的 RESTful API 示例（用户模块）

表格

接口功能	URL	请求方法	说明
获取所有用户	/users	GET	查询列表
获取单个用户	/users/{id}	GET	查询单个
新增用户	/users	POST	提交 JSON
全量更新用户	/users/{id}	PUT	替换整个资源
部分更新用户	/users/{id}	PATCH	只改部分字段
删除用户	/users/{id}	DELETE	删除资源

---

五、返回数据格式规范

RESTful 一般返回 JSON，结构统一：

json

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三",
    "age": 25
  }
}

• code：配合 HTTP 状态码使用
• message：提示信息
• data：真正返回的数据

---

六、RESTful 的优点

1. 接口清晰易懂，看 URL 就知道资源是什么
2. 方法统一，GET/POST/PUT/DELETE 语义明确
3. 无状态，服务器更容易集群扩展
4. 标准化，前后端协作成本极低
5. 可缓存，GET 请求天然支持缓存，提升性能

---

七、RESTful 常见误区（很多人都错）

1. 把接口设计成动词（/getUser、/addOrder）→ 违反规范
2. 所有接口都用 POST → 完全不是 RESTful
3. 状态码永远返回 200 → 失去状态码意义
4. 服务器保存会话状态 → 破坏无状态原则
5. URL 设计混乱（层级不清、大小写混用）

---

八、一句话总结 RESTful

用 URL 定位资源，用 HTTP 方法表示操作，用状态码表示结果，用 JSON 传递数据。

一套规范，让所有接口统一、清晰、易维护、易扩展。