如何设计好 API 接口？

API接口设计得好不好，直接影响系统的可维护性。今天分享一下设计接口的经验。

好的API长什么样

1. 命名清晰

看名字就知道这个接口是干什么的。

好：GET /users/{id}
坏：GET /getData?type=user&id=1

2. 符合RESTful规范

  • 用名词不用动词：/users，不是 /getUsers
  • 用HTTP方法表示操作：GET查询，POST创建，PUT更新，DELETE删除
  • 用复数：/users，不是 /user

3. 返回合理的状态码

  • 200：成功
  • 400：请求参数错误
  • 401：未登录
  • 403：没权限
  • 404：资源不存在
  • 500：服务器错误

不要什么情况都返回200。

4. 统一的响应格式

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

不管成功还是失败，都用统一的格式，方便前端处理。

设计接口的步骤

1. 明确需求

这个接口要实现什么功能？谁来调用？

2. 设计URL

用什么HTTP方法？URL怎么命名？

3. 定义参数

需要传什么参数？参数放在URL里、Query里还是Body里？

4. 定义返回值

返回什么数据？什么格式？

5. 考虑异常情况

参数错误怎么办？数据不存在怎么办？没权限怎么办？

一些实用建议

1. 版本控制

接口可能会升级，加上版本号：/api/v1/users

2. 分页

列表接口要支持分页：/users?page=1&size=10

3. 字段过滤

有时候不需要返回所有字段：/users?fields=id,name

4. 文档很重要

用Swagger或者Apifox生成接口文档，保持更新。

5. 保持一致性

整个系统的接口风格要一致。比如时间格式、字段命名风格、错误码定义。

常见的坑

1. 一个接口做太多事情

一个接口又查询又更新又删除，太复杂了。

一个接口只做一件事。

2. 接口设计和数据库表一一对应

接口应该面向业务场景设计，不是面向数据库设计。

3. 随意改接口

接口一旦上线被使用，就不要随便改。要改就加新版本。

4. 没有文档

接口没有文档，前端只能靠猜或者问你。

最后

API设计是后端的基本功。

设计得好，前端用着舒服，后续维护也方便。设计得差，大家都痛苦。

多看看优秀的API设计（比如GitHub的API），学习别人是怎么设计的。

上次更新: