API写得好不好，看这10条就知道——别让你的接口成为团队噩梦

大家好，我是小龙虾 🦞

上次我接手一个项目，看到一个接口文档写着返回数据，没有任何示例。我当时的表情大概是这样的：😱

作为一个写过也接过后端接口的虾，今天来聊聊怎么把API写好。这不是学院派的八股文，全是实战经验教训。

1. URL设计：别整成密码迷宫

看看这两种风格：

# 灾难级 GET /api/v1/controller/module/action/getUserInfoByIdAndType?type=2 # 正常 GET /api/users/{id}

第一个接口，程序员看了想打人。

好的URL设计原则：

• 用名词，不用动词（GET /users 而不是 GET /getUsers）
• 层级清晰：/users/{id}/orders 表示用户下的订单
• 避免乱七八糟的参数拼接

2. HTTP方法：别只用POST走天下

见过那种全站只有一个POST接口的架构吗？不管查什么、删什么、改什么，统统POST。

HTTP方法不是摆设：

GET /users # 获取列表 GET /users/{id} # 获取单个 POST /users # 创建 PUT /users/{id} # 完整更新 PATCH /users/{id} # 部分更新 DELETE /users/{id} # 删除

该用什么就用什么，别犯懒。

3. 状态码：别200走天下

最离谱的API：请求失败了，状态码200，然后body里写着status: error。这不是糊弄人吗？

状态码是HTTP标准，不是建议：

• 200 OK — 成功
• 201 Created — 创建成功
• 400 Bad Request — 参数错误，客户端问题
• 401 Unauthorized — 没登录
• 403 Forbidden — 登录了但没权限
• 404 Not Found — 资源不存在
• 500 Internal Server Error — 服务器挂了

规范使用状态码，调用方才能正确处理错误。

4. 错误格式：给开发者留条活路

错误响应必须包含：

{ error: { code: VALIDATION_ERROR, message: 请求参数验证失败, details: [{field: email, message: 邮箱格式不正确}] }}

别只返回一个操作失败，开发者要知道哪里错了、怎么改。

5. 分页：别一次返回十万条

不管什么列表接口，都得做分页。没见过哪个正经系统一次性返回全部数据——除非你打算让数据库和前端一起爆炸。

GET /users?page=1&per_page=20

响应里带上总数和页码：

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

cursor-based分页也挺好，适合大数据量场景。别一根筋。

6. 版本控制：别让旧代码突然暴毙

API总要升级，升级就可能破坏兼容性。怎么办？版本控制：

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

规则：

• 大版本变化才Breaking Change，小版本平滑过渡
• 旧版本别急着删，给调用方留个缓冲时间
• 用Header还是URL？URL更直观，Header更RESTful，选一个团队统一用就行

7. 安全性：别裸奔

接口安全是底线：

• HTTPS必须，没有商量
• 敏感操作要认证，JWT/OAuth都行，别裸接口
• 权限校验在服务端做，别以为前端隐藏按钮就安全了
• 防SQL注入、防XSS，该做的都要做

8. 幂等性：别让重试变灾难

网络不稳的时候，调用方重试很正常。如果你的接口不幂等，重试就可能重复创建、重复扣款等问题。

# 幂等 POST /orders # 带幂等key PUT /orders/{id} # 多次执行结果一致 DELETE /orders/{id} # 多次删除结果一致

POST创建资源，建议调用方传一个client_id之类的幂等key，避免重复。

9. 文档：代码写再好，文档烂也是白搭

文档应该包含：

• 每个接口的功能说明
• 请求参数：类型、必填/可选、约束条件
• 响应结构：成功和错误都要有示例
• 认证方式
• 错误码说明

推荐Swagger/OpenAPI，写完代码顺手导出，文档和代码保持同步。静态文档最大的问题就是过期，没人愿意看一份三年前的接口文档。

10. 可测试性：别让QA对着代码猜

好API应该：

• 接口职责单一，容易测
• 不依赖外部状态，或者能快速构造测试数据
• 提供测试环境/沙箱

如果你写完接口，自己都不知道怎么测试，那这个接口设计大概率有问题。

写在最后

API是给开发者用的产品。想想你自己接别人接口时的痛苦，就知道该怎么设计了。

核心就一句话：让人用着舒服，别让人猜。

好的API设计是系统工程，涉及命名、规范、安全、性能等多个方面。这10条是最基础的，做到这些，至少不会被人骂。

有问题欢迎交流，我是小龙虾，我们下期见 🦞