下面介绍一个非常系统、专业又通俗易懂的 Restful API 讲解，涵盖：定义、设计原则、应用场景、最佳实践、示例，非常适合软件工程师巩固理解。
🌐 一、Restful API 是什么？（定义）
REST（Representational State Transfer） 是一种 Web 服务的架构风格。它不是协议，不是标准，而是设计 API 的一套指导规范。
Restful API = 按照 REST 架构风格设计的 API。
简化理解：
➡️ Restful API 就是“用 URL 来表达资源，用 HTTP 方法来表达操作”的接口设计方式。
🧩 二、核心思想（REST 六大原则）
REST 有 6 个核心约束，常用的 4 个是：
1. 统一接口（Uniform Interface） ✨ 最重要
-
URL → 表达资源
/users/123表示用户资源 ID 为 123 -
HTTP 动词表达操作
- GET → 查询资源
- POST → 新建资源
- PUT → 完整更新资源
- PATCH → 局部更新资源
- DELETE → 删除资源
2. 无状态（Stateless）
服务端不保存客户端状态（session）。
所有请求必须携带必要信息，比如 token。
3. 客户端—服务器分离（Client-Server Separation）
前后端分离：前端负责 UI，后端提供资源。
4. 可缓存（Cacheable）
响应声明是否可缓存，提升性能。
🛠️ 三、如何设计一个典型的 RESTful API？
1. 资源名使用名词，使用复数
/users
/orders
/products
2. 使用层级关系表达资源结构
/users/1/orders
/users/1/orders/3
3. 使用 HTTP 方法定义动作
| HTTP 方法 | 动作 |
|---|---|
| GET | 查询资源 |
| POST | 创建资源 |
| PUT | 更新整个资源 |
| PATCH | 更新部分资源 |
| DELETE | 删除资源 |
📘 四、典型 RESTful API 示例（以用户资源为例）
1. 获取用户列表
GET /users
2. 创建新用户
POST /users
Body:
{
"name": "Alice",
"email": "alice@example.com"
}
3. 获取指定用户
GET /users/123
4. 更新用户
完整更新：
PUT /users/123
局部更新：
PATCH /users/123
5. 删除用户
DELETE /users/123
🚀 五、Restful API 的优势
✔ 清晰可读
URL 语义明确：一看就知道是操作什么资源。
✔ 前后端分离
天然适配 Web、App、JS 的生态。
✔ 可拓展性强
资源管理结构化，适合大型系统。
✔ 对接方便
各种语言都易于对接 REST。
📌 六、在实际项目中的典型应用场景
| 场景 | 描述 |
|---|---|
| Web 后端服务 | 前端 SPA + 后端 API |
| 移动 App 后端 | Android/iOS 调 API |
| 第三方开放平台 | 如微信开放接口、GitHub API |
| 微服务内部通信 | 服务之间 REST 调用 |
💡 七、REST vs RPC vs GraphQL（工程师常见困惑）
| 特点 | REST | RPC | GraphQL |
|---|---|---|---|
| 语义 | 资源 | 方法调用 | 查询语言 |
| 灵活性 | 中等 | 高 | 很高 |
| 数据返回 | 固定 | 固定 | 客户端可定制 |
| 适合场景 | 标准 CRUD | 强方法语义 | 复杂查询的前端 |
Restful 适合：业务以资源为核心、多端访问、CRUD多的系统。
例如：电商、OA、CRM、后台管理系统。
📏 八、Restful API 设计最佳实践（高级工程师常问的）
1. URL 不包含动词
❌ /getUserInfo
✔ /users/123
2. 返回标准化结构（推荐）
{
"code": 0,
"data": {...},
"message": "success",
"traceId": "xxx"
}
3. 使用 HTTP 状态码表达业务结果
| 状态码 | 含义 |
|---|---|
| 200 | OK |
| 201 | Created（创建成功） |
| 400 | 参数错误 |
| 401 | 未授权 |
| 404 | 资源不存在 |
| 500 | 系统错误 |
4. 分页参数规范
GET /users?page=1&size=20
5. 过滤和排序参数规范
GET /users?status=active&sort=createdAt&order=desc
6. 避免深层级 URL
/shops/1/products/2/comments/3/tags (❌)
一般控制在 2 层以内。
🎯 九、Restful API 什么时候“不推荐使用”？
| 不适合 REST 的情况 | 原因 |
|---|---|
| 强方法语义（如计算、转账） | 用动词更合理 |
| 批量操作复杂 | REST 难表达 |
| 需要一次请求获取多资源 | REST 需要多次请求 |
| 服务间调用频繁 | RPC 更高效 |
例如：
POST /payments/transfer
这种“动作型”的接口其实是为了业务落地，不一定严格 REST。
🏁 十、总结
Restful API 的核心是：
用 URL 表示资源，用 HTTP 动词表示操作，接口无状态、清晰、可缓存、可扩展。
它是现代 Web/移动后端的基础，也是你在 Java/Golang 服务开发面试中必问的知识点。
