做后端开发这么多年，见过无数让人想砸键盘的API。有些是历史遗留问题，有些是新手村的标配操作，还有些是你永远不知道当时的脑子在想什么。 今天就来盘点一下那些让人血压飙升的API设计，保证你看完会说"我以前也这样干过"——然后默默去改代码。

1. 返璞归真：用HTTP状态码表示一切业务逻辑

有些人觉得HTTP状态码是万能的：

200 - 用户余额不足
200 - 登录成功
200 - 服务器爆炸了
200 - 你没有权限访问这个接口

兄弟，200的意思就是"啥都OK"，你把它当成瑞士军刀用，最后结果就是所有人都得去看响应体才能知道到底发生了什么。这不叫RESTful，这叫"我觉得状态码很酷"。

2. 泛泛而谈的错误信息

错误信息写得跟星座运势一样模糊：

{
  "error": "操作失败",
  "code": -1
}

操作失败了，为什么失败？是数据库炸了还是参数不对？-1是什么意思？谁也不知道。 正确的错误信息应该像诊断书一样精确：

{
  "error": "库存不足",
  "code": "INVENTORY_INSUFFICIENT",
  "message": "商品SKU-2024-Xiaolongxia库存不足，当前剩余5，用户请求10",
  "requestId": "req_abc123"
}

3. 命名玄学：拼音+缩写+数字的完美风暴

见过最离谱的接口命名：

/api/v1/user/getById
/api/v2/u/gbi
/api/v3/userinfo/query

第三个版本的开发者的内心："反正没人能看懂，我自己也看不懂，这样反而安全。" 安全是安全了，维护的时候大家集体看天。 API命名应该自解释，用完整的英文单词，让陌生人也能猜到用途。

4. 签名验证：让黑客看了都想帮你改bug

有些签名算法复杂到开发者自己都记不住，每次调试都是玄学：

sign = MD5(appId + timestamp + MD5(secret + "abc" + version) + randomStr)

这种设计除了制造bug之外没有任何意义。签名算法应该简单到你能向产品经理解释清楚——如果你解释不清，说明这个设计本身就是过度工程化的垃圾。

5. 分页：薛定谔的下一页

有些API的分页逻辑是你永远不知道下一页存不存在：

{
  "data": [...],
  "hasMore": true,
  "total": null,
  "nextPage": null
}

hasMore是true但nextPage是null，这是什么意思？是还有数据还是网络抖了？ 这种不确定性会让调用方陷入无尽的猜测。分页应该给出明确的可信信息：要么给totalCount和总页数，要么给nextCursor让调用方无脑翻页。

6. 时间格式：每个人的内心都有一把锤子

有些系统的时间格式是随机的：

"createdAt": "2024-01-01 00:00:00"
"updatedAt": "2024/01/01 00:00:00"
"deletedAt": "1704067200"
"expiredAt": "Mon Jan 01 2024 00:00:00 GMT+0800"

{
  "code": 200,
  "data": {
    "result": {
      "info": {
        "user": {
          "profile": {
            "settings": {
              "preferences": {
                "notifications": {
                  "email": true
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "users": ["张三", "李四", "王五"],
  "roles": ["admin", "editor", "viewer"]
}

if (code == 10086) {
    // 移动用户特殊处理
    giveMoreQuota();
}

/user/get - 获取用户信息
必填参数：无
选填参数：无
返回：用户信息