企业官网建设流程全解析

接手旧项目被调用链逼疯之后，codegraph是怎么把我捞出来的

大概两年前，我接手了一个线上跑了好几年的服务模块，代码量二十万行出头，文档只有一份六年前的部署说明。前端人换了几轮，后端注释加起来不超过一百条。那段时间我每天干得最多的事，就是用编辑器从入口类一层层跳转，试图把调用链在脑子里拼出来。拼到第三天，我决定换个思路，去找能把代码结构直接画成图的工具。试过好几个之后，我留用了现在几乎每天都在用的 codegraph——一个通过静态分析把工程里的模块、类、函数、调用关系抽出来，再用 graphify 渲染成一整套可视化图谱的开源工具。这篇东西不是官方文档的搬运，是我自己从安装到真实项目落地的完整记录，里面有不少官网没写清楚的细节。

如果你也在维护一份历史包袱很重、或者体量大到没法靠人肉读代码的工程，那这篇文章大概能帮你省下几个通宵。下面直接从"codegraph 到底解决了什么问题"讲起，再逐步拆到安装、使用、踩坑和日常化。

1. 把 codegraph 当什么用，以及它读代码的底层逻辑

1.1 它和 Sourcegraph 这类"代码搜索工具"的本质区别

很多人第一次听到 codegraph，会下意识联想到 Sourcegraph，因为名字太像了。但两者的使用场景完全是两回事。Sourcegraph 解决的是"我要找的定义在哪个文件、这个函数还有谁在调用"这种检索问题，它的核心是索引和搜索，回答一个又一个孤立的问题。而 codegraph 解决的是"整个工程的结构长什么样、模块之间的依赖边界在哪、入口到底调了多少层才碰到数据库"这种系统性问题，它的核心是建模和拓扑关系。

我自己的体会是：搜索工具适合有明确目标时的定点查询，codegraph 适合目标模糊时的全局侦察。刚接手旧代码时，你根本不知道该搜什么，这时候把所有 Controller 到 Service 到 Mapper 的关系画出来，远比一个个方法跳转更高效。它做的不是搜索引擎，而是把代码库变成一张可以缩放平移的地图。

1.2 codegraph 是怎么"读"代码的：解析、索引、建模三层结构

要理解 codegraph 的输出，最好先理解它的处理链路。整体上分三层：

• 解析层：按语言选择对应的解析器，比如 Java 走语法树解析，Python 走字节码与 AST 混合解析，把源码转成带符号信息的中间表示。
• 索引层：把中间表示里的符号、引用、文件路径全部索引起来，这一步决定了后续查询的速度。
• 建模层：根据索引结果计算调用关系、继承关系、包含关系和依赖关系，最终生成一个带类型标记的图结构。

graphify 就是建模层的输出端，它负责把你选定的子图渲染成最终的可视化文件。我最初以为 graphify 只是"画图"，后来才发现它对图谱的可读性影响巨大，比如是否保留跨层跳转、如何折叠工具类、同层节点怎么排序，这些都会直接改变你从图里能读出的信息量。

1.3 同类工具对比：为什么最后留下的是它

市面上同类工具不少，我稍微列一下我实际用过的：

我最后留下 codegraph 的原因很实际：它同时插了 Java、Python、Go、TypeScript 几套解析器，能在一个命令下把微服务仓库里多个语言模块统一建模，这一点在混合技术栈项目里非常加分。

2. 安装和环境依赖：想清楚这两件事再动手

2.1 语言支持范围与解析器要求

codegraph 不是一个"装完就能解析所有语言"的万能工具，它每支持一种语言，就依赖对应的解析器。以我用的版本为例，默认支持 Java、Python、Go、JavaScript/TypeScript、C/C++ 的一部分。装之前先确认两件事：

• 你项目的主力语言在不在支持列表里，半支持的语言在宏定义、模板代码、反射调用上会有漏检。
• 解析器版本和代码特性是否匹配，比如项目里用到了很新的语法特性而解析器版本太老，会出现大量"无法解析的符号"，图上会少很多边。

我建议第一次安装后，先拿项目里一个很小的模块做扫描，把生成结果和实际代码对照一下，确认解析器工作正常，再动手扫全量仓库。

2.2 三种安装方式实测

我在 macOS、Linux 和 Windows 环境都装过，三种方式有各自的小坑。

macOS 上我推荐直接走 Homebrew，一条命令就装完了，依赖的树形解析库也会自动带上。最需要注意的不是装，而是 PATH 环境变量，如果你同时装了多版本 JDK，codegraph 在解析 Java 工程时会去找javac，路径错了会直接报一堆找不到符号的错误。

