为什么你的API总被吐槽？这份RESTful设计避坑指南能救你

做后端开发这么多年，我见过太多API设计得让人想骂人。有个兄弟曾经跟我吐槽："调你们接口比追女生还难！"这话虽然夸张，但确实反映了一个现实——很多API设计得跟迷宫似的。

今天不整虚的，直接上干货。我从自己踩过的坑里提炼出几条实战经验，保证你看完就能用。

一、URL命名：别把API整成密码

先说个真实案例。有个遗留系统，查询用户的接口长这样：

/api/v2/u/q?id=123

我问你，你能猜到这是什么意思吗？反正我不能。

RESTful的核心是资源导向。URL应该是名词，不是动词。正确姿势：

GET /users/123          # 获取单个用户
GET /users              # 获取用户列表
POST /users             # 创建用户
PUT /users/123          # 更新用户
DELETE /users/123       # 删除用户

简洁、清晰、一目了然。新人接手也能直接看懂。

二、状态码：别总是200然后在body里藏error

这是我见过最离谱的设计——接口永远返回200，但body里写着{"code": 500, "msg": "服务器炸了"}。兄弟，你这是糊弄谁呢？

HTTP状态码是干嘛用的？就是告诉调用方发生了什么。给我用起来：

• 200 - 成功（GET、PUT成功）
• 201 - 创建成功（POST后）
• 204 - 无内容（DELETE成功后）
• 400 - 请求参数有问题
• 401 - 没登录
• 403 - 没权限
• 404 - 资源不存在
• 500 - 服务器炸了（尽量少用，多半是bug）

状态码是HTTP协议给我们的免费文档，用好它能省多少沟通成本？

三、分页：列表接口必备

如果你有个接口返回用户列表，几十万条数据一口气全返回——恭喜你，要么把服务器拖死，要么把调用方内存撑爆。

标准分页参数：

GET /users?page=1&page_size=20

返回格式也要统一：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1000,
    "total_pages": 50
  }
}

这样前端想怎么渲染就怎么渲染，不用每次都来问你"接口最多能返回多少条"。

四、版本控制：别让你的升级变成breaking change灾难

接口要升级怎么办？直接改？别闹。

正确做法是在URL里带版本号：

/api/v1/users
/api/v2/users

老接口继续服务，让调用方自己决定什么时候迁移。你好我好大家好。

有人会说"URL里带版本号不优雅"。兄弟，线上跑着几十个调用方的时候你就知道什么叫优雅了——稳定性比优雅重要一万倍。

五、错误信息：要能帮调用方定位问题

最烂的错误返回长这样：

{"error": "操作失败"}

操作失败是什么鬼？哪个环节失败了？为什么失败？

好的错误格式应该是：

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "指定的用户不存在",
    "detail": "user_id: 12345",
    "help": "请检查user_id是否正确"
  }
}

这样调用方看到错误码就知道怎么回事，甚至可以做一些自动化处理（比如错误重试、告警）。

六、POST/PUT的body：别给我返回一串数字

见过有些接口，POST创建一个订单，返回：

123456

就一串数字，鬼知道这是订单ID还是什么别的东西？

统一返回JSON格式：

{
  "data": {
    "order_id": 123456,
    "status": "created",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

而且重要操作最好返回完整的资源对象，让调用方不用再调一次GET。

总结

API设计本质上是一种承诺。一旦发布，调用方就会依赖它。改起来代价很大。

所以从一开始就设计好——清晰的URL、正确的状态码、完善的分页、合理的版本策略、有用的错误信息。这些看似是小事，但当你维护一个跑了三年的系统时，就会发现当年每一点小心思都值了。

最后送大家一句话：写API的时候想想三年后的自己会不会骂街。如果你会，那现在就改。

有问题欢迎留言，咱们一起探讨。