我写API这十年：见过的烂设计能绕地球三圈

干过后端开发的都知道，API这东西，写出来容易，写好难。我见过太多项目，代码写得漂亮，接口设计得一塌糊涂。今天就来聊聊那些让人看了想骂娘的API设计，顺便给你指条明路。

1. 动词乱用，URL像在写散文

先说个最常见的毛病——URL里堆满了动词。

POST /api/getUserInfo
POST /api/retrieveUserData
POST /api/queryUserDetails

兄弟，你是觉得RESTful是摆设吗？HTTP方法就是给你用的啊！GET是查询，POST是创建，PUT是更新，DELETE是删除。不用白不用的感觉是吧？

正确的姿势：

GET /api/users/123
PUT /api/users/123
DELETE /api/users/123

简单、清晰、一目了然。你又不是在写古文，动词往URL里塞什么塞？

2. 命名混乱，让人怀疑人生

有些项目的API命名简直是灾难片现场：

GET /api/get_user_info
GET /api/getUserInfo
GET /api/user-info
GET /api/UserInfo

同一个项目里，四种命名风格齐活儿。你说这是微服务？不好意思，这是微服务难民收容所。

我的建议：团队先定好规范，然后用工具强制执行。下划线还是驼峰，全大写还是全小写，必须统一。可以用ESLint插件或者后端的lint工具来做检查。

3. 状态码乱飞，200表示一切皆有可能

这是最让我血压高的设计——所有错误都返回200，然后在前端解析返回的code字段判断成功还是失败。

{
  "code": 500,
  "message": "用户不存在",
  "data": null
}

哥们儿，HTTP状态码是干嘛用的？你这是把HTTP当快递箱用，箱子上写着"易碎品"，里面塞了坨石头？

正确的做法：

HTTP 404 Not Found
{
  "error": "USER_NOT_FOUND",
  "message": "用户不存在"
}

该用什么状态码就用什么状态码，这是协议层面的默契，别自己发明一套。

4. 分页设计，抄都不会抄

分页是个重灾区。我见过：

// 方案A: 所有数据一口气返回
GET /api/users  // 返回10万条数据，前端当场去世

// 方案B: offset+limit，但没总数
GET /api/users?page=1&limit=20  // 你让我怎么渲染分页器？

// 方案C: 发明新概念
GET /api/users?cursor=abc123&count=20  // 这个cursor是什么鬼？

业界标准做法很简单：

GET /api/users?page=1&per_page=20

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "page": 1,
    "per_page": 20,
    "total_pages": 50
  }
}

或者用cursor-based pagination（适合实时性数据）：

GET /api/users?after_id=12345&limit=20

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJpZCI6MTYzNjV9",
    "has_more": true
  }
}

选哪种取决于你的业务场景，但别自己发明轮子。

5. 嵌套层级深得像文件夹

有人喜欢把返回数据结构得像俄罗斯套娃：

{
  "code": 0,
  "data": {
    "result": {
      "user": {
        "info": {
          "profile": {
            "name": "张三",
            "avatar": "https://..."
          }
        }
      }
    }
  }
}

你是在做API还是在玩找茬游戏？客户端的同事问候你全家了知道吗？

原则：扁平化设计，需要什么给什么。最多嵌套两层，再多就是给自己挖坑。

{
  "id": 123,
  "name": "张三",
  "avatar_url": "https://...",
  "created_at": "2026-06-21T10:30:00Z"
}

简洁、实用、看着舒服。

6. 文档缺失或过时，写了等于没写

有些项目的API文档，打开一看：

/api/user - 获取用户信息
POST /api/create - 创建用户

没了。就这几个字。你让调用方猜哑谜呢？

文档必须包含：

• 完整的请求参数说明（类型、是否必填、默认值）
• 响应结构详解（每个字段的含义）
• 错误码说明（每个code对应什么情况）
• 请求示例（curl、Python、JavaScript至少各一个）
• 认证方式（Bearer Token? API Key? 都写清楚）

推荐用Swagger/OpenAPI来写文档，代码即文档，文档即代码。

7. 版本管理像裸奔

最恐怖的是没有版本概念的API：

GET /api/users  // v1? v2? v3? 天知道

哪天你要重构这个接口，前端没来得及配合，直接炸锅。

标准做法：URL里带版本号

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

新版本上线后，v1再维护一段时间，给调用方足够的迁移时间。过渡完了再下线，历史包袱越背越重。

总结：好API的标准

说了这么多，其实好API就几个标准：

1. 简单直观——看URL就知道干什么
2. 一致性强——命名、响应结构、错误处理都要有统一规范
3. 状态码用对——别让200背所有的锅
4. 文档完善——代码即文档，文档是最小阻力
5. 版本可控——有规划地迭代，别裸奔

API设计这事，说到底是给人用的。多为调用方想想，少点自嗨，你的接口才能真正成为好接口。

下次你设计API的时候，想象一下调用你接口的那个兄弟——可能是三年后的你。

积点德吧各位。