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

简介: 后端工程师需重视接口设计,提供清晰规范的接口文档以节省合作时间,避免纠纷。关键点包括:1) 接口名称应直观明了;2) 接口路径规整,能反映接口功能;3) 使用恰当的请求方式(GET, POST, PUT, PATCH, DELETE);4) 提供详细接口说明和示例;5) 实施接口版本管理,更新文档以适应变更;6) 明确请求头信息;7) 关注接口安全,进行参数加密和授权;8) 编写测试案例和错误码定义,方便调用者理解和测试。

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

74076262d8f14d5390e1ba557e0296a0

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

接口设计规范JavaPub

1. 接口名称清晰、明确

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

img

2. 接口路径规整

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

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

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

4677eb13-b696-43be-b530-60766742a4e3

3. 请求方式规范

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

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

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

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

eb21c081-f26c-4c8c-9197-4a35573e8b04

4. 接口详细说明

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

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

006r3PQBjw1fb5h84baewj306404lmx9

5. 编写接口请求示例

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

curl javapub.net.cn

img

6. 引入接口版本管理

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

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

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

56d7cbc6-0b2c-4a90-ac37-a8e65c040d47

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

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

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

b4fe3684d20e97fa311ca213c8dc7ea9

8. 明确请求头有哪些

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

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

image-20240521104426851

9. 接口安全

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

image-20240521104647299

10. 接口测试

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

image-20240521105043027

11. 定义错误码

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

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

image-20240521104901378

目录
相关文章
|
算法 测试技术 数据安全/隐私保护
如何写一份优秀的接口文档(下)
如何写一份优秀的接口文档(下)
906 0
|
SQL 前端开发 安全
详细介绍前后端分离必备的接口规范,包括命名规范、参数规范、错误处理规范等
详细介绍前后端分离必备的接口规范,包括命名规范、参数规范、错误处理规范等
3403 1
|
XML 域名解析 JSON
【RESTful】RESTful API 接口设计规范 | 示例
【RESTful】RESTful API 接口设计规范 | 示例
12311 0
【RESTful】RESTful API 接口设计规范 | 示例
|
JSON Java Apache
Bean自动映射工具对比及VO、DTO、PO、DO对象之间的转换
在实际的开发过程中,常常遇到各个层之间对象转换,比如 VO、DTO、PO、DO 等,而如果都是手动set、get,一旦属性较多时,操作起来不仅麻烦,而且浪费时间,因此经常会使用一些工具类,进行对象之间的转换,下面将对象与对象之间转换的方式进行对比,一级对象间的使用进行总结。
Bean自动映射工具对比及VO、DTO、PO、DO对象之间的转换
|
12月前
|
缓存 监控 测试技术
接口设计的18条军规:打造高效、可靠的API
【10月更文挑战第2天】在软件开发中,接口设计是连接不同模块、系统乃至服务的桥梁。一个优秀的接口设计不仅能提升开发效率,还能确保系统的稳定性和可扩展性。以下是接口设计的18条军规,旨在帮助你在工作和学习中设计出更加高效、可靠的API。
470 1
|
SQL JSON API
接口设计的18条军规
本文介绍了接口设计的18条最佳实践,包括签名防止数据篡改、加密敏感信息、IP白名单增强安全性、限流保护服务、统一返回值结构、异常统一处理、请求日志记录、幂等性设计、限制请求记录条数、压力测试、异步处理、数据脱敏、完整接口文档、合理使用请求方式、利用请求头传递参数、设计批量操作接口和职责单一原则。这些规则旨在确保API接口的安全、稳定、高效和易于维护。
186 3
|
Java 数据处理
接口设计规范
接口设计规范
599 2
|
测试技术 API
接口设计原则与最佳实践指南
接口设计原则与最佳实践指南
|
设计模式 移动开发 Java
【阿里规约】阿里开发手册解读——代码格式篇
本文所有代码格式规范遵循《阿里规约》,从编码、换行符、空格规则、括号规则、字符数等方面展开,详细阐述方法参数、强制转换、运算符、缩进等元素的编写规范。
【阿里规约】阿里开发手册解读——代码格式篇
|
存储 关系型数据库 MySQL
【阿里规约】阿里开发手册解读——数据库和ORM篇
从命名规范、建表规范、查询规范、索引规范、操作规范等角度出发,详细阐述MySQL数据库使用过程中所需要遵循的各种规范。
【阿里规约】阿里开发手册解读——数据库和ORM篇