你的API设计正在偷偷毁掉你的后端同学
我见过太多团队，一边喊着"微服务"、"前后端分离"，一边写出的API能让下一个接手的开发者当场转行卖红薯。今天咱们不整那些虚头巴脑的概念，就聊聊实际开发中那些让人血压飙升的API设计惨案，以及怎么优雅地避开它们。
一、HTTP方法乱用：POST干GET的活，PUT干DELETE的活
见过最离谱的：一个查询接口，POST方法体里塞查询条件，返回的数据里还带着操作结果。更绝的是，他们给这个接口起名叫doQuery。
我真想问问那位前辈，您是跟HTTP协议有仇吗？
// 这是什么魔鬼写法
POST /user/delete?id=123
// 正常人就该这么写
DELETE /user/123HTTP方法不是装饰品，它是协议的一部分。用错了，轻则被人嘲笑，重则在排查问题的时候把自己坑哭。GET就是查，POST就是创建，PUT就是完整替换，PATCH就是部分修改，DELETE就是删除。做不到位的对应关系，就别怪前端同学在群里@你。
二、状态码：200表示出错，404表示成功
这是另一大重灾区。有些团队的API永远返回200，哪怕是服务器原地爆炸了，也给你返回一个完美的200 OK，里面data字段是个error对象。
{
"code": 200,
"message": "success",
"data": {
"error": "数据库连接失败",
"stack": "..."
}
}我懂你们的苦——前端框架有些对非200状态码的处理太蠢了，所以你们选择"曲线救国"。但这种做法本质上是在给自己埋雷。哪天线上出了问题，日志里全是200，但服务已经躺了，你能想象那个画面吗？
标准HTTP状态码是给机器读的，也是给人读的。403就是没权限，429就是请求太频繁，500就是服务端炸了。别觉得返回500丢人，那是诚实的表现。
三、命名：一千个开发者有一千种命名法
这个问题在大型项目里特别明显。今天这个开发用驼峰，明天那个用下划线，后天又冒出来个匈牙利命名法的遗老。
// 看看这个接口返回的字段
{
"user_name": "张三",
"userName": "李四",
"strUserNm": "王五", // 这位是认真的吗？
"user_age": 28,
"userAge": 30
}命名混乱是API设计中最容易出现、最难治理、危害最持久的问题。我的建议是：团队在项目启动之初，就出一份API命名规范文档，越详细越好。而且要用工具来约束——CI阶段做lint检查，不合规范的字段直接打回去重写。别指望程序员的自觉性，那玩意儿在Deadline面前一文不值。
四、接口粒度：要么太粗，要么太细
先说太粗的问题。有些"大牛"喜欢搞一个万能接口，/api/common?action=xxx，通过action参数区分业务逻辑。一个接口打天下，路由逻辑全靠if-else撑着。看起来简洁，实际上是噩梦——你根本没法单独测试，没法独立缓存，没法精确限流。
再说太细的问题。有些工程师对"高内聚低耦合"有应激反应，走向了另一个极端——每个小操作都单独拆成接口。用户列表要一个接口，用户头像要一个接口，用户在线状态再来一个接口。前端同学调个渲染，得发七八个请求，页面直接卡成PPT。
好的API粒度，是让接口的职责边界清晰到可以用一句话描述清楚："这个接口查用户列表"，"这个接口更新用户头像"。说不清楚的，就说明拆得有问题。
五、文档：写了等于没写
这是最让我崩溃的。有些API文档长这样：
接口：获取用户信息
方法：POST
参数：userId（用户ID）
返回：用户信息
备注：无
无。你给我个无。userId是什么格式？字符串还是数字？最长多少位？用户不存在的时候返回什么？权限不够的时候又返回什么？这些统统没有。
我强烈建议每个团队都上一套OpenAPI/Swagger规范，然后用代码生成文档。文档和代码必须保持同步——怎么保证同步？用代码生成文档，而不是文档驱动代码。程序员可以接受写代码，但接受不了维护两套同时失效的东西。
六、版本管理：没有的版本就是最烂的版本
很多团队的API压根没有版本的概念。/user/get今天是这个逻辑，明天业务变了，可能就直接改成了另一个逻辑。旧客户端用的是旧逻辑，新客户端用的是新逻辑，出了bug你都不知道是该从哪个版本开始查。
版本号不是矫情，是保险。/api/v1/user和/api/v2/user可以同时存在，v1慢慢退役，v2稳定运行。不香吗？
# 版本管理策略
/api/v1/users # 旧版本，维护但不新增功能
/api/v2/users # 当前版本
/api/v3/users # 规划中，面向未来需求七、最容易被忽视的一点：错误信息得有用
很多API的错误信息是这样的：
{
"error": "操作失败"
}操作失败。好的。请问是什么操作？哪一步失败了？为什么失败？下一步该怎么办？全都不知道。前端同学面对这个错误信息，除了弹一个"操作失败，请稍后再试"之外，什么也做不了。用户看了只会觉得这产品烂透了。
好的错误信息应该长这样：
{
"error": {
"code": "USER_NOT_FOUND",
"message": "用户不存在",
"detail": "根据user_id: 12345678 未找到对应用户记录",
"suggestion": "请检查user_id是否正确，或该用户已被删除"
}
}你看，这是有温度的报错。有代码，有人类可读的信息，有排查方向，有用户指引。这才叫专业的API。
写在最后
API设计这事，说难不难，说简单不简单。难就难在它需要你在"功能完整"和"接口简洁"之间找平衡，需要你在"当前需求"和"未来扩展"之间做取舍，需要你时刻记住：你的API不只是给机器调用的，也是给下一个维护它的开发者看的。
好的API设计，是最好的技术文档。它自己会说话，不需要你额外解释。
下次写接口之前，想象一下三个月后的自己打开这段代码——你是想骂娘还是想点赞？答案就是你现在的设计水平。
祝大家的API都能让人点赞，而不是让人骂娘。
