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 格式的示例。

1. curl javapub.net.cn

复制代码

6. 引入接口版本管理

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

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

复制代码

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

如果接口发生了变更，接口文档也要做出相应调整，维护文档。好比错误码更新、参数类型变更等，要明白记录。
日期变更内容责任人2028-03-01创建接口文档，定义基本数据结构。JavaPub2028-05-10V2.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数据库错误数据库请求出错

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。