Linux 上我用的是官方 Release 里的二进制包。切记不要把下载下来的压缩包放在项目目录里解压就直接跑，我这么干过一次，扫描结果里把 Release 包里的自带测试用例也当成项目代码了，图谱上多出一大堆诡异的孤立节点。正确做法是解压到固定的/opt或~/tools目录，再手动建一个软链接到~/bin。

Windows 上麻烦一些。codegraph 的主程序是跨平台的，但解析器的动态库和权限设置经常出问题。我的建议是：不要在 Windows 上扫大型代码库，除非你愿意折腾 Visual Studio 运行库和防火墙放行规则。实际情况中，Windows 机器更适合做 graphify 调参和看 SVG 结果，扫描建模放到 WSL 或远程 Linux 环境里做，我在项目里的分工就是这么定的。

2.3 第一次扫描前的全局配置

装完先别急着扫大项目，codegraph 有一个本地配置文件，通常在~/.codegraph/config.toml，第一次运行时会自动生成。我建议你至少关心这几个配置项：

• exclude_paths：把build、target、dist、node_modules这些目录排掉，否则扫描时间直接翻好几倍，图上还会充满无意义的依赖边。
• max_file_size：默认可能对超大文件不设限，但某些代码生成器输出的上千行 JS 会严重拖慢建模速度，建议按实际项目设一个阈值。
• parallelism：这个很有用，扫描大仓库时我一般调到 CPU 核心数的 70%，避免建模阶段内存直接冲高。

这些配置看起来不起眼，但它决定了你第一次跑的体验。我第一次就是没配 exclusions，直接扫一个前端工程，图还没生成，内存先爆了。

3. graphify 不是画图那么简单，它决定了图谱能不能被人看懂

3.1 graphify 的核心参数：scope、depth、edge-type

扫码建模之后的产物是一个全量的大图，直接打开会让你的浏览器卡死，所以真正日常用的是 graphify 的子图渲染能力。三个参数是我最依赖的：

• --scope：指定只看某个包、模块或类，比如--scope com.example.order.web，图就只剩下这个包相关的节点和邻接边。
• --depth：控制从 scope 出发往外延伸几层。我一般是先--depth 1看直接邻居，再放大到--depth 3看跨模块传播路径。
• --edge-type：选择要渲染的关系类型，常见有call、extends、imports、contains。默认会全部画出来，但混在一起很难读，我通常在排查循环依赖时只看imports，在梳理业务调用链时只看call。

组合起来一个很常用的命令长这样：

codegraph graphify \ --scope com.example.order.service \ --depth 2 \ --edge-type call \ --format svg \ --output order-service-callgraph.svg

这个命令输出的是订单服务模块两层内的调用关系图，既不会大到打不开，又足够看清 Service 层往外扩散的范围。

3.2 输出格式怎么选：SVG、PNG、GraphML、JSON

graphify 支持好几种输出，我的选择逻辑是这样的：

• SVG：日常首选。文本可以选中复制，放大不糊，直接嵌入 Confluence 或者 MkDocs 都方便。
• PNG：适合发到 IM 群里快速沟通，不需要别人打开点击查看，但细节一多就糊，只适合小型局部图。
• GraphML：这个格式看着像给机器用的，但实际是排查问题的大杀器。把图导出成 GraphML 后，我可以在 Gephi 这类图分析软件里做网络分析，比如算个中间中心性，看看哪些类处在调用链的咽喉位置。
• JSON：适合下游脚本消费。我做过一个依赖变更检查脚本，就是靠 graphify 的 JSON 输出和 Git 变更文件列表做交集，这个后面详细说。

所以不要觉得 graphify 只有画图这一个用途，它的输出本质是关系数据，画图只是默认的消费方式。

3.3 用过滤和着色让十万节点图瘦身

大型微服务仓库的全量图动辄几万个节点，直接渲染谁都会疯。graphify 有一套过滤逻辑，官网文档写得比较分散，我总结一下自己的用法：

• 按节点类型过滤：只显示class或function级别的节点，把package级别的聚合节点隐掉，图会清爽很多。
• 按依赖强度过滤：剔除那些被引用了上百次的工具类节点，比如各种StringUtils、DateUtils，这些工具节点会像蜘蛛网一样把图搅乱，但对理解业务架构毫无帮助。
• 依赖图聚焦：把生成骨架图时自动加入的规则引擎、代理类处理成可折叠组，这样既保留了真实关系，又不会刷屏。

