你写的API接口，为什么总被人嫌弃？

做后端开发这么多年，我见过最离谱的事情，是一个同事把用户状态码用 1 和 0 表示，然后用字符串 "1" 返回给前端。前端小哥问他这是啥意思，他理直气壮地说："1就是启用，0就是禁用啊！"前端差点当场离职。

这不是故事，这是事故。

今天咱们来聊聊API设计——这个看起来谁都会，但实际上80%的接口都在挖坑的领域。我不会给你罗列什么"REST最佳实践"，那些东西你自己搜一下能看一百篇。我只说那些我在实际项目中被坑过、挣扎过、骂过娘的实战经验。

一、HTTP方法不是装饰品，别乱用

很多人写接口，POST和GET乱用，或者全用POST，美其名曰"统一接口"。我就见过这种：

POST /getUserInfo
POST /deleteUser
POST /listOrders

这是把HTTP方法当摆设。GET是幂等的、只读的、安全的；DELETE是删除；POST是创建；PUT/PATCH是更新。方法选对了，前端看接口文档的时候脑子里是清晰的；方法乱用，前端看到你的接口心里是崩溃的。

RESTful不是银弹，但用好HTTP方法是最基本的职业道德。

二、状态码比你的接口文档有人看

状态码是接口的门面，但你看看多少人把它玩坏了：

• 永远返回200，然后在body里写 {"code": 500, "msg": "服务器错误"}
• 404表示"用户不存在"，403表示"密码错误"
• 200 OK 但 body 里是空的，让前端去猜

拜托，HTTP状态码是给谁设计的？是给HTTP客户端、CDN、网关、浏览器看的。你返回一个200但实际是错误，前端的错误处理逻辑直接抓瞎，运维的监控系统也识别不出来。

我的原则很简单：

• 2xx：真的成功了
• 4xx：客户端的错，你改请求就能解决
• 5xx：服务端的错，你改代码才能解决

别在状态码里夹带私货，该是什么就是什么。

三、返回结构不一致，是最贵的债

有时候一个项目里，查用户的接口返回：

{"id": 1, "name": "张三", "email": "zhangsan@example.com"}

查订单的接口返回：

{"code": 0, "data": {"order_id": 100, "amount": 299}}

删数据的接口返回：

{"success": true, "message": "删除成功"}

三个接口三种格式，前端每接一个都要单独适配，代码里充斥着各种if-else判断。这不是接口，这是接口的七国大乱。

我的建议是统一响应格式，而且要早定规范，不要等项目做了一半再改：

{
  "code": 0,
  "message": "OK",
  "data": {}
}

就这么简单。但关键是——所有人、所有接口都必须遵守。代码评审的时候把这个加进去，谁格式不对就给他打回去。

四、命名：你的接口名字暴露了你的品味

见过这些"佳作"吗：

/api/getData
/api/doSomething
/api/handle
/api/jiekou

最后一个是认真的吗？"jiekou"是拼音，这是接口命名里的随地大小便。

好的命名应该是不用文档也能猜出干嘛的：

• GET /users/{id} — 获取用户，清晰
• GET /users/{id}/orders — 获取某用户的订单，RESTful风格
• POST /users/{id}/deactivate — 禁用用户，比 POST /updateUserStatus 语义更明确

URL用名词复数，路径体现资源层级，动词用HTTP方法表达。这不是教条，这是让人能看懂你的接口。

五、分页不是可选的，是必须的

我见过有人写列表接口，不做分页，直接 select * from users 返回全表。测试环境几十条数据跑得飞快，上生产第一天服务器就冒烟了。

分页参数要统一，我的习惯是：

GET /users?page=1&page_size=20

返回结构：

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

不要让前端自己算分页逻辑，人家不是来给你打工的。

六、版本号是你给未来留的退路

接口不是写完就完事的，你要改，但改了你不能影响已有的调用方。怎么办？版本号。

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

不是说版本号越多越好，而是当你真的有破坏性变更的时候，有一个平滑过渡的方案。不要相信"我们内部接口不会有人调用"这种话——往往说这话的项目，后来都被其他系统接了个遍。

七、安全这件事，别等出事了才想起来

不展开说，就说几个最低限度：

• 敏感操作（增删改）必须有权限校验，不要以为前端做了校验就够了
• 不要在URL里传密码或token，GET请求会被日志记下来
• 接口要有防刷机制，不然分分钟被人爬光
• 返回的数据要做脱敏，用户手机号、身份证号不能裸奔

写在最后

API设计这件事，说难听点，是后端程序员的门面。你的代码可以写得丑，但接口设计烂了，整个团队都要陪你受罪。前端在骂你，运维在骂你，后来接手的人在心里画圈圈诅咒你。

好的API设计不是什么高深的技术，就是多站在调用方想一想，把自己能做好的部分做到位。命名清晰一点，格式统一一点，状态码用对一点，文档写清楚一点。这些小事做好，你就是一个靠谱的后端。

至于那些还在用 POST /jiekou 的人——我只能说，欠下的债迟早要还的。