干这行这么多年，我见过无数 API。有的是艺术品，有的是灾难片。

今天不整虚的，直接上硬菜——我见过最离谱的 REST API 设计错误，附赠正确姿势。看完你可能会菊花一紧，想起自己写过的某些代码。

别慌，咱一起脸红一起进步。

第一宗罪：用 POST 干一切

这大概是全世界最常见的 API 烂设计。

POST /getUser
POST /deleteOrder
POST /fetchProducts

兄弟，你把 POST 当万能钥匙用呢？

HTTP 动词不是装饰品，是语义担当：

• GET — 读取资源，不改变任何状态
• POST — 创建新资源
• PUT — 完整替换资源
• PATCH — 部分更新
• DELETE — 你猜

用 POST 干所有事，就像用扳手拧螺丝——能用，但总感觉哪里不对劲。

第二宗罪：URL 里塞动词

这个和第一宗是亲兄弟，经常一起出现。

GET /getUserById/123
POST /createNewOrder
POST /updateUserInfo

RESTful API 的 URL 应该是名词，不是动词。因为 HTTP 方法本身就是动词！

正确的打开方式：

GET /users/123
POST /users
PUT /users/123
DELETE /users/123

简洁、优雅、语义清晰。这才叫 API，不是命令行。

第三宗罪：命名随心所欲

我见过最绝的：

/product
/prod
/prods
/productsInfo
/allProducts
/productList

一个项目里 five different ways to say the same thing.

这就是 API 的薛定谔命名——你不知道这个接口到底叫什么，只有调用了才知道返回什么（可能什么都能返回）。

建议：团队先坐下来定好名词单复数规则，写进文档，刻烟吸肺。

第四宗罪：HTTP 状态码是什么，能吃吗？

见过最离谱的：所有接口永远返回 200，哪怕后端已经爆炸了。

{ "code": 500, "message": "服务器冒烟了", "data": null }

兄弟，你用 HTTP 状态码不用，用自己发明的 code？

标准 HTTP 状态码是干嘛用的：

• 2xx — 成功
• 3xx — 重定向
• 4xx — 客户端错误（你丫的错）
• 5xx — 服务器错误（我的锅）

请尊重这些状态码，它们比你发明的错误码通用一万倍。

第五宗罪：分页是什么，不存在的

我们的用户有一百万个——于是你的接口返回一百万条数据。

前端：我谢谢你。

后端：我谢谢你。

数据库：我不谢谢你们任何一个人。

正确的分页姿势：

GET /users?page=1&per_page=20

响应带上 metadata：

{ "data": [...], "pagination": { "page": 1, "per_page": 20, "total": 1000000, "total_pages": 50000 } }

这才是人和动物的区别。

第六宗罪：嵌套嵌套嵌套

见过最离谱的获取订单接口返回：

{ "order_id": "123", "user": { "user_id": "456", "profile": { "avatar": {...}, "settings": {...}, "preferences": { "theme": {...}, "language": {...} } } }

这是一个订单接口还是一个俄罗斯套娃？

你要的是订单信息，不是用户的前前前女友的宠物的生日礼物清单。

建议：按需返回，用 fields 参数控制，或者分开调用。你是在写 API，不是在写《百年孤独》。

第七宗罪：安全？什么安全？

见过最刺激的：

GET /user/123/profile?token=abc123

Token 放 URL 里？兄弟，这是要刻在服务器日志里的节奏啊。

正确姿势：Authorization Header。

Authorization: Bearer <token>

还有更刺激的——明文密码传输、SQL 拼接参数、没有任何权限校验...

我就不点名了，但这些哥们儿晚上真的睡得着吗？

说点正经的

好的 API 设计是门艺术，不是一门科学。它需要：

1. 一致性 — 命名、返回格式、错误处理，全项目统一
2. 可预测性 — 开发者看 URL 就知道干嘛的
3. 文档先行 — 没文档的 API 和没说明书的电器一样
4. 版本控制 — API 注定要变的，提前想好 /v1/v2
5. 考虑调用者 — 你写的 API 是给别人用的，不是在炫技

最后送大家一句话：你的 API 是你留给后人的礼物，或者是诅咒。代码会重构，但 API 往往要撑很久。

希望你的 API 不要成为后人的噩梦。

共勉。

有问题？评论区见。别客气，尽管吐槽。