接口测试 你是这么写接口的么

CKL的思考 · 2023年06月02日 · 最后由 Mr.Shuo 回复于 2023年08月01日 · 8083 次阅读

本文是来自一位前端人员的吐槽,笔者自己在做接口测试的时候,也会发现各类不太合理的接口定义,看看前端人员怎么说。

相信很多开发经理,尤其是 Java 开发主管都会遇到这样的人,有的工程师被招进来,没干两个月就跑了,你问他,他就说只写写接口,没啥挑战,没有前途,于是就离职了,但是当你去看看他写的代码,发现真的 “很烂”,一个连接口都写不好的人,还抱怨没有挑战,连基本的事情都做不好,有什么资格做更 “牛逼” 的工作呢?

一个接口可以 10 分钟搞定,复杂的搞个一周都有可能,有时我们在项目中可能急于完成任务,而忽视了其他方面,但,我认为有些问题是可以提前避免的。

01

接口能实现功能就可以了吗?如果这样,那么上图中的骚操作可以满足大部分场景,或者前端把数据库表传给后端,后端直接把表中数据查出返回就可以了,这种 “数据中转工程师” 的确没啥前途。

什么是好的接口?

一个能满足需求实现的接口远远达不到 “好” 的标准,我相信大部分的 Java 工程师都可以写出满足需求实现的接口,但是并非所有人都能写出好的接口。

我相信,好的接口具有:良好的结构,精简的数据,自洽的逻辑和清晰的调用关系,规范的路由,易懂的代码,快速的响应,完善的异常处理,周到的场景覆盖,易扩展且稳定运行... ...

and more!

02

问题一:凌乱地返回信息

不需要的信息不要返回,不是一股脑把所有信息返回让前端按需使用。

命名要简洁,比如 listObject 可以改成 list, itemCount 改为 count 或 total

字段要达意:dashBoardAuth, isAllAuth, isAuthDataset 几个都是认证权限相关的,可以放在一起:

auth:{
dashboard : true,
all : 0,
dataset : 0
}

返回信息凌乱,并不会造成功能不可用。凌乱是指很多没用的字段,结构混乱等,理论上无论结构有多混乱,字段里有多少干扰,前端都可以取得到数据,无非多做一些澄清和确认,多做一些格式转换,但清晰的结构,仅返回有用的字段,会使后期理解和维护过程变得更加容易。

如果返回的信息不凌乱,前端后对接会变得更加和谐和默契。

笔者注:过多的返回值,也会引发性能、网络、安全等一系列问题,需要引起重视

问题二:命名不合理

permission 和 privilege 的含义重复,应该简写为:permissions.view,命名除了统一风格(匈牙利风格,驼峰风格等)外,还要尽可能简化,不要有错误的英文,能简化的尽量简化,不要啰唆,结构的层次可以分层地表达含义,没必要在后面的层级中再加上父层的含义。

比如在接口路径中,实际项目中常常存在这种情况:

上面的路径不够简洁,dashboard/group/dashboardTreeList 这个路径中有两相 dashboard,前者已经指明了此接口是/dashboard/模块下的,后面就不需要再出现了,应改为:dashboard/group/treeList

笔者注:这个是规范的问题,产品级的系统,还是要注意规范化编码,减少人为障碍

问题三:路由风格要统一

接口风格不统一,有些是 Rest 风格的,有些不是 Rest 风格的

问题四:所有接口全部合成一个

上图是某项目的销售简报,从电商迁移过来的,一个页面中有多个图表,但全部用一个接口查询返回,我想大部分人都知道这会造成性能问题,不仅后端服务器有压力,也没有很好地利用浏览器的并发请求能力,对界面渲染也不友好。

笔者注:按模块给接口,既可以充分利用 HTTP 的并发能力,也可以很好地实现首频加载之类的性能优化,不能为了减少请求而合并接口

问题五:数据格式问题

数据格式不规范,数字不要加引号

数据格式前端处理,数据库里也不要存成文本,不要进行单位转换(如转成万、亿等),后端不要对小数位数做处理,这些操作都应前端处理。

为什么前端处理这种格式呢?因为 UI 和用户需求是经常变的,如果某天用户把小数位数由保留 1 位改成保留 2 位小数,前端修改起来要容易得多,而且部署也不会造成服务器重启,只用刷新浏览器即可。

现在前端多是基于 SPA 的前后端分离地开发,打包多会有 HASH 码,很少会影响页面访问,但放在后端处理就困难得多。

笔者注:展示的事,交给前端,数据格式一定要定义清楚,可以减少大量非必要的隐式转换

问题六:返回的字段要统一,保持一致性

一个系统中不同的接口返回的数据,命名都不统一,比如用户账号,有时用 userId,有时用 username,有时用 userName,有时用 nickName,有时用 userNo,甚至内一个接口内都没统一,这对于前后端对接是不友好的,当然,这些也不会影响功能使用。

这些问题,真的无关紧要吗?

笔者注:接口测试人员的灾难,其实这也是数据治理的一部分

03

虽然上述的各种问题不能影响需求交付,但如果上述问题积累太多,就会变成代码屎山,非常难维护,堆的多了,就只能做一件事:大规模重构或扔掉重做。

笔者注:软件的复杂性就是这么一点点增加的。

共收到 6 条回复 时间 点赞

问题 5 引申出来一个遇到的坑,Java 后端使用 long 类型时,直接传递给前端,前端 js 处理会有精度丢失问题,反而需要把 long 转为 string 传给前端,才能保证精度不丢失

我们有维护统一的数据字典,统一的异常信息列表,对接口定义、数据类型、粒度、分类、编号统一管理,每种业务流程也会有相应接口流程对应的文档,感觉还好

Ouroboros 回复

羡慕了,应该是大公司吧,流程很规范

hug. 回复

这其实和公司大不大没啥关系。。。看愿不愿意在规范上花功夫~
这些东西其实也花不了多少成本,但是会避免很多坑

Ouroboros 回复

是的,本质还是团队规范的问题,或者说研发负责人的质量意识,决定了团队的质量意识。

我们公司更坑,啥校验都让前端做,后端接口基本没校验逻辑,不管你参数怎么传都能调通,还让我们搞接口自动化测试,搞毛啊

CKL的思考 接口自动化不是救命稻草 中提及了此贴 11月15日 18:57
CKL的思考 接口自动化不是救命稻草 中提及了此贴 11月15日 18:57
需要 登录 后方可回复, 如果你还没有账号请点击这里 注册