企业官网建设流程全解析

把依赖图发布成项目文档：Rubrowser自包含HTML输出接入CI构建指南

【免费下载链接】rubrowsera ruby code dependency graph interactive visualizer项目地址: https://gitcode.com/gh_mirrors/ru/rubrowser

Rubrowser 是一款 Ruby 代码依赖图可视化工具，能把项目中的类、模块及其依赖关系渲染成一张交互式依赖图，并输出为单个自包含 HTML 文件（数据、脚本、页面全部打包在一起）。本文介绍如何把 Rubrowser 的自包含 HTML 输出接入 CI 构建，让依赖图随每次构建自动生成、自动发布为项目文档——团队成员只需打开一个 HTML 文件，就能看懂整个代码结构。

为什么自包含 HTML 适合发布成文档 📊

Rubrowser 从 2.0.0 版本起不再运行 HTTP 服务器，而是直接生成一个自包含的 HTML 文件。官方说明见 readme.md 中的 Note 一节，也即：数据、脚本、HTML 都在一个文件里，可以在 CI 构建中生成并发布为项目文档。

这种方式对"文档化"非常友好：

• ✅零依赖：不需要启动服务，双击就能在浏览器打开
• ✅可归档：产物可以提交到仓库、随静态站点（如项目 Pages）直接托管
• ✅可离线：断网环境、内部文档服务器均可正常展示
• ✅可交互：拖拽固定节点、缩放平移、点击高亮所有依赖与被依赖关系

从实现上看，渲染入口在lib/rubrowser/renderer.rb：它用lib/rubrowser/data.rb解析出的类/模块定义与关系数据，套用views/index.erb模板，把前端逻辑（public/javascript/application.js）一并内联，最终写出单个 HTML 文件。想深入了解解析逻辑，可以从spec/parser/下的测试夹具（如class_with_one_class_dependency.rb）入手。

💡 想看完整源码？可以克隆仓库浏览实现：git clone https://gitcode.com/gh_mirrors/ru/rubrowser

快速上手：3 步在本地生成依赖图

第 1 步：安装 Rubrowser

gem install rubrowser

第 2 步：执行分析并输出 HTML

rubrowser -o docs/dependency-graph.html

不加参数时默认分析当前目录；-o指定输出文件。

第 3 步：打开查看

用浏览器打开生成的文件即可。节点圆圈大小与该类/模块的代码行数成正比，红色标记表示存在循环依赖。

接入 CI 构建：让依赖图随构建自动更新 ⚙️

把依赖图放进 CI 后，每次合并代码都会刷新文档，无需任何人手动执行命令。分三步：

1. 将 Rubrowser 加入开发依赖

在Gemfile的 development 分组中加入：

gem 'rubrowser'

2. 添加一个构建任务

在你的 CI 配置中新增一个任务，执行 Rubrowser 并把产物声明为 artifacts（或部署到静态站点）：

build-graph: script: - bundle exec rubrowser -o docs/dependency-graph.html artifacts: paths: - docs/dependency-graph.html

3. 发布产物

• 简单场景：把docs/dependency-graph.html直接提交或归档，附在发布说明中
• 进阶场景：把docs/目录部署为静态站点，团队成员固定链接随时查阅

这样"依赖图 → 项目文档"的链路就闭环了：代码变更 → CI 自动重建依赖图 → 文档同步更新。

固定布局：用 .rubrowser 让每次构建的图保持一致 📌

自包含 HTML 每次生成的节点位置是随机的，文档里的图每构建一次就"抖"一次，阅读体验不好。Rubrowser 提供了布局文件机制：

1. 在浏览器里手动拖拽节点，把布局调整到满意的位置
2. 点击页面上的按钮，把当前布局下载为 JSON（节点固定坐标）
3. 将该文件保存到项目中，官方推荐命名为.rubrowser
4. 生成时通过-l参数嵌入布局：

rubrowser -l .rubrowser -o docs/dependency-graph.html

把这个.rubrowser提交到仓库后，CI 每次构建都会得到布局稳定的依赖图，文档截图与链接位置都不会漂移。

常用参数速查表

导出 JSON：对接其他文档工具 🔌

除了 HTML，Rubrowser 还能把解析结果导出为结构化数据（实现见lib/rubrowser/formatter/json.rb）：

rubrowser -j | jq '.'

你可以用它做二次加工，例如统计模块数量、生成依赖清单文档，或喂给其他可视化工具。

了解局限：静态分析的边界 🧭

接入 CI 前，建议把以下 4 点预期同步给团队（均见readme.md）：

• 语法错误的文件会被跳过，仅打印警告，不会中断构建
• 项目外引用的类不会出现在图中，只展示你定义的类/模块
• 纯静态分析，元编程（包括 Rails 的 associations）不在覆盖范围
• 循环依赖通过强连通分量算法检出并以红色标记（逻辑在lib/rubrowser/data.rb的mark_circular_dependencies）

进阶：把执行追踪也叠加到文档图上 🚀

如果希望依赖图不仅能"看结构"，还能"看运行时"，可以启用监控模式：在应用启动前（Rails 项目可放在 initializer）运行：

Rubrowser::Monitor.run(path: Rails.root.to_s, port: 8080)

然后生成连接监控端的图：

rubrowser -s localhost:8080 > output.html

运行代码时，图上对应节点会实时高亮，实现来自lib/rubrowser/monitor.rb与lib/rubrowser/server.rb。这一模式更适合本地调试；CI 场景用前面介绍的静态 HTML 输出即可。

小结

• Rubrowser 2.0+ 输出的是自包含 HTML，天然适合作为项目文档发布
• 接入 CI 只需两行：gem 'rubrowser'+ 一个执行rubrowser -o docs/...的构建任务
• 提交.rubrowser布局文件，让每次构建的依赖图布局保持稳定
• 静态分析有边界，对元编程重度依赖的项目请合理预期

把依赖图变成"每次构建自动更新的活文档"，新成员接手项目时的上手成本会显著降低。

【免费下载链接】rubrowsera ruby code dependency graph interactive visualizer项目地址: https://gitcode.com/gh_mirrors/ru/rubrowser