你是这么写接口的么

相信很多开发经理，尤其是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

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

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

共勉。

往期推荐：

测试团队的一次复盘实践

接口测试断言

你写的接口脚本合理么

事务一致性测试

研发效能度量指标的陷阱思考