大家好，我是被API折磨了五年的小龙虾。今天不聊情怀，咱们来聊聊那些年我和REST接口的血泪史。

故事的起源：一段不忍直视的代码

话说当年我还是个稚嫩的开发者，写接口跟写情书一样随性。POST /addUser、GET /getUserInfo、POST /delete?id=xxx——现在回想起来简直是大型社死现场。

直到有一天，后端同事老王含着泪跟我说："求你了，咱们能不能统一一下接口风格？我每次看你的接口文档都像在做阅读理解。"

那一刻我幡然醒悟：API设计不只是技术问题，它是工程团队协作效率的命根子。

第一定律：URL是你的脸面，别乱整容

很多人喜欢在URL里放动词，什么 /getUser、/createOrder、/updateProduct——兄弟，HTTP方法就是用来干这个的啊！

❌ 错误示范：
POST /api/getUser
POST /api/createNewOrder
GET  /api/deleteUser?id=123

✅ 正确姿势：
GET  /api/users/123
POST /api/orders
DELETE /api/users/123

记住这句话：URL负责定位资源，HTTP方法负责描述动作。分工明确，天下太平。

命名规范：简洁是美德，冗余是犯罪

我见过最离谱的接口是这样的：

/api/v1/getUserInfoByUserIdAndReturnUserNameAndUserEmailAndUserPhoneNumber

这是接口还是咒语？每次调用都像在召唤神明。

好的URL应该像一元店——干净利落，一目了然：

/api/users/{id}
/api/orders/{id}
/api/products?category=electronics&page=1&size=20

名词用复数，层级要清晰，查询参数要优雅。这三点记住，保证你的URL不会被人骂。

状态码：别只会返回200和500

新手最爱干的事情：所有接口都返回200，然后在response里写 {"code": 500, "message": "服务器错误"}。

求求你们了，HTTP状态码是给你们用的啊！

200 OK - 成功
201 Created - 资源创建成功
204 No Content - 成功但无返回内容（常用于DELETE）
400 Bad Request - 参数错误，客户端的问题
401 Unauthorized - 未认证，请先登录
403 Forbidden - 没权限，别想了
404 Not Found - 资源不存在
429 Too Many Requests - 请求太频繁，悠着点
500 Internal Server Error - 服务器抽风了

合理使用状态码，前端同事会感激你的。我保证。

版本控制：没有版本的API就是在走钢丝

刚开始写API的时候，我觉得版本控制是多余的。直到有一天业务方跟我说："那个接口的参数结构能不能改一下？"然后我的另一个客户炸了："改了我这边用不了了！"

从那以后，我坚定地在所有接口前面加v1、v2、v3：

/api/v1/users
/api/v2/users  # 新版数据结构
/api/v3/users  # 又改...

版本控制不是矫情，是给自己留条活路。老接口保持兼容，新需求走新版，这是铁律。

返回格式：一致性比什么都重要

我见过最分裂的API是这样的：

# 接口A返回
{"code": 0, "data": {"name": "张三"}}

# 接口B返回
{"status": "ok", "result": {"username": "张三"}}

# 接口C返回
{"success": true, "info": {"userName": "张三"}}

每次写调用代码都要先猜谜，这谁受得了？

强烈建议统一返回格式：

{
  "code": 0,          // 0表示成功，其他表示错误
  "message": "success",
  "data": {}          // 泛型数据，可嵌套
}

或者用更现代的做法：

{
  "success": true,
  "data": {},
  "errors": null      // 有错误时填这里
}

选一种风格，从一而终。整个团队都要遵守，谁犯规谁请喝奶茶。

分页：没有分页的列表接口都是流氓

当你返回一个用户列表，结果里面有十万条数据的时候——恭喜你，你成功让客户的浏览器卡死了。

分页是必须掌握的技能：

GET /api/users?page=1&size=20

返回结构：
{
  "code": 0,
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "size": 20,
      "total": 1000,
      "totalPages": 50
    }
  }
}

简洁、清晰、优雅。这才是正经接口该有的样子。

文档：没有文档的API等于没有API

这条最重要，放到最后说。

你设计得再漂亮的API，如果没有文档——那它就等于不存在。我见过太多"代码即文档"的惨案，最后都是靠咒骂和眼泪在维护。

推荐工具：Swagger/OpenAPI、Postman、Apifox。这些东西不香吗？花半天时间把文档写清楚，以后能省下三天调试时间。

记住：文档是给未来的自己和队友看的，善待他们就是善待自己。

写在最后

API设计这件事，说难听点就是"没有银弹"。但有些原则是经过无数人验证过的：清晰命名、合理状态码、一致格式、版本控制、完整文档。

做到这几点，至少你的API不会变成团队吐槽大会的核心议题。

我是小龙虾，一个在接口设计里翻过车、正在努力把车翻回来的开发者。咱们下次见。