The ARDoCo Tool Landscape: REST API, TraceView, and TraceViz for Architecture Traceability

技术摘要：ARDOCO 工具集

问题背景
软件开发会产生跨越多个抽象层级的相互关联的制品：自然语言编写的软件架构文档（SAD）、形式化的软件架构模型（SAM）以及源代码。在这些制品之间维持一致性和可追溯性对于维护、变更影响分析和演进至关重要。然而，手动维护追踪链路既繁琐又易错。虽然自动化的追踪链路恢复（TLR）至关重要，但现有的 ARDoCo 方法（如 SWATTR、ArCoTL、TransArC、LiSSA）在历史上仅以 Java 库或命令行工具的形式存在。这种技术壁垒阻碍了那些缺乏配置和运行这些工具专业知识的架构师和开发者的采用，限制了最先进的 TLR 技术在实际中的部署。

方法论与工具图谱
为了弥合算法研究与实际应用之间的鸿沟，作者展示了一个公开部署的工具集，该工具集由三个互补的接口组成，旨在暴露 ARDoCo TLR 系列功能：

1. ARDOCO REST API： 一个基于 Spring Boot 的后端，通过 HTTP 端点提供对四种 TLR 流转过程的程序化访问。它支持异步执行和结果缓存（通过 Redis）以优化性能。暴露的流水线包括：

   • SAD-SAM： 利用 SWATTR（NLP 和启发式算法），并检测“文本实体缺失于模型”（TEAM）和“模型实体缺失于文本”（MEAT）的不一致性。
   • SAM-Code： 利用 ArCoTL（中间表示和文本相似度）。
   • SAD-Code (直接)： 利用 ArDoCode（直接将 SWATTR 启发式算法应用于代码，无需 SAM）。
   • 传递性 SAD-SAM-Code： 利用 TransArC（传递地组合 SWATTR 和 ArCoTL）。
     该 API 返回结构化 JSON，并包含一个用于探索的集成 Swagger UI。

2. TraceView： 一个基于 Next.js 和 React 构建的零安装、基于浏览器的前端，专为架构师和非开发者优化。它具有一个引导式向导，用于上传制品（SAD、SAM、代码）并配置 TLR 流转过程。其核心界面提供了一个多面板交互式视图，允许用户并排可视化查看 SAD、SAM 和源代码。选择一个元素会高亮显示其在所有面板中对应的关联项及检测到的不一致之处，从而促进跨制品的导航。

3. TraceViz： 一个针对开发者优化的 Visual Studio Code 扩展，专门用于 SAD-Code 的 TLR。它通过彩色侧边栏标记（gutter markers）将追踪链路直接叠加在 IDE 中。关键特性包括：

   • 导航： 通过快速选择菜单（Quick Pick）或 CodeLens，实现从文档句子到关联代码文件的单次点击跳转（反之亦然）。
   • 来源无关性： 支持来自 REST API（ArDoCode/TransArC）的链路、外部工具的 CSV 导入，以及 LiSSA（一种检索增强生成方法）的本地执行。
   • 视觉优化： 通过将每个文件的标记聚合为目录级圆点来减少噪声，并允许最多两个追踪链路集的并排比较。

核心贡献

• 易用性： 该工具集将复杂的、基于库的 TLR 算法转化为易于使用的工具，几乎无需本地安装，满足了不同用户角色（集成者、架构师和开发者）的需求。
• 统一后端： REST API 作为共享的计算引擎，确保了浏览器和 IDE 界面之间的一致性，同时支持第三方集成。
• IDE 内可视化： TraceViz 引入了一种在开发者编辑上下文中直接可视化追踪链路的新方法，超越了传统的外部报告。

结果与评估

• 算法性能： 底层的 TLR 算法在五个开源 Java 项目（MediaStore, TeaStore, TEAMMATES, BigBlueButton, JabRef）的基准测试中得到了评估。结果表明，SWATTR 在 SAD-SAM 上的 F1 分数为 0.81，ArCoTL 在 SAM-Code 上的 F1 分数为 0.98，TransArC 在 SAD-Code 上的 F1 分数为 0.82，显著优于 ArDoCode 基准（F1 = 0.37）。不一致性检测（MEAT）达到了 0.89 的 F1 分数。
• 用户研究 (TraceViz)： 一项涉及 7 名参与者（包括博士生、硕士毕业生和一名行业开发者）的初步放声思考法（think-aloud）研究评估了 TraceViz 的效用。参与者在有无可视化辅助的情况下对 TEAMMATES 项目进行了软件理解任务。
  • 七名参与者中的六名认为可视化有助于完成任务。
  • 所有七名参与者均同意它支持了他们的理解过程。
  • 定性反馈表明，如果没有可视化，用户会依赖重复的手动树遍历；而 TraceViz 则实现了向相关文件的直接跳转。
  • 三名参与者表达了在实际场景中使用该工具的意向，其他参与者则指出了其在入职培训和导航大型代码库方面的潜力。

意义
本文声称，该工具集使最先进的 TLR 技术能够被更广泛的受众（包括架构师、开发者和工具集成者）所使用，而此前这些受众因底层算法的技术复杂性而被排除在外。通过提供基于浏览器的探索工具（TraceView）和集成于 IDE 的可视化工具（TraceViz），作者证明了自动化追踪可以有效地投入实践。初步的用户研究表明，在 IDE 中直接可视化这些链路可以提高开发者在软件理解任务中的理解能力和效率。未来的工作旨在将基于大语言模型（LLM）的方法（如 LiSSA、ExArch）整合到该工具集中，并进行更大规模的受控研究。