RESTful 规范的 HTTP 接口是一种基于 REST（Representational State Transfer）架构风格设计的 API，它利用 HTTP 协议的各种特性（如方法、状态码、URL 结构等）来实现资源的统一接口访问。RESTful 接口的核心是将系统中的所有事物抽象为资源，并通过标准化的 HTTP 方法对这些资源进行操作。

RESTful API 是遵循 REST 架构风格的 HTTP 接口

RESTful 规范的核心原则

资源导向
所有内容都被抽象为资源（如用户、订单、文章），通过 URL 标识（如 /users/123）。
统一接口
使用标准的 HTTP 方法操作资源：
- GET：获取资源
- POST：创建资源
- PUT：更新资源（全量）
- PATCH：更新资源（部分）
- DELETE：删除资源
无状态
每个请求都是独立的，服务器不存储客户端的会话状态。
分层系统
客户端无需关心数据存储或处理的具体层级（如数据库、缓存等）。
幂等性设计
GET、PUT、DELETE操作应具备幂等性（多次请求结果相同）。

RESTful 接口示例

假设我们有一个博客系统，其 RESTful 接口可能设计为：

操作	URL	HTTP 方法	说明
获取所有文章	`/api/articles`	`GET`	返回文章列表
获取单篇文章	`/api/articles/123`	`GET`	返回 ID 为 123 的文章
创建新文章	`/api/articles`	`POST`	创建一篇新文章
更新文章内容	`/api/articles/123`	`PUT`/`PATCH`	更新 ID 为 123 的文章
删除文章	`/api/articles/123`	`DELETE`	删除 ID 为 123 的文章
获取文章评论	`/api/articles/123/comments`	`GET`	返回文章 123 的评论列表

为什么使用 RESTful 规范？

标准化：遵循统一的设计原则，降低学习成本。
可扩展性：易于添加新资源或修改接口，不影响现有系统。
松耦合：客户端和服务器可以独立演进。
缓存支持：HTTP 缓存机制（如ETag、Cache-Control）可提高性能。
跨平台兼容：基于 HTTP 协议，支持任何语言和框架。

RESTful 与非 RESTful 的对比

非 RESTful 接口可能这样设计：
GET /api/getAllUsers（获取用户）
POST /api/deleteUser?id=123（删除用户）
这种设计依赖自定义方法名，不符合 HTTP 语义。
RESTful 则统一使用标准 HTTP 方法：
GET /api/users（获取用户）
DELETE /api/users/123（删除用户）

常见误区

URL 中使用动词：如/api/getUserInfo ，应改为 GET /api/users/{id}。
忽略状态码：如用 200 OK表示所有请求结果，应使用更具体的状态码（如 404 Not Found、400 Bad Request）。
过度设计嵌套资源：如/api/users/123/orders/456/products ，可简化为/api/products/456 。

在我看来动词定义接口好像更加直观，那么为什么要使用 RESTful api 呢

1. 标准化带来的统一性

场景对比

非 RESTful（动词导向）：

plaintext
```
POST /api/addUser
POST /api/modifyUserInfo
POST /api/deleteUser
GET  /api/fetchUserList
```
- 问题：每个接口都需要记忆自定义动词，难以形成统一认知。

RESTful（资源导向）：

plaintext

POST   /api/users         # 创建用户
PUT    /api/users/123     # 更新用户
DELETE /api/users/123     # 删除用户
GET    /api/users         # 获取用户列表

优势：只需理解 HTTP 方法的语义，看到 URL 就能推断操作类型。

2. 充分利用 HTTP 协议特性

状态码标准化

RESTful 强制使用 HTTP 状态码表示操作结果：

200 OK：请求成功
201 Created：资源创建成功
400 Bad Request：参数错误
401 Unauthorized：未授权
404 Not Found：资源不存在
409 Conflict：资源冲突（如重复创建）

非 RESTful 接口可能全部返回200，然后在响应体中自定义错误码，增加理解成本。

3. 无状态设计的优势

RESTful 要求每个请求包含所有必要信息，服务器不存储会话状态：

优点：
- 易于扩展：请求可被任意服务器处理，支持负载均衡和微服务架构。
- 容错性强：单个请求失败不影响其他请求。
- 可缓存：HTTP 缓存机制天然适用（如GET请求可被浏览器缓存）。

4. 自动支持跨平台

RESTful 接口基于标准 HTTP 方法，任何语言或框架都能轻松实现：

前端：JavaScript（fetch/axios）、React、Vue
后端：Java（Spring）、Python（Django/Flask）、Node.js
移动端：iOS（Swift）、Android（Kotlin）

5. 更好的扩展性

场景示例

假设需要扩展 “用户订单” 功能：

非 RESTful：可能需要新增GET /api/fetchUserOrders

RESTful：直接复用已有接口模式：

plaintext

GET /api/users/123/orders  # 获取用户 123 的订单
POST /api/users/123/orders # 创建新订单

6. 符合人类认知规律

虽然乍一看 “动词 + 操作” 更直观，但现实世界更倾向于 “资源 + 动作” 的模式：

图书馆系统：
- 非 RESTful：“执行借阅图书操作”
- RESTful：“对《设计模式》这本书执行借阅动作”
电商系统：
- 非 RESTful：“执行添加购物车操作”
- RESTful：“对 iPhone 14 这个商品执行添加购物车动作”

常见误区解答

Q1：动词真的更易懂吗？

短期：对于简单系统，动词可能更快上手。
长期：随着系统复杂度增加，动词会爆炸式增长（如 addUser, addAdmin, addGuest），而 REST 只需关注资源本身（ POST /users）。

Q2：所有场景都必须严格 RESTful 吗？

不是。对于某些特殊场景（如复杂业务流程），可以适当放宽限制，采用RESTful 为主，非 RESTful 为辅的混合设计。

Q3：RESTful 一定比非 RESTful 好吗？

不一定。如果系统规模很小且不会扩展，过度设计 RESTful 可能增加复杂度。但对于中大型项目，RESTful 的优势会显著体现。

总结

RESTful 规范的核心价值在于：通过标准化降低沟通成本，通过约束提升系统质量。它让 API 设计从 “个性化定制” 转变为 “遵循通用模式”，就像交通规则一样，虽然初期需要适应，但最终会带来更高的效率和更少的混乱。

如果你的项目有以下特点，强烈建议采用 RESTful：

多人协作开发
需要支持多客户端（Web、App、第三方集成）
预期会不断扩展功能
追求代码的可维护性和可测试性

没有理想的人不伤心

RESTful 规范的 HTTP 接口