¤ 拓展阅读 ¤
淘宝App搜索业务侧采用的是局部动态化的跨端技术架构,客户端提供丰富的基础能力与视图组件的API,前端负责业务视图搭建与业务逻辑实现。
视图组件相关:组件定义、组件属性、组件方法
在代码编写完后,端侧同学会按照自己的话术将注释内容进行丰富后(让前端同学能够理解的内容)维护到语雀文档中。
既然跨端能力代码可以有模板规范,那么也可以约定注释信息的填写模板,将注释内容信息规范化。
基于规范化的注释内容,可以通过脚本工具或者编译插件工具,在代码编译时按照既定的规则将这些信息进行采集。采集到信息之后,通过服务上报的方式将数据持久化在远端数据库,方便后续的二次加工和使用。
基于采集到的API信息,可以生成API介绍的网页来替代语雀文档展示的方式。
同时还可以更进一步,按照前端语言规范,将这些信息生成前端代码库的JS描述文件,实现了在前端IDE中编写代码时的端侧 Api 提示和代码补全能力,同时描述文件也可以使用npm进行版本管理。
基于以上思路分析,整体的方案链路大致如下:
模块拆解
综合考虑开发成本并结合Android端侧的编译环境,选择自定义Java注解和注解处理器的方式来作为信息生成的方案。
既然是基于注解的自动化采集方式,我们除了需要将端侧复杂的API按照作用进行分类外,还需要对不同类目的API设计适配性的内容填写规范,使API信息尽可能的有效且丰富。
在实际操作过程中我们发现,为了尽可能完整的描述方法或者组件的能力和调用方式,有些比较复杂的方法需要填写的信息内容比较多,例:
采集规则不用特殊设计,代码编译时按照注解的定义规则,将对应注解里面的字段按照定义拆解出key-value即可。
按照方案设计中的构想,我们需要将采集到的API信息进行上报,为了方便数据上报,我们将信息组装成json文件。
文件生成
目标文件
为了支持前端IDE的代码提示,还需要按照前端的API描述文件编写规范生成对应的描述文件。
前端API描述文件规范
文件生成
目前端侧的打包发布平台支持丰富的自定义配置,在打包流水线中添加自定义脚本执行节点,在自定义脚本文件中完成API信息数据的上报和前端描述文件的发布。
进展
目前前端代码提示插件已能正常使用,相比之前盲写代码还是舒服了不少。IDE中使用效果如下:
通过持久化的API数据,自动生成相关API的说明站点,包含API的功能描述与调用方式。
目前注解信息填写依靠CR规范限制开发者填写,后续考虑通过使用编译插件进行检测,对没有填写相关信息的API进行编译中断,强制开发者进行填写。
以上就是淘宝App搜索业务在跨端架构下客户端侧API维护的一种思路实现方式,整体方案比较常规,也是希望通过将一些常用的工具进行组合,尽可能的提高跨端协同的效率与开发幸福感。
¤ 拓展阅读 ¤