RESTful API 设计翻车现场：我从血泪教训中整理出的一份救命指南

做后端开发这些年，我见过太多 API 写得跟散文一样的项目。不是说内容不好，而是——你打开接口文档，仿佛在读一篇小学生作文，充满了「然后」「后来」「总之」。

今天我就来聊聊 RESTful API 设计里那些让人血压飙升的坑，以及怎么优雅地绕过去。都是我或者同事真实翻过的车，保证接地气。

一、先搞清楚你写的到底是不是 RESTful

很多同学以为只要用了 HTTP 协议、传个 JSON，就叫 RESTful API 了。这就像以为自己买了口好锅就自动会做菜了一样。

RESTful 是一种架构风格，不是协议。它有几个核心约束：客户端-服务器分离、无状态、可缓存、分层系统、统一接口。

最后这个「统一接口」是关键。Roy Fielding（REST 之父）说过，统一接口的核心是：每个资源都有可寻址的标识（URI），通过通用的动作来操作资源（HTTP 方法）。

所以如果你写了这样一个接口：

POST /api/getUserInfo
POST /api/deleteUser
POST /api/updateUserName

兄弟，你这是在写 RPC，不是在写 REST。区别在于：REST 的核心是「资源」，而 RPC 的核心是「动作」。

二、URI 设计：别把 URL 当作下水道

我见过最离谱的 API 长这样：

POST /api/v1/user-manager/delete-user-by-id

这是 URL，不是下水道，不需要塞得满满当当。

RESTful 的 URI 应该长这样：

DELETE /users/{id}

名词复数形式作为资源路径，HTTP 方法表示动作，绝了。

几个基本原则：用名词不用动词、复数形式、层级关系用路径、避免冗余。

三、状态码：你还在 200 走天下吗？

这个问题我几乎在每个 Code Review 里都会遇到。不管是「没找到」还是「参数错了」还是「服务器炸了」，一律返回 200，然后里面写个 code: 500。

我就想问一下，那你还要 HTTP 状态码干嘛？装饰品吗？

状态码是 API 的语言。服务器通过它告诉客户端发生了什么，客户端根据状态码决定怎么响应。

常用状态码：200 OK、201 Created、204 No Content、400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict、422 Unprocessable Entity、500 Internal Server Error。

四、错误处理：别让客户端去猜谜

很多 API 返回的错误长这样：

{ "code": 1002, "message": "操作失败" }

好的错误响应应该有类型、标题、状态码、详细错误列表。参考 RFC 7807 Problem Details 标准，给出 field 级别的错误信息。

五、分页：别让前端每次请求都拿10万条数据

标准分页：page 分页适合后台管理，cursor 分页适合消息流等大数据场景。没有银弹，但要有意识去选。

六、版本管理：不要让你的 API 像开盲盒

URL 路径版本控制是最简单最清晰的方案。/api/v1/users 和 /api/v2/users，别纠结那些「不够 RESTful」的吐槽。

七、最容易被忽视的：HTTP 头

Content-Type、Accept、Authorization、X-Request-ID（排查神器）、RateLimit 头……这些元信息很重要。

写在最后

API 设计看起来是技术活，实际上是沟通活。一个好的 API 设计标准是：看一眼文档，就能写对调用。

好的 API 设计靠的是约束和共识，不靠灵活和默契。那些「我们 team 都知道」的隐性知识，迟早会让你在凌晨三点的生产事故里付出代价。

少写点 if-else，多想点 URI 规范。共勉。