如何改善接口文档-前后端的“桥梁”?

chace0120 发布于 2015/04/03 00:25
阅读 1K+
收藏 0

工作模式
公司目前采用前后端分离的模式进行项目开发。本人处于后端组的Java开发职位。
前后端的沟通桥梁
前后端分离开发项目,前端组主要负责页面的设计与交互,后端组主要负责数据的存储与服务。前后端组工作协作靠接口文档。目前本人公司的接口文档由前端工程师主要填写,后端人员进行后期的调整。
发现的问题
在前后端两个小组协作开发项目的过程中,逐渐了发现了些许协作问题,以本人目前的眼界,认为最为突出的问题会发生在接口文档上。
结论缘由
为什么本人会认为最大的问题出现在接口文档,并在此请教改善之法呢?有以下几点原因。

1.前后端人员的思维差异
接口文档,表明了前端请求后端数据时的格式。本人公司采用json的数据格式进行数据交互,后端采用Java开发,自然是将model中的数据转为json格式“跪送”给前端。但由于每个人的思维不用,对接口中的字段命名习惯等也大不相同。例如后端User类中有name和age两个属性,但前端人员写接口文档时偏偏是{“username”:“xxx”, “sex”:“xxx”}。为了应对这种情况,最开始开发项目时,后端再返回数据之前采用Map的方式将model中的数据进行重组和封装,达到前端要求的接口内容。但Java代码就泛滥出大量的put操作,甚是繁琐。个人认为这种情况可以在开发前期两组就要办法做统一规范。
2.前端人员填写 接口的“随意性”
为了避免Map方式所带来的繁琐操作和put代码泛滥,随后的项目开发中,引入了DTO类,并借助Dozer工具进行实体类DTO类之间的映射转换。DTO类中的属性名符合前端人员在接口文档中所写的字段名称。例如为了传输User类的数据,对应的有UserDTO类,有username和sex属性。同时DTO也可以应对传输实体类部分属性的情况。OK,这种模式进行了一段时间后发现,由于前端人员写接口太过随意,导致后端会产生大量碎片化的DTO类。举个详细的例子:
public class Course { //课程实体类
    private Long id;
    private String number;
    private String name;
    private Teacher teacher; //课程教师
}


前端通过接口请求课程相关的数据时,可能是{"number":"xxx","name":"xxxxx"},可能是{"id":xxx,"name":"xxxx"},亦或是{"id":xx,"name":"xxx","teacherName":"xxx"}。这种“随意性”导致后端要么创建应对各式各样情况的DTO类,要么就是在实体类和DTO类中追加冗余的、没有意义的属性。例如又可能为了显示,需要在Course类添加一个studentScore的属性。

当然“随意性”我用了引号,表示这只是我个人的观点,并不能说明前端人员有错,人家在写文档时自然更偏向于自己认为舒服的结构,这很正常,本人表示充分理解。

3. 过于过程化的接口结构
第三点是我近期所察觉到的最可怕的一点。诸如上述问题的存在,当遇到复杂的项目时,文档结构就会失控。假如前端人员对后端的技术并不清楚的话,以及他们更偏向于过程化的编码思维,直接导致接口结构呈现过程化的趋势,可悲的是由于交互功能的复杂度,后端为了实现前端期望的接口结构,在编码时已然潜移默化地在进行面向过程的开发,而不是面向对象,个人认为这是灾难的征兆。说到这儿,我依旧不认为前端在写接口有错或是有问题,这是人家的正常思维习惯。
以上是本人在自己工作经历中所感悟的痛楚,在此请教各路有经验人士的改善观点。


加载中
1
Brin想写程序
Brin想写程序

后端别变,前端做适配。。

因为前端js灵活,成本低。。

后端java这种每次修改都要重新部署,从整体成本考虑,应该是前端用js做接口层。

所以接口文档应该前端提需求,也就是纸质的报告,后端来写正式的接口。。前端再修改,也就是不能删除字段,但是可以修改字段名和新加字段,你们公司流程错了。

而且你们公司没有架构师??

这个活应该是架构师干的。。

Brin想写程序
Brin想写程序
回复 @Angerbaby : 在真正做业务的公司里面,一次服务器重启,或者重新部署导致的用户流失,是有真正的经济损失的。。你可以这么跟你领导解释。。
chace0120
chace0120
会参考您的建议与领导商讨,谢谢您的回答。
1
混世顽童
混世顽童
前后端一起坐下来讨论接口实现,由后端完成真正的java接口,交给前端补充,再协商统一
chace0120
chace0120
恩,这个是必要的人为因素,我觉着以后也需要花必要的时间在前后端协商上。不然这种前后端分离不会提高开发效率,只会互相拖累。
0
聽雨人
聽雨人
想来想去字段命名还是个问题哈
chace0120
chace0120
人的思考方式不同,相当是问题。自己认为叫name挺爽,人家觉着叫username挺爽,就这之类的问题吧。
0
Brin想写程序
Brin想写程序

而且MVC里面,发送给前端的应该是View层的内容,而不是直接发送Model过去,所以之前用DTO的方法是正确的。

不过你们后端用dozer,倒不如前端也找个类似于dozer的东西吧。。

chace0120
chace0120
回复 @Brin想写程序 :这个。。。公司小,没有专门的且经验丰富的架构师,一定程度上来说自己就是自己的“架构师”。所以,这需要我自己去不断地摸索总结。
Brin想写程序
Brin想写程序
回复 @Angerbaby : 你会遇到这个问题,只能说明你上面的架构师不合格。。。
chace0120
chace0120
回复 @Brin想写程序 : 明白您的意思,我觉着我可以更坚定地去明确些东西了。
Brin想写程序
Brin想写程序
回复 @Angerbaby : 因为我玩全栈的,所以用js出发,从一个对象里面去一两个字段,跟一个对象就一两个字段,前端的影响为0.
Brin想写程序
Brin想写程序
回复 @Angerbaby : 关键是从业务出发,暴漏了有什么后果?我觉得后端给的应该始终比前端要的多。。我觉得只要不是用户名密码,和权限信息,暴漏就暴漏了。。
下一页
0
yak
yak
做一个配置文件来处理字段映射就没问题了
chace0120
chace0120
目前项目里使用的是,Entity <- Dozer ->DTO,Dozer有配置文件可以解决Entity对DTO字段名不同的情况。
0
求是科技
求是科技
楼主的问题解决了没?我目前就处于公司写接口,ssm框架,专职接口,也遇到楼主的问题。还有,后端还应该具备哪些知识点呢?目前的框架基本上一整合就固定了,接着定好接口,就开始写接口了(说实话,主要是根据业务写SQL)。
0
大神哔哔

楼主可以尝试使用API接口管理平台管理接口,方便协作工作,而且还提供项目管理,权限管理,接口管理,接口测试,高级mock,接口版本管理功能。真的可以极大提高开发效率。可以试试eolinker旗下的ams,目前国内很多产品我都试用过,api管理工具推荐eolinker,https://www.eolinker.com国外的推荐swagger,这款软件是目前国外最好的

0
mon
mon

前后端一起商量约定出来,然后部署倒到内部api服务器上

返回顶部
顶部