另外，graphify 支持基于入度出度对节点着色。我一般设置出度大于 20 的节点标成红色，这些往往是扇出极高的"上帝类"，入度大于 30 的节点标成蓝色，这些是底层的基础服务。一眼扫过去，红蓝节点就是架构上首先要关注的腐败点。不用展开看细节，颜色就是信号。

4. 一次完整的实战：给 Spring Boot 订单服务做全景图谱

4.1 扫描命令与分析耗时

光讲参数有点虚，我拿一个真实项目举例。这是一个标准的 Spring Boot 订单服务，大概有 600 个 Java 类、2000 多个接口定义，里面还混了一小段 Python 脚本做对账逻辑。我的扫描命令：

codegraph scan \ --lang java,python \ --exclude target,node_modules,build \ --base-dir ./order-service \ --output ./_codegraph/order-service.cg

跑完耗时大概 1 分 40 秒，占用内存约 3.2GB，第一次看到这个数据我觉得有点重，但后来发现建模阶段是完全可以接受的。扫描完成后生成的.cg文件就是全部图谱数据，后续 graphify 的所有操作都基于这个文件，不需要重新扫描。

这里有个很实用的技巧：把扫描结果文件提交到 Git LFS 或者共享目录，整个团队就能直接共享同一份图谱数据，不用每个人都在本机跑一遍扫描。对老项目来说尤其省时间，因为扫描一次之后，你只是想换个角度看图的话，根本不需要重新解析代码。

4.2 从 Controller 到 Mapper：一条调用链的读图方法

我以订单查询接口为例，把读图方法讲清楚。先定位 Controller 里的OrderQueryController，用 graphify 取出它的一层调用：

codegraph graphify \ --scope com.example.order.controller.OrderQueryController \ --depth 1 \ --edge-type call \ --format svg \ --output controller.svg

图上立刻能看到这层 Controller 直接依赖了五六个 Service。这一步很有意思，因为很多同学读代码的习惯是从 Controller 不断往下钻，但实际上只在第一层停留，你就能发现 Controller 是否干了一些不该干的活。我这张图上就发现有两个 Service 名字带Processor，但它们的包路径居然是web包，这明显是分层飘了。

再往下走一步，选中OrderQueryService，把 depth 放到 3，就能看到它向下延伸的两条大分支：一条是走缓存再走 Mapper，另一条直接怼到数据库。这种"旁路访问"用肉眼看代码有时候真不容易发现，因为从 Service 到 Mapper 之间隔着好几个委托方法，但在图上就是一根清晰的直边，非常扎眼。

4.3 用图谱当场揪出的两个设计问题

第一次跑完这个订单服务的全景图，我至少发现两个值得记录的设计问题。

第一个是OrderDO这个实体类被 30 多个类直接引用，包括不应该碰持久化对象的 Controller 和 DTO 转换层。在图上，这些边全部指向OrderDO，节点闪亮得就像一个被中心化攻击的目标。后来我们做了OrderEntity的拆分和适配层，才把这张网的扇入压下来。

第二个是同包内循环引用。图里OrderCacheManager和OrderIndexManager之间出现了双向箭头，代码上表现为这两个类互相调用了对方的方法，而它们都还在同一个service.cache包下。这种循环虽然编译没事，但往往意味着职责边界没有分清楚。后来我在 CI 里加了一个检查，只要 graphify 导出的 JSON 里出现同包双向imports边，就自动打一个 warning。

图谱的作用不在于告诉你哪里绝对有 bug，而在于告诉你哪里的规模和密度不对劲，然后把你的注意力精准引过去。

5. 我在 codegraph 上踩过的坑，以及对应的绕行方案

5.1 匿名函数和反射调用导致的关系漏检

静态分析的天花板就是代码的动态特性，codegraph 对反射调用、SPI 加载、通过字符串拼出来的类名几乎是抓瞎的，只能靠深度索引和启发式规则去猜。我第一次扫描一个用了大量反射的配置中心组件时，图上缺失了很多关键的 Provider 到实际实现类的边，导致我一度以为某个功能是无依赖的。

处理这个问题我总结了两个对策：

• 对已知的反射入口，在 codegraph 的配置里手动补充"别名映射"，告诉它某个字符串对应的真实类型，让缺失的边补回来。
• 在图上发现疑似断裂的链时，不要直接断言没有依赖，先搜一下字符串常量，看看是不是反射或者工厂模式动态创建的对象。

这个坑的本质可以这样理解：codegraph 给你画的地图只代表静态世界的已知道路，动态世界里还有隐藏传送门。那些传送门不在地图上，但你可以把地图和代码搜索结合使用来确认。

5.2 大型仓库扫描时的内存策略

