一种基于文档和测试驱动开发的方法
技术领域
本发明属于研发效能和研发质量领域,特别是涉及一种基于文档和测试驱动开发的方法。
背景技术
最近几年API成为大家比较关注的话题,因为它切实解决了企业在数字化和研发效能改善等方面的一些问题,而且能够推动企业业务的增长。
现在,随着企业内部分工越来越细,以及分布式的技术架构、微服务的普及,API的数量和管理难度都随之大幅上升。资料显示,60%以上的团队,将半数时间花在了围绕API相关的工作上面,如果我们把API涉及到的团队都列出来,能看到API治理其实是一个流程长,且内容复杂的系统性问题。
当前业界普遍使用的方式为,优先编写代码,后续通过word、excel、pdf等格式记录接口文档,参数命名没有规划和沟通,研发过程中便会遇到各种问题、前端人员对接和测试人员进行接口调试都会增加难度,研发效率也会因此降低,企业内部资产管理越来越混乱,系统也会变的越来越复杂。
同时,由于繁杂系统中拥有大量的接口,这些接口缺少对应的文档或者文档版本过低,研发过程中需要花费时间更新或者补全之前的接口信息,从而导致研发人员研发迭代效率大大下降;更有甚接口在系统中运行,但是没有进行识别,进行大量重复的开发和研发工作,从而使系统变得更加冗余,接口量更多了。接口记录完成之后,接口的测试没有做好,导致接口的质量下降,亦同样会使整体研发效率下降,因此,文档完成之后的接口测试非常重要,亟需一种可以统一管理接口文档并且提升研发效率的方法,通过文档自动化生成测试案例并通过一键跑批测试案例方法来测试接口,来提升接口正确率。
发明内容
为了解决上述的问题,本发明设计开发一套满足自动生成接口文档、以接口文档为核心的开发方法,并将此方法作为后续开发过程中的最佳实践。
为实现上述目的,本发明提供了如下方案:一种基于文档和测试驱动开发的方法,包括:
通过IDEA插件扫描接口代码或者注解,生成接口文档;
配置nginx,生成指定nginx日志,根据eolink页面信息配置eo-resolver解析器;通过所述eo-resolver解析器生成API文档或者测试用例;
对接口进行解析,将所述接口文档内容录入到eolink上,获得目标接口文档;基于所述目标接口文档实现后续代码开发和前后端的测试开发对接。
优选地,通过IDEA插件扫描接口代码或者注解,生成接口文档的过程包括生成类注释和单独方法生成注释;
所述生成类注释和单独方法生成注释的过程包括,
基于http协议类型,分别在类上和方法上输入[//eo],然后键入“意图”组合键,菜单选择“Write Eolink doc”,通过所述IDEA插件生成Eolink注释,其他信息手动补充和修改。
优选地,所述生成类注释和单独方法生成注释之后还包括生成方法注释和生成属性注释;
所述生成方法注释和生成属性注释的过程包括,
基于当前java文件右键唤出菜单,点击“Generate Class Doc”,获得二级菜单;基于所述二级菜单选择需要生成的注释类型(http/rpc),通过所述IDEA插件对当前java文件的方法生成Eolink注释和对当前java文件的属性生成Eolink注释,其他信息手动补充和修改。
优选地,通过所述IDEA插件对当前java文件的方法生成Eolink注释的过程还包括,若方法已存在包含@eo.name的注释则不会再生成;若类已存在包含@eo.groupName的注释则不会再生成;
通过所述IDEA插件对当前java文件的属性生成Eolink注释的过程还包括,若属性已有注释则不再生成。
优选地,所述生成方法注释和生成属性注释之后还包括上传全部接口和部分接口上传;
所述上传全部接口过程包括,
基于生成的Eolink注释并确认无误后,对当前java文件右键唤出菜单,点击“Upload All Api”,通过所述IDEA插件自动解析方法且全部提交到目标服务器上,实现全部接口上传;
所述部分接口上传的过程包括,
基于当前java文件右键唤出菜单,点击“Upload All Api”,通过所述IDEA插件自动解析方法,唤出接口选择窗口,基于所述接口选择窗口查看接口信息是否正确,再点击上传实现部分接口上传。
优选地,所述上传全部接口和部分接口上传之后还包括项目级上传;
所述项目级上传的过程包括,
确保项目能够正常编译和启动,通过点击顶部菜单 [Tools -> Upload ProjectApi Doc]扫描所述项目下所有的api接口,基于各项注释和注解进行识别,将识别出来的api上传至配置的空间-项目中,自动生成“http默认分组”和“rpc默认分组”分别存放识别出来的http接口和rpc接口。
优选地,所述项目级上传的过程还包括,
若项目内使用了包含@eo.groupName的Eolink Doc来标记分组,对应的api传到所标记的分组中。
优选地,配置nginx,生成指定nginx日志,根据eolink页面信息配置eo-resolver解析器;通过所述eo-resolver解析器生成API文档或者测试用例的过程包括,
为nginx添加插件/编译,修改nginx日志打印格式,重启nginx运行获得nginxaccess_json.log,基于所述eo-resolver解析器配置nginx的log地址、配置项目名称和分组,运行eo--resolver项目,到apikit空间内对结果进行验收,生成API文档或者测试用例,并对所述API文档或者测试用例设置上传。
本发明公开了以下技术效果:
本发明提供的一种基于文档和测试驱动开发的方法,通过IDEA插件扫描接口代码或者注解,生成接口文档;配置nginx,生成指定nginx日志,根据eolink页面信息配置eo-resolver解析器最后通过eo-resolver解析器生成API文档或者测试用例;对接口进行解析,接口文档内容录入到eolink上;后续代码开发可以将文档作为依据,前后端对接可以通过文档进行预对接,测试可以通过文档快速编写测试案例,提升整体开发效率,降本增效。
本发明通过扫描代码注解、代码或者通过nginx日志生成接口文档,实现仅通过页面配置便可以实现生成接口文档,大大节省了前端后端及测试的对接、沟通和开发时间,降低了企业内部的管理成本,提高了整体研发效率。
附图说明
为了更清楚地说明本发明实施例或现有技术中的技术方案,下面将对实施例中所需要使用的附图作简单地介绍,显而易见地,下面描述中的附图仅仅是本发明的一些实施例,对于本领域普通技术人员来讲,在不付出创造性劳动的前提下,还可以根据这些附图获得其他的附图。
图1为本发明实施例的eo-resolver解析器工作流程示意图;
图2为本发明实施例的文档协作流程的流程示意图。
实施方式
下面将结合本发明实施例中的附图,对本发明实施例中的技术方案进行清楚、完整地描述,显然,所描述的实施例仅仅是本发明一部分实施例,而不是全部的实施例。基于本发明中的实施例,本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他实施例,都属于本发明保护的范围。
为使本发明的上述目的、特征和优点能够更加明显易懂,下面结合附图和具体实施方式对本发明作进一步详细的说明。
如图1所示,本发明提供了一种基于文档和测试驱动开发的方法,包括:
通过IDEA插件扫描接口代码或者注解,生成接口文档;
配置nginx,生成指定nginx日志,根据eolink页面信息配置eo-resolver解析器最后通过eo-resolver解析器生成API文档或者测试用例;
对接口进行解析,接口文档内容录入到eolink上;
后续代码开发可以将文档作为依据,前后端对接可以通过文档进行预对接,测试可以通过文档快速编写测试案例,提升整体开发效率,降本增效。
进一步地优化方案,IDEA插件生成接口文档包括:
生成类注释;
在类上输入[//eo],然后键入“意图”组合键(默认是Alt+Enter),菜单选择“WriteEolink doc”,插件自动生成Eolink注释,其他信息请手动补充和修改,此功能目前仅支持http协议类型。
单独方法生成注释;
在方法上输入[//eo],然后键入“意图”组合键(默认是Alt+Enter),菜单选择“Write Eolink doc”,插件自动生成Eolink注释,其他信息请手动补充和修改,此功能目前仅支持http协议类型。
一键生成方法注释;
当前java文件右键唤出菜单,点击“Generate Class Doc”出现二级菜单,选择需要生成的注释类型(http/rpc),插件自动给当前java文件的方法生成Eolink注释,其他信息请手动补充和修改。
其中,私有方法和构造方法将被忽略,如使用的lombok,lombok生成的方法也会忽略因为明文上方法不存在,同时,若方法已存在包含@eo.name的注释则不会再生成;若类已存在包含@eo.groupName的注释则不会再生成。
一键生成属性注释;
当前java文件右键唤出菜单,点击“Generate Field Doc”,插件自动给当前java文件的属性生成Eolink注释,其他信息请手动补充和修改,若属性已有注释则不再生成。
一键上传全部接口;
当前java文件右键唤出菜单,点击“Upload All Api”,插件自动解析方法且全部提交到目标服务器上。由于此功能没有预览窗口,使用此功能前应先生成Eolink注释并确认是否无误
部分接口上传;
当前java文件右键唤出菜单,点击“Upload Api”,插件会自动解析方法,唤出接口选择窗口,在此窗口查看接口信息是否正确,再点击上传。
项目级上传;
确保项目能够正常编译和启动时使用此功能,否则可能因为倚赖缺失等问题中断识别。通过点击顶部菜单 [Tools -> Upload Project Api Doc]扫描该项目下所有的api接口,并基于注释和注解进行识别,最终把识别出来的api上传到所配置的空间-项目中,自动生成一个“http默认分组”和“rpc默认分组”分别存放识别出来的http接口和rpc接口。
若项目内使用了Eolink Doc(@eo.groupName)来标记分组,对应的api将会传到所标记的分组中。
由于是项目级识别和上传,识别过程中可能会有“窗口冻结”的情况,识别完后会进行任务上传,不影响其他使用。
Nginx服务生成接口文档包括:
1.配置nginx,生成指定nginx日志;
2.根据eolink页面信息配置eo-resolver解析器;
3.通过eo-resolver解析器生成API文档或者测试用例;
4.生成的用例在eolink页面直接进行测试;
eo-resolver解析器的配置文件作用包括:
1.配置nginx的log地址,生成api测试用例和api文档;
2.灵活配置项目名称和分组;
3.设置上传api文档或者api测试用例。
如图2所示,由于协作流程基础都是文档,因此提出通过文档和测试来驱动开发,协助各方人员进行合作连调,增加对接效率,减少协同过程中遇到的各种问题。其中,
Eolink:接口管理及自动化测试平台,可以完整规范的管理接口文档,并且提供文档对接依据。
eo-resolver:通过抓取日志信息获取接口请求内容、返回内容并借此生成接口文档及测试用例。
Nginx:1、服务器也称伺服器是提供计算服务的设备。由于服务器需要响应服务请求,并进行处理,因此一般来说服务器应具备承担服务并且保障服务的能力。通常分为文件服务器,能使用户在其它计算机访问文件、数据库服务器、应用程序服务器、WEB服务器等。
2、负载均衡建立在网络结构之上,通过分摊到多个操作单元上进行执行,从而提供了一种廉价有效透明的方法扩展网络设备和服务器的带宽、增加吞吐量、加强网络数据处理能力、提高网络的灵活性和可用性。
3、常见的服务器架构有三种服务器集群架构,服务器负载均衡架构,分布式服务器架构,主要用于电子商务类型的网站;分布式服务器主要是解决跨区域,多个单个节点达到高速访问的目前,类似CDN的用途的话,会采用分布式服务器。
DTDD:通过文档和测试来驱动开发方法。
以上所述的实施例仅是对本发明的优选方式进行描述,并非对本发明的范围进行限定,在不脱离本发明设计精神的前提下,本领域普通技术人员对本发明的技术方案做出的各种变形和改进,均应落入本发明权利要求书确定的保护范围内。