做后端开发这么多年，我见过太多「能跑就行」的API。它们确实能跑，但用的人每天都在心里问候开发者。以下是我见过的5个高频糟心事，看看你中了几条。
坑1：HTTP状态码乱用
你永远不知道有人会把404返回给「用户不存在」，把500返回给「密码错误」。我就问一句：密码错误是服务器挂了吗？
正确的做法其实很简单：
- 400系列 → 客户端的锅，你请求有问题
- 401 → 没登录 / 认证失败
- 403 → 登录了但没权限
- 404 → 资源不存在（真的不存在）
- 422 → 请求格式对，但语义有问题（比如校验失败）
- 500 → 服务端炸了
记住：状态码是你的API给开发者的第一语言，说清楚点。
坑2：错误响应Body跟个谜语人似的
你有没有见过这种错误返回：
{
"code": "ERR_INVALID_PARAM",
"message": "Invalid parameter"
}好家伙，invalid哪个参数？不告诉你。正确值是什么？不告诉你。你能怎么办？去读文档吧您呐。
一个好的错误响应应该是这样的：
{
"error": {
"code": "VALIDATION_FAILED",
"message": "请求参数校验失败",
"details": [
{
"field": "email",
"message": "邮箱格式不正确",
"rejected_value": "abc"
}
]
}
}看，这才叫有效沟通。
坑3：分页返回total等于-1
什么？你问我为什么分页接口不返回总数？「因为数据库量大，性能不好」。好，那你至少告诉我有没有下一页啊！
两种推荐方案：
- Cursor-based pagination：返回next_cursor，下一页用cursor去拿，简单高效
- Limit/Offset + has_more：返回has_more字段，告诉前端「还有」，比total靠谱多了
别让你的API用户做无谓的请求。
坑4：把API版本号藏起来
「我们没版本号概念，URL里不需要v1/v2。」好，半年后你要breaking change的时候怎么办？强制用户升级？偷偷改行为？
URL版本控制虽然不完美，但它是事实标准：
GET /api/v1/users
GET /api/v2/users用户可以选择什么时候迁移，你也可以平滑过渡。双赢。
坑5：鉴权错误返回404
这个我真的要单独拿出来骂。有些API，没登录访问受保护资源，返回404。「安全」嘛，别人不知道你有哪些接口。
但这是脱了裤子放屁。攻击者稍微试试就知道你这个URL存在不存在，返回404反而让正常用户一脸懵。
正确做法：返回401或403，并明确告知需要认证。安全不是靠假装不存在来实现的。
总结一下
好的API设计本质上是一种用户体验设计。你的用户是其他开发者，他们的痛点你要感同身受。
记住三句话：
- 状态码要精准，别让开发者猜
- 错误响应要有用，别返回黑箱
- 分页和版本要提前想好，别到时候拍脑袋
API是你给世界的接口，精致点。