我踩过最疼的一次坑，是扫描一个包含大量代码生成产物的 Go 仓库时，codegraph 的进程直接 OOM，原因是生成产物里的巨大 init 函数和重复符号把建模器撑爆了。

这个问题的解决方案不是盲目加大内存，而是先缩范围和调配置：

• --exclude一定要覆盖生成目录，比如pb、mock、generated。
• --max-node-count或者类似的限制参数，可以给单个文件解析设一个节点上限，超过上限的放弃详细建模只保留粗粒度节点。
• 分模块扫描比全量扫描稳定得多。先扫核心模块，再扫周边模块，最后再用graphify --merge把多个.cg文件合并成一张大图。

合并不是简单的拼接，它会把相同符号的节点合并起来，边也会做去重。我后来把订单仓库的扫描切成了"web + service + infrastructure"三个批次，每批跑完单独验证，最后再合并，整体内存峰值从开机即挂降到了 4GB 内。

5.3 图谱太乱时我优先做的三件事

如果你生成的图谱一打开就像一碗加了福尔马林的意大利面，先别急着怪工具，大概率是你没有做好缩图。我现在的流程是三分法：

第一，先做分层审查。只保留imports边，关掉call边，看模块级的依赖关系。这一层如果已经干净，再往函数级走。第二，正则过滤掉样板节点。比如把Lombok生成的Builder、Accessor类全部过滤掉，它们对业务分析没有价值，只会增加噪音。第三，使用 group 折叠。graphify 可以按包前缀折叠成一个大圆点，一个com.example.order.controller包折叠成一个节点后，整个图的节点量直降 80%，结构瞬间清晰。

这三件事做完仍然乱的图，往往就说明真实代码已经乱到值得深刻反思了，而不是图的问题。

6. 把 codegraph 从"临时工具"变成"日常开发基建"的几条路径

6.1 接入 CI：PR 触发依赖变更检查

graphify 的 JSON 输出最大的价值是可以被脚本消费。我在一个后端仓库里做了一套依赖变更检查：每次 PR 触发时，用 git 拿到变更文件列表，再和最新图谱数据比对，计算这些文件对应节点的出向边和入向边，之后把依赖关系的变化写入 PR 评论。

比如某人改了UserService的公共方法签名，脚本会在评论里列出所有调用UserService的下游类。这种提醒对我来说太有用了，等构建报错才去改调用方，远远慢于在评论里提前看到影响清单。

这里有个小原理：codegraph 索引完整个仓库后，定位"谁引用了我"这类反查操作是 O(1) 级别的，而纯文本搜索是 O(n)。所以它本质上把"看代码影响面"从搜索问题变成了索引问题，效率不是一个量级。

6.2 自动生成架构文档，替代画不完的 UML

我见过的多数团队架构图都是手工画的，画完就过期。用 codegraph 的方式完全是自动的：定时任务对主干分支扫描建模，graphify 一键渲染模块级依赖图，再嵌入 MkDocs 或 Hexo 的文档站点。

这样做有几个实打实的好处：

• 架构图永远和真实代码同步，不存在"图上画的是三层，代码里已经七层"的尴尬。
• 修改代码后重新生成图谱，马上能看到架构是否发生了变化。
• 新同事上岗时，把生成的调用图当成第一份阅读材料，比让他自己翻代码快得多。

我现在的团队里已经没人画 UML 架构图了，因为 push 代码时 CI 会自动刷新一份模块级依赖图。这对我来说是最近一年收益最高的自动化改造之一。

6.3 与 IDE 插件配合的使用节奏

codegraph 本身没有功能完整的 IDE 插件，它更偏向命令行和 CI 环境。我日常的使用节奏是：先在 IDE 里做点状查询定位某个类的具体代码，然后到终端用 codegraph 拉出这个类的上下文图谱，把局部小图导出成 SVG 放到一个工作用的tmp目录，自己在上面写写画画做标注。

长期配合下来，我形成了一个比较固定的"点-线-面"节奏：

• 点：IDE 内跳转，看具体实现。
• 线：graphify 拉出某一条业务链的完整路径。
• 面：隔几周跑一次全量扫描，看整个服务的宏观依赖结构有没有漂移。

如果哪天我发现代码改了但图上没有出现预期的新边，那就说明引入的新依赖可能走了动态加载这类让静态分析失明的方式，这本身就是需要警惕的信号。

这些是我最近用得最顺的配套组合。工具不复杂，复杂的是让图替你说话的习惯。如果你手里也有那种编年史级别的老代码库，建议今天就装一个 codegraph，跑一次全量扫描，把第一张全景图生成出来。图出来的那一刻，很多被掩盖多年的架构真相，就藏在你一眼能看到的地方。