RESTful API（Representational State Transfer）是一种基于 Web 的 API 设计风格，具有简洁、结构清晰、语义明确等特点，常用于前后端分离的系统中。
一、RESTful API 的核心理念
REST 不是协议，而是一种 设计风格，其核心理念是：
- 将资源作为核心（Everything is a resource）
- 通过 HTTP 方法对资源进行操作（使用标准动词）
- 无状态通信（Stateless）
- 使用统一接口（Uniform Interface）
二、RESTful API 的命名规则（规范）
1. 资源 URI 命名
- 使用名词，且一般使用复数形式
- 避免动词（动作由 HTTP 方法表示）
例如：
GET /users 获取用户列表
GET /users/123 获取 ID 为 123 的用户
POST /users 创建一个新用户
PUT /users/123 更新 ID 为 123 的用户
DELETE /users/123 删除 ID 为 123 的用户
2. 使用标准 HTTP 方法表示操作
| HTTP 方法 | 作用 |
|---|
| GET | 获取资源 |
| POST | 创建资源 |
| PUT | 更新资源（整体） |
| PATCH | 更新资源（部分） |
| DELETE | 删除资源 |
3. 使用路径层级表达资源之间的关系
GET /users/123/orders 获取用户 123 的所有订单
GET /users/123/orders/456 获取用户 123 的订单 456
4. 使用查询参数表示过滤、排序、分页等
GET /products?category=phone&sort=price_asc&page=2&limit=20
三、RESTful API 的特点
| 特点 | 描述 |
|---|
| 资源导向 | 所有内容都被抽象为资源（User、Order、Article 等） |
| 使用标准协议 | 基于 HTTP 协议，直接使用其方法（GET、POST 等） |
| 无状态通信 | 每次请求都包含所有上下文，不依赖服务器保存状态 |
| 统一接口 | 接口风格统一、易于理解和使用 |
| 可缓存 | 客户端可根据响应头对资源进行缓存，提高性能 |
| 分层架构 | 客户端无需知道请求最终由谁处理（例如中间层、负载均衡等） |
四、RESTful API 与传统 API 的对比
| 比较项 | RESTful API | 传统 API 风格 |
|---|
| 接口风格 | 资源导向，结构清晰 | 动作导向，接口混乱 |
| 动作表示 | 使用 HTTP 方法表示动作 | 接口路径中包含动词（如 /getUser） |
| 可读性 | 高，可直观理解操作含义 | 低，需要阅读文档才能理解 |
| 维护性 | 易于扩展和维护 | 扩展性差，接口膨胀 |
五、常见 RESTful API 错误码（建议）
| 状态码 | 含义 | 说明 |
|---|
| 200 | OK | 请求成功 |
| 201 | Created | 成功创建资源 |
| 204 | No Content | 请求成功，但无返回内容 |
| 400 | Bad Request | 请求参数有误 |
| 401 | Unauthorized | 认证失败 |
| 403 | Forbidden | 没有权限访问资源 |
| 404 | Not Found | 资源不存在 |
| 500 | Internal Server Error | 服务器内部错误 |
六、什么时候应该用 RESTful？
- 资源之间关系明确、结构层级清晰
- 系统需要公开标准 API 供外部系统调用
- 系统前后端分离，接口要语义化、易于文档化
