7 RESTful 规范

RESTful 规范是目前企业开发中主流的 API 设计风格（几乎所有互联网项目都会用），核心是 "用 HTTP 协议的特性来定义接口的语义"------ 简单说就是 "通过 URL 表示资源，通过 HTTP 方法表示对资源的操作"。

7.1 RESTful 的核心规则

RESTful 规范的核心是 **"资源"+"操作" 分离 **：

资源：用 URL 表示（比如 "购物车项" 是资源，URL 写成/cart/items）；
操作：用 HTTP 方法表示（比如 "查、增、删" 对应 GET/POST/DELETE）。

规则 1：URL 表示 "资源"，不用动词
❌ 非 RESTful（URL 里带 "操作动词"）：

/getCartItems // 查购物车
/addCartItem // 加购物车
/deleteCartItem // 删购物车项

✅ RESTful 写法（URL 只写资源，用 HTTP 方法表示操作）：

复制代码

GET    /cart/items   → 查购物车项（比如：对应controller的`getCartItems`方法）
POST   /cart/items   → 加购物车项（比如：对应controller的`addItemToCart`方法）
DELETE /cart/items/{itemId} → 删购物车项（比如：对应controller的`removeItemFromCart`方法）

/cart/items是 "购物车项" 这个资源，HTTP 方法决定是 "查、增、删"。

规则 2：用 HTTP 方法表示 "操作"
RESTful 中 HTTP 方法的对应关系，比如：

|---------|---------|----------------------------------------|----------|
| HTTP 方法 | 操作 | 你的接口示例 | 作用 |
| GET | 查（读） | @GetMapping("/cart/items") | 获取购物车列表 |
| POST | 增（创建） | @PostMapping("/cart/items") | 新增购物车项 |
| DELETE | 删（删除） | @DeleteMapping("/cart/items/{itemId}") | 删除指定购物车项 |
| PUT | 改（全量更新） | @PutMapping("/cart/items/{itemId}") | 更新购物车项数量 |

规则 3：用路径参数表示 "单个资源"
比如删除 "某个购物车项" 的接口：

@DeleteMapping("/cart/items/{itemId}")
public Result<Void> removeItemFromCart(@PathVariable Long itemId) { ... }

URL 中的{itemId}是 "路径参数"，表示 "单个购物车项资源"；
对应 RESTful 的 "操作单个资源" 语义（比如/cart/items/123就是 "ID 为 123 的购物车项"）。

7.2 在企业中的应用

现在几乎所有企业级项目（尤其是前后端分离、微服务项目）都采用 RESTful 规范，原因是：

接口语义清晰：看 URL 和 HTTP 方法就知道是 "操作什么资源、做什么事"，比如DELETE /cart/items/123，不用看文档就知道是 "删除 ID 为 123 的购物车项"；
前后端协作高效：前端开发者不用记 "接口叫什么名字"，只需要按 "资源 + 方法" 的逻辑调用；
兼容各种框架 / 工具：Swagger、Postman 等工具都对 RESTful 接口有友好支持，自动生成文档、调试更方便；
易扩展：比如后续要加 "修改购物车项"，直接用PUT /cart/items/{itemId}，接口风格统一，维护成本低。