7 RESTful 规范
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}，接口风格统一，维护成本低。