低代码之函数库说明文档的自动化生成原理

背景

七巧低代码开发平台提供低代码脚本能力，作用域于运行端（PC端+移动端），以Java、JavaScript作为语言基础，让具备编程能力的用户可使用七巧低代码开发引擎编写简易的脚本，实现复杂的业务。

使用场景举例：

在CRM场景中，存在客户与跟进记录表，在客户列表中添加一个【添加跟进】按钮，然后绑定跟进记录表单，希望添加的跟进记录自动关联到客户信息。

低代码脚本函数库及相关物料管理：

为了跟上业务的迅速扩张，提高研发人员的开发效率，我们不断丰富低代码脚本函数库。不过，随着研发实践的不断演进，现有的系统功能已不足以应对最新的需求，我们面临着低代码函数库管理的新挑战，这些挑战主要体现在：

1.函数库的更新过程过分依靠手工操作，需要开发人员和运营人员共同配合，存在文档信息变动时容易漏掉关键通知的问题。这可能会影响到后续工作的测试或是与相关方的对接。

2.在研发迭代的过程中，低代码脚本函数库与之结合的紧密程度不够，存在研发迭代跟踪遗漏的问题。

3.低代码脚本函数库文档的维护和代码的关联性不强，导致很多代码没有同步更新脚本说明，随着时间积累，容易产生不一致的问题，给后续的维护工作带来了极大的困难。

思路和方案

为打造高效的低代码脚本文档管理平台，我们的主要目标是确保文档的正确性，并减少开发团队维护文档的工作量。要实现这些目标，我们需要着手解决以下几个核心问题：

1.文档与代码分离带来的维护问题：

参考Javadoc注释机制，通过自定义注解的方式，对函数库、函数方法、参数提取公共标准，结合AST与FreeMarker等技术栈，实现代码即文档，降低维护成本。

2.保证脚本函数库完整的变更信息被有效识别的问题：

通过比对不同迭代间低代码脚本函数库元数据的差异，提取函数库、函数方法、参数的变更内容，生成完整的物料信息。

3.根据迭代发布计划，及时同步脚本函数库以及相关物料更新的问题：

优化迭代发版规范，将函数库以及物料更新纳入常规操作中，保证生产环境的低代码脚本函数库及相关物料与发版迭代代码的一致。

平台架构图

业务流程

数据模型关系管理

数据模型管理在是本方案中一个非常重要的支撑。如果模型无法有效管理，就无法实现高效准确的API文档更新。

最终模型关系管理如图所示：

数据模型关系包含：

函数库：函数描述、函数说明
函数方法：方法描述、方法说明、方法返回值、方法示例
参数：参数描述、参数说明、参数备注

总结

将低代码脚本函数文档管理集中于代码内部，对整个研发管理流程带来了很多好处。首先，开发人员只须根据规范要求完成函数说明，在代码提交后，文档便能同步自动更新，大幅简化了文档的持续维护工作。其次，该机制让文档的更新管理得到了保障，在每次迭代发版的过程中，只需要同时发布文档内容，即能保证低代码函数库内容与代码相匹配。最为关键的是，通过在代码层面维护低代码函数说明，确保了低代码函数库内容与实际代码一致。

作者介绍：
道一云，成立于2004年，是中国低代码领域的领导厂商、腾讯战略投资企业、腾讯生态核心合作伙伴。拥有自主知识产权管理软件产品百余项，涵盖数字化应用构建低代码平台-七巧、全场景智能业务分析BI-七析、千人千面、数智化办公企业级门户-七星以及30多款开箱即用的场景应用。

欢迎关注：
公众号：道一云低代码（do1info）
官网：道一云七巧 - 可视化、智能化、数字化应用构建
免费体验：道一云产品免费试用