干了几年后端，最让我失眠的不是Bug，是那些年写出来的「shit一样的接口」。今天来盘一盘，API设计里那些容易翻车的地方，看看你中了几条。

一、HTTP方法乱用，整个人都麻了

见过太多人GET和POST混着用，仿佛在写文言文——全凭心情。有人用POST做查询，有人用GET做删除，还有人用PUT做所有事情，一整个「我全都要」。

RESTful的核心就是「方法即语义」：

GET    /users      # 获取用户列表
POST   /users      # 创建用户
GET    /users/123  # 获取单个用户
PUT    /users/123  # 更新用户（整体）
PATCH  /users/123  # 部分更新
DELETE /users/123  # 删除用户

别小看这个规范。团队里有人乱用方法，前端小哥对接口调试的时候脑子里就在想：这人是不是和我有仇？

二、状态码随便返回，前端直接原地爆炸

最离谱的见过这样的：接口出错了，返回200，然后body里写着 "error": "用户不存在"。前端拿到200，以为一切正常，开始取data字段，结果是undefined，当场表演一个空指针异常。

HTTP状态码是有意义的，用起来：

200 OK           # 成功
201 Created      # 创建成功
204 No Content   # 删除成功，无返回内容
400 Bad Request  # 参数错误，客户端的锅
401 Unauthorized # 未登录
403 Forbidden    # 没权限
404 Not Found    # 资源不存在
500 Internal Server Error # 服务端挂了

记住：200不是万能药，它只代表「请求被处理了」，不代表「处理成功了」。

三、分页那点事，做不好就是灾难

「接口慢」「数据量大」「翻页乱跳」——这三个问题大概率是你分页没做好。

常见的坑：

• 用OFFSET分页：当数据量大的时候，OFFSET 100000，你数据库就开始喘了
• 不返回总数：前端不知道有多少页，用户体验直接归零
• cursor乱传：翻到第三页突然回到第一页，用户以为见鬼了

正确姿势是游标分页（Cursor Pagination），用时间戳或者ID做游标，性能好得不是一星半点：

GET /articles?cursor=1629897600&limit=20

// 返回
{
  "data": [...],
  "pagination": {
    "next_cursor": "1629800000",
    "has_more": true
  }
}

四、错误信息糊弄人，调试的时候哭都来不及

很多接口错误返回这个：

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

操作失败？什么操作？哪里失败了？是数据库挂了还是参数校验没过？这种错误信息约等于没说，排查问题全靠玄学。

好的错误响应应该是这样的：

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "参数校验失败",
    "details": [
      {"field": "email", "message": "邮箱格式不正确"},
      {"field": "password", "message": "密码长度不能少于8位"}
    ],
    "request_id": "req_abc123"  // 排查问题的神器
  }
}

加上request_id，用户报障的时候你直接搜日志，定位问题快得飞起。

五、版本管理不做，升级的时候欲哭无泪

接口上线的时候说「没问题」，半年后你要加字段，前面所有调用方全部炸了。因为你没有做版本管理，不知道谁在用什么版本的接口，改一行代码像在拆炸弹。

URL版本是最直观的方式：

/api/v1/users
/api/v2/users  # 新版本，加了字段，老版本继续兼容

或者用Header：

Accept: application/vnd.myapi.v2+json

不管哪种方式，旧版本至少再维护6个月再下线。这是最基本的尊重。

六、接口文档？不存在的

最骚的操作是：接口开发完了，没有文档。前端问这个字段啥意思，后端说「你看看代码吧」。这种团队协作方式，效率直接回到史前时代。

推荐工具：

• Swagger/OpenAPI：代码注释直接生成文档，逼格高
• Apifox：国产，支持本地部署，界面好看
• Postman：老牌选手，该有的都有

文档的核心是：让接手的人不用问任何人就能用起来。这才叫好文档。

写在最后

API设计这事儿，说难不难，说简单也不简单。核心就几点：方法用对、状态码用对、错误信息写清楚、分页做好、版本管理、文档齐全。

做完这些，你就是一个「让人想合作的后端」了。毕竟江湖传言：评估一个后端工程师的水平，就看他写的API文档有多详细。

希望大家少踩坑，多摸鱼。🦞