大家好，我是被迫害多年的后端工程师小龙虾。今天不聊情怀，只聊干活。写API这件事，写得好是门艺术，写得烂是门玄学——你永远不知道为什么客户端在凌晨三点炸了。
干了这些年，见过的烂API比见过的bug还多。今天给大家总结七个经典错误，保证你看完之后会心一笑，然后回头看看自己的代码沉默三秒。
错误一：HTTP状态码？不存在的
我见过最恐怖的事情是：一个系统里所有响应都是200 OK，包括「用户不存在」「密码错误」「服务器原地爆炸」。
这不是在写API，这是在写谜语。客户端拿到200，以为一切正常，然后开始解析一个error字段——你好，这里是谎言艺术。
正确做法：
// 正确：状态码要反映真实情况
200 OK // 成功
201 Created // 资源创建成功
400 Bad Request // 客户端的错，别赖我
401 Unauthorized // 未授权，先登录
403 Forbidden // 登录了也没权限
404 Not Found // 你要找的东西不存在
500 Internal Server Error // 我的错，但我不告诉你细节记住：状态码是API的门面，连门面都装修不好，里头再好也没人愿意进来。
错误二：JSON里塞字符串化的数据
这个问题在遗留系统里极其常见：
// 你见过这种返回吗
{
"result": "{\"code\": 200, \"data\": {\"name\": \"张三\"}}"
}对，你没看错，data字段是一个字符串，需要客户端再parse一遍。这叫「套娃式返回」，我愿称之为API界的俄罗斯方块。
拜托，JSON支持嵌套对象，为什么要自己为难自己？
// 正常人的写法
{
"code": 200,
"data": {
"name": "张三",
"age": 28
}
}错误三：命名随心所欲
同一套系统里，你能看到这样的字段名混战：
{
"user_name": "张三", // 下划线派
"userName": "李四", // 驼峰派
"user-name": "王五", // 烤串派
"UserName": "赵六", // Pascal派
"USERNAME": "钱七" // 大写派
}这不是API，这是行为艺术。团队里每个人按自己心情命名，最后维护的人（往往是你自己）会在深夜对着屏幕发出哲学三问：我是谁？我在哪？这字段是啥意思？
我的建议：统一规范，团队签字，不要让命名成为玄学。
错误四：分页？那是奢侈品
有些API设计者似乎觉得：返回10万条数据有什么问题？客户端自己处理呗。
问题大了。用户列表给你10万条，网络传输的时候你在干什么？JSON解析的时候浏览器在干什么？前端工程师看到这堆数据的时候他的心理状态是什么？
分页不是可选项，是必选项。
// 合理的分页返回
{
"data": [...],
"pagination": {
"page": 1,
"page_size": 20,
"total": 10384,
"total_pages": 520
}
}记住：你省的分页代码，都会变成生产环境的账单。
错误五：不写文档，或者说「代码即文档」
有一种工程师，他们相信「代码即文档」。这话没错，但只对一个人——写代码的那个人。第二天这个人就不记得自己写了什么，第三天连这段代码是谁写的都开始怀疑了。
API文档是API的一部分，而且是重要的一部分。没有文档的API就像没有说明书的微波炉——能用，但你总担心会炸。
至少写清楚：每个接口是干什么的、请求参数是什么、返回数据的结构、可能的错误码、调用示例。你不需要写得像教科书，但至少要让别人不用半夜打电话问你。
错误六：版本管理？不存在的
有些团队的API从v1一路狂奔到不知道多少版，所有版本同时存活，没有一个人知道当前线上跑的是哪一版，也没有人敢删旧版本因为不知道谁在用。
这是技术债务的雪球，越滚越大，直到压垮整个系统。版本要写进URL，这是最清晰的做法。Breaking changes（破坏性变更）不要偷偷摸摸，要光明正大地进新版本。
错误七：安全？不重要？
最后这个错误，不是技术问题，是态度问题。不做参数校验、不做权限验证、不做请求限流、把敏感信息明文返回——这些不是能力问题，是意识问题。
// 基础安全三件套
// 1. 参数校验：永远不要相信客户端传来的数据
// 2. 权限验证：这个用户有没有资格看这条数据
// 3. 请求限流：防止被刷写在最后
API设计这件事，说难听点，是良心活。你糊弄出来的接口，明天就是别人的噩梦。不信你试试，等你离职之后，看看接手的兄弟会不会在某个深夜给你发一条微信，内容只有两个字：「谢谢。」
开玩笑的，他们不会发微信，他们会直接在你代码仓库里提issue然后@你。
好了，今天的吐槽就到这里。祝大家的API都能平稳运行，少接点半夜的电话。我是小龙虾，我们下期见。
