RESTful API 设计：URI设计规范，HTTP方法语义化，状态码选择，API版本管理策略
聊到后端架构，RESTful API 设计是绕不开的话题。我见过太多团队，接口设计随心所欲，最后维护成本高得吓人。说白了，RESTful 不是一套死板的规范，而是一套约定俗成的「沟通语言」。今天我就把这几年的实战经验掰开揉碎，跟你聊聊 URI 怎么命名、HTTP 方法怎么用、状态码怎么选、版本怎么管。
核心原则：RESTful API 的核心是「资源」—— 把一切业务抽象成资源，用统一的接口去操作它们。
一、URI 设计规范：给资源起个好名字
URI 是资源的地址。我个人的习惯是：名词复数、小写字母、用连字符分隔。为什么？因为简单、直观、好记。
- 用名词，不用动词：
/users而不是/getUsers。动词交给 HTTP 方法去表达。 - 用复数：
/orders而不是/order。集合天然就是复数。 - 层级关系用斜杠：
/users/123/orders表示「用户 123 的订单」。 - 过滤、排序、分页用查询参数：
/orders?status=paid&page=1&size=20。
我在项目中遇到过团队把过滤条件塞进路径里，比如 /orders/paid/2024。嗯，这其实不太对。路径应该表达资源层级，查询参数才表达筛选条件。你想想看，如果后面要加个「已取消」的筛选，路径就炸了。
避坑指南：我曾经见过一个接口叫 /getUserInfoById，后来需求变了，要改成 /getUserDetail，前端和后端都得改。如果一开始就用 /users/{id}，啥事没有。
二、HTTP 方法语义化：动词要准确
HTTP 方法就是你的「动词」。每个动词都有明确的语义，别乱用。
| 方法 | 语义 | 示例 | 幂等 |
|---|---|---|---|
| GET | 获取资源 | GET /users/123 |
是 |
| POST | 创建资源 | POST /users |
否 |
| PUT | 全量更新 | PUT /users/123 |
是 |
| PATCH | 部分更新 | PATCH /users/123 |
是 |
| DELETE | 删除资源 | DELETE /users/123 |
是 |
这里有个容易踩的坑：PUT 和 PATCH 的区别。PUT 是全量替换，你传什么字段，服务端就存什么字段。PATCH 是局部更新，只修改你传的字段。我见过有人用 PUT 做部分更新，结果没传的字段被清空了。嗯，线上事故就是这么来的。
注意：POST 不是幂等的。你调两次 POST 创建订单，会生成两笔订单。所以前端做重试时要小心，最好加个幂等键（Idempotency-Key）。
三、状态码选择：让客户端看懂你的心情
状态码是服务端对客户端的「回应」。选对了，前端不用猜；选错了，联调时互相甩锅。
我习惯把状态码分成几类：
- 2xx 成功：
200 OK：GET、PUT、PATCH 成功201 Created：POST 创建成功，记得返回 Location 头204 No Content：DELETE 成功，或者更新后不需要返回内容
- 3xx 重定向：API 里用得少，但
301（永久重定向）和302（临时重定向）偶尔会用到。 - 4xx 客户端错误：
400 Bad Request：参数校验失败，比如邮箱格式不对401 Unauthorized：没登录，或者 过期403 Forbidden：登录了但没权限404 Not Found：资源不存在409 Conflict：资源冲突，比如重复创建422 Unprocessable Entity：语义错误，比如业务规则不满足
- 5xx 服务端错误：
500 Internal Server Error：代码炸了502 Bad Gateway：上游服务挂了503 Service Unavailable：服务过载或维护中
我曾经在项目里看到有人把所有错误都返回 200，然后在 body 里放一个 code 字段表示成功或失败。说实话，这很反人类。前端每次都要解析 body 才知道有没有错，而且浏览器的 DevTools 里全是绿色 200，排查问题全靠猜。用标准状态码，一目了然。
小技巧：错误响应 body 里统一放一个 error 字段，里面包含 message 和 details。比如：{ "error": { "message": "用户不存在", "details": "userId: 123" } }。这样前端可以统一处理错误提示。
四、API 版本管理策略：别让老用户骂你
API 一旦上线，就有人依赖它。你改接口，客户端就得跟着改。所以版本管理是必须的。
常见的版本管理方式有三种：
| 方式 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| URI 路径 | /v1/users |
简单直观，容易缓存 | 版本号污染 URI |
| 请求头 | Accept: application/vnd.myapi.v1+json |
URI 干净，符合 REST 风格 | 调试麻烦，浏览器不友好 |
| 查询参数 | /users?version=1 |
实现简单 | 容易被忽略，缓存不友好 |
我个人习惯用 URI 路径 方式。为什么？因为简单。你想想看，运维同学配置 Nginx 路由、做灰度发布，看路径就知道是哪个版本。用请求头的话，还得去解析 HTTP Header，麻烦。
但这里有个原则：不要轻易升级大版本。每次大版本升级，客户端都得改代码、发版、用户更新。我见过一个项目，半年内从 v1 升到 v5，前端团队直接崩溃。所以，尽量做到向后兼容。新增字段、新增接口，都不算破坏性变更。只有删除字段、修改字段类型、改变接口语义，才需要升大版本。
避坑指南：我曾经在 v1 接口里把一个字段从 int 改成 string，觉得「反正 JSON 里都是字符串，前端应该能兼容」。结果前端有个老版本 App 直接崩溃了。从那以后，我改字段类型必升版本。
五、知识体系总览
下面这张图，是我对 RESTful API 设计核心要点的总结。你可以把它当作一个检查清单。
这张图把 RESTful API 设计的五个核心维度串起来了。你设计接口时，可以对着这张图逐个检查：URI 规范吗？方法用对了吗？状态码选对了吗？版本怎么管？有没有遵循最佳实践？
好了，关于 RESTful API 设计，我就聊这么多。记住一句话：好的 API 设计，是让调用者不用看文档也能猜对。你想想看，如果前端同学看到 GET /users/123 就知道是获取用户信息，看到 404 就知道用户不存在，那联调效率能不高吗？
总结：URI 用名词复数，方法用标准语义，状态码用标准码，版本用路径管理。做到这四点，你的 API 就已经超过 80% 的项目了。
可可精品资料库