11条军规,让你的接口设计无可挑剔

作为后端工程师,多数情况都是给别人提供接口,写的好不好使你得重视起来。

最近我手头一些活,需要和外部公司对接,我们需要提供一个接口文档,这样可以节省双方时间、也可以防止后续扯皮。这是就要考验我的接口是否规范化。

1. 接口名称清晰、明确

顾名思义,接口是做什么的,是否准确、清晰?让使用这一眼就能知道这个接口在做什么,力求言简意赅。比如:查询用户信息,简单明了。

2. 接口路径规整

接口地址,也就是接口的 URL 路径。当别人调用你的接口,就是通过 URL 配合请求时参数来调用。比如: /api/user/queryById 。一般来说,接口地址的命名也要可以大概看出接口的作用,比如前面这个接口,它是作用使用:通过用户id查询用户信息

除了接口路径,还需要指明接口的域名或IP。以 http 协议为例、端口是 8080,当我请求 javapub 的用户中心信息时:

https://javapub.net.cn:8080/api/user/queryById

3. 请求方式规范

请求方式常用的有如下几种:

  • GET(SELECT):从服务器取出资源,通常用于查询数据(一项或多项)。
  • POST(CREATE):在服务器新建一个资源,通常用在新增、修改、删除操作。
  • PUT(UPDATE):在服务器更新资源,通常用于更新数据(客户端提供改变后的完整资源)。
  • PATCH(UPDATE):在服务器更新资源,通常用于修改部分数据(客户端提供改变的属性)。
  • DELETE(DELETE):从服务器删除资源,通常用于删除数据。

这么多请求方式,多数中小公司只用 GET 和 POST,可能还有些公司只用 POST。但是选择合适的请求方式可以提升开发效率、并且让我们的接口更容易复用。

不管用哪种,一定要写清楚。

4. 接口详细说明

如果是非常简单的接口,通过接口名就可以了解个大概。如果是一些非常复杂的接口,就一定要添加详细说明文档,包括功能描述、请求参数、请求相应参数等信息。

力求言简意赅,通过入参、做了什么动作、返回哪些值。

5. 编写接口请求示例

接口文档需要提供接口示例,接口实例是为了帮助调用者理解接口的使用方法和调用流程,快速开始调试程序。一般是 CURL 格式的示例。

curl javapub.net.cn

6. 引入接口版本管理

随着功能开发的日趋完善,可能对接口做出修改更新,例如添加、删除时变更参数,或者修改返回值的格式。这些新变更可能影响用户的 API 使用体验,造成现有客户端无法使用。

https://javapub.net.cn:8080/api/user/v1/queryById

https://javapub.net.cn:8080/api/user/v2/queryById

7. 维护接口文档版本更新

如果接口发生了变更,接口文档也要做出相应调整,维护文档。比如错误码更新、参数类型变更等,要明确记录。

日期 变更内容 责任人
2028-03-01 创建接口文档,定义基本数据结构。 JavaPub
2028-05-10 V2.0用户中心接口更新 王哥

8. 明确请求头有哪些

接口文档,要写清楚请求头信息,比如:有权限校验的接口请求,在请求头中 apiKey。还有一些参数是 JSON 的,要设置 application/json

  • Accept:指定客户端能够接收的内容类型,如:Accept: text/plain, text/html
  • Authorization:一般存放令牌信息,如:Authorization: Basic QzPhZGRpbjpvcGVuIHNlc2FtZQ==
  • Cookie:存放 Cookie 信息。
  • User-Agent:指定客户端信息,作为服务端处理时定制化。
  • Accept-Encoding:指定客户端允许的数据压缩格式,如 gzip、deflate 等。

9. 接口安全

有些接口参数涉及到隐私和敏感数据、需要参数加密做好脱敏处理和说明。此外,还要做好接口授权访问,防止出现拖库、击穿等P0问题。

10. 接口测试

在编写接口文档时,编写测试案例也要给出测试数据,包括请求参数和返回结果。让调用者有一个预期,节省沟通成本。

11. 定义错误码

接口文档,一定要错误码,错误码作为程序重要的参考,让下游知道什么时候做什么动作。比如:当查询不到用户信息时,可以提示它跳转到注册页面。

错误码 名称 说明
1001 参数错误 参数不合法
1002 数据库错误 数据库请求出错

热门相关:龙腾四海   女校友   爱的躯壳   艳事妈咪日记   MZ世代的第一次经验