3、RESTful API设计：REST架构风格、HTTP方法与资源映射、API版本管理与状态码设计
好，咱们今天聊聊RESTful API设计。说实话，这话题在云平台对接里太关键了。你想想看，自动化流程要跟云平台打交道，API就是那个“翻译官”。翻译官当不好，整个对接就乱套了。
我这些年做过的项目，但凡API设计得好的，后续集成几乎不用返工。设计得差的？嗯，那真是改到想哭。所以今天我把核心要点掰开揉碎了讲给你听。
3.1 REST架构风格：不是随便写个URL就叫REST
很多人以为，只要用HTTP协议，URL写得像那么回事，就是RESTful了。其实不然。REST是一种架构风格，不是协议，更不是标准。它有几个核心约束，我一个个说。
- 无状态性：每个请求都包含所有必要信息。服务端不存客户端上下文。我在项目中遇到过，有人把用户登录状态塞在服务端Session里，结果一扩容就出问题。无状态才能水平扩展，这是云原生的基础。
- 统一接口：资源通过URI标识，操作通过HTTP方法表达。说白了，就是“看URL知道是什么，看方法知道干什么”。
- 资源导向：一切皆资源。不是“操作”，是“资源”。比如
/createOrder这种写法，一看就是RPC思维，不是REST。 - 自描述消息：每个响应都包含足够信息来描述自身状态。媒体类型（Content-Type）就是干这个的。
核心观点：REST不是技术选型，是设计思想。你理解了这四点，API设计就成功了一半。
3.2 HTTP方法与资源映射：CRUD的优雅表达
HTTP方法跟数据库的CRUD操作是对应的，但映射关系没那么死板。我习惯这样设计：
| HTTP方法 | 操作 | 资源路径示例 | 说明 |
|---|---|---|---|
| GET | 查询 | /api/v1/orders/{id} |
获取单个资源，幂等 |
| POST | 创建 | /api/v1/orders |
创建新资源，非幂等 |
| PUT | 全量替换 | /api/v1/orders/{id} |
整体更新，幂等 |
| PATCH | 部分更新 | /api/v1/orders/{id} |
局部修改，非幂等 |
| DELETE | 删除 | /api/v1/orders/{id} |
删除资源，幂等 |
这里有个坑，我踩过。有人把PUT当PATCH用，传几个字段就更新几个字段。结果客户端漏传字段，服务端直接把其他字段置空了。所以我的建议是：PUT必须传完整资源，PATCH只传变化部分。
个人经验：在自动化流程对接中，我倾向于用POST做复杂查询。因为GET的URL长度有限制，而且查询参数多了，缓存策略也不好控制。比如批量查询订单状态，用POST /api/v1/orders/batch-query比用GET带一堆参数要清爽得多。
3.3 API版本管理：别让升级变成灾难
版本管理这事儿，说白了就是“向前兼容”。你改了API，不能把老客户端搞崩了。我见过最粗暴的做法：直接在URL里写版本号，比如/v2/orders。然后老版本直接下线，客户端全得跟着升级。这在云平台对接里是行不通的——你想想看，几百个自动化流程同时跑，你让它们一起改？
我个人习惯的做法是：
- URL路径版本：
/api/v1/orders。简单直观，适合对外公开的API。缺点是版本多了URL会乱。 - 请求头版本：通过
Accept: application/vnd.myapp.v2+json指定。更优雅，但调试起来麻烦点。 - 查询参数版本：
/api/orders?version=2。最灵活，但容易被忽略。
我推荐用第一种。为什么？因为直观。你在日志里看到/v1/orders，一眼就知道是哪个版本。我曾经在项目里用过请求头版本，结果排查问题时，开发人员得先看请求头才知道版本号，效率低了不少。
避坑指南：我曾经犯过一个错——版本号只保留最新两个。结果有个老流程半年没更新，突然要对接新数据，发现/v1已经下线了。后来我学乖了：至少保留三个大版本，给客户端留足迁移时间。同时，每个版本都要有明确的废弃时间表，提前通知客户端。
3.4 状态码设计：让错误信息自己说话
状态码不是随便填的。好的状态码设计，能让调用方不用看文档就知道发生了什么。我总结了一套原则：
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | 成功 | GET、PUT、PATCH成功返回 |
| 201 | 已创建 | POST创建资源成功 |
| 204 | 无内容 | DELETE成功，或GET无数据 |
| 400 | 请求错误 | 参数校验失败、格式错误 |
| 401 | 未授权 | 缺少认证信息或认证失败 |
| 403 | 禁止访问 | 认证通过但无权限 |
| 404 | 未找到 | 资源不存在 |
| 409 | 冲突 | 资源状态冲突（如重复创建） |
| 422 | 不可处理 | 业务逻辑错误（如库存不足） |
| 429 | 请求过多 | 限流触发 |
| 500 | 服务端错误 | 未捕获的异常 |
| 503 | 服务不可用 | 服务正在维护或过载 |
这里有个细节：不要所有错误都返回400。我见过一个API，参数校验失败返回400，业务逻辑错误也返回400，连数据库连接超时也返回400。调用方根本不知道问题出在哪。正确的做法是：客户端的问题用4xx，服务端的问题用5xx。这样自动化流程可以根据状态码决定是否重试——5xx可以重试，4xx重试也没用。
最佳实践：响应体里一定要带错误详情。我习惯这样设计：
{
"code": "ORDER_NOT_FOUND",
"message": "订单ID 12345 不存在",
"details": {
"orderId": "12345",
"suggestion": "请检查订单ID是否正确"
}
}这样自动化流程可以根据code字段做分支处理，而不是去解析message字符串。你想想看，解析字符串多脆弱啊，改个标点符号就崩了。
3.5 实战建议：从设计到落地
最后，我分享几个实战中的小建议：
- 资源命名用名词复数：
/orders，不是/order，也不是/getOrder。 - 子资源用嵌套路径：
/orders/{id}/items，清晰表达层级关系。 - 过滤、排序、分页用查询参数：
?status=active&sort=created_at&page=1&size=20。 - HATEOAS可选但推荐：在响应里返回相关链接，让客户端“发现”下一步操作。比如创建订单后，返回
{"links": {"self": "/orders/123", "payment": "/orders/123/payment"}}。
我的习惯：在项目初期，我会先画一个资源地图，把所有API端点列出来，标注好方法、参数、状态码。然后拉着前后端一起评审。这一步虽然花时间，但能避免后期80%的返工。你想想看，等代码写完了再改API设计，那成本可就高了。
好了，RESTful API设计这块就聊到这儿。核心就三件事：资源要清晰、方法要准确、状态码要规范。下一节咱们聊聊API安全，那又是另一个有意思的话题了。