1. 为什么需要 codegraph代码图谱到底是什么先交代一下背景。做后端的这些年我见过太多团队在接手老项目时的状态代码仓库几十万行模块之间绕来绕去新人进来第一周基本就是在 IDE 里点跳转从一个文件跳到另一个文件再跳回来循环往复一天下来脑子像被塞了一团毛线。这个问题不是文档能解决的——文档写得再好也常常落后于代码也不是架构图能解决的——架构图画的是你预期的样子而不是代码真实的样子。codegraph 解决的就是这个痛点它把一份代码仓库解析成一张可交互的图让函数调用、模块依赖、类继承关系不再藏在文件里而是变成你面前可以缩放、点击、搜索的可视化图谱。你管这个动作叫 codegraph graphify简单说就是把代码图化。它可以生成函数调用图、模块依赖图、类关系图还能按某个文件逆向查出它影响了哪些上游调用方。这个工具不是代码审查插件也不是 CI 里跑 lint 的东西它更像一个代码地图生成器——给定任意语言的项目吐出一张能够导航的地图。我把它实际用下来的感受是适合三类人。第一类是接盘老项目的开发需要在一个陌生仓库里快速搞清楚边界和依赖第二类是做重构的技术 leader需要量化改这个模块会波及哪些模块第三类是写架构文档的人想让文档里的图和真实代码对齐。如果你刚入职一家新公司要在一个几万文件的仓库里找方向codegraph 比人带你看代码省力得多。接下来我把核心设计、安装使用、实际场景和踩坑记录都展开讲。2. 核心设计拆解图模型、解析链路与方案取舍2.1 图模型节点、边和元数据在看它的使用之前有必要先弄清楚 codegraph 内部是怎么描述代码的。它的图模型并不复杂一共就三层节点Node、边Edge、元数据Metadata。节点分四类file文件、module包/模块、class类、function函数。每类节点保存自己的基础属性比如文件路径、函数名、类名、起始行号、结束行号。边描述关系常见的有 callsA 函数调用了 B 函数、importsA 文件导入了 B 文件、extendsA 类继承了 B 类、implementsA 类实现了 B 接口。元数据则挂在节点上默认会计算行数Lines of Code和圈复杂度Cyclomatic Complexity这两个指标后面在定位上帝类和高危函数时非常有用。这套模型的好处是足够通用。不管底层是什么语言解析出来后最终都落到节点-边这个结构上所以它可以用一套统一的可视化界面去展示不同语言的代码。坏处是它舍弃了更细粒度的信息比如变量的数据流、条件分支的具体路径这意味着它做不了特别深度的程序分析。真实使用中这个取舍是对的——做代码图谱的目标是给人看结构不是替代编译器做静态断言。2.2 解析引擎从源码到 AST 再到图谱graphify 背后的核心链路是读取文件 - 生成语法树AST- 识别符号与关系 - 构建图。具体来说codegraph 使用 tree-sitter 作为解析引擎而不是传统的正则表达式。tree-sitter 的特点是增量解析且错误容忍度好即使文件里存在局部语法错误它也能解析出大部分结构不会因为一个不完整表达式就丢弃整个文件。这也是 codegraph 能处理真实生产代码的重要原因——现实世界里的代码仓库总有各种历史遗留问题用严格的 AST 解析器比如编译器前端往往读几个文件就被不兼容语法击穿。拿到 AST 之后解析器做三件事收集声明函数定义、类定义、导入语句、收集引用函数调用点、继承声明、建立符号表做作用域消解。最后把消解后的关系写入图中。这一步最费时间的是跨文件符号消解——比如你有一个 utils.py 里的 format_name 函数别的模块都 import 它然后调用codegraph 需要把调用点准确挂到 utils.py 那个函数节点上而不是只画一个未知调用。这一步做不好图就退化成文件级别的依赖图价值大打折扣。方案上让我比较认可的是 codegraph 支持多种语言共用一个图结构不会出现Python 项目和 Go 项目产出两种格式的问题。目前官方支持 Python、JavaScript、TypeScript、Go、Java、PHP、Ruby 等主流语言冷门语言的支持靠社区贡献 parser遇到不支持的语法就跳过该文件并在日志里提示。3. 五分钟上手安装、初始化与 graphify 实战3.1 安装与环境准备codegraph 以 CLI 工具的形式提供安装非常简单。它是 Python 实现的所以一条 pip 命令就能装好pip install codegraph codegraph --version如果是在国内网络环境建议先配置好镜像源这步不展开。装完以后最好确认一下 graphify 子命令可用codegraph graphify --help我建议在一个干净的虚拟环境里装避免和项目依赖冲突。实测在 Python 3.9 到 3.12 上都能跑通底层 tree-sitter 是预编译的 wheel 包不需要本地编译环境对 Windows 用户也比较友好。你不需要安装任何数据库或服务端图谱默认以 JSON 文件落盘可视化界面用浏览器打开本地 HTML 文件就行。环境准备阶段唯一要注意的是磁盘空间。一个一万文件规模的中型仓库生成的 graph JSON 大概是几十 MB 量级可视化预览时浏览器内存占用可能接近 1GB所以跑大项目时别用太低配的机器。3.2 初始化与配置扫描范围安装完成后进入目标项目目录执行初始化cd /path/to/your/project codegraph init --language python --output .codegraph/执行后会自动识别项目结构生成一个.codegraph/config.json配置文件。这个文件建议直接用编辑器打开看一眼里面会写清楚项目根目录、语言类型、需要忽略的路径列表。官方默认会忽略.git、node_modules、vendor、dist、build等目录你可以把tests目录也加进 exclude后面扫描会快很多。我强烈建议你在首次扫码前手动在配置里把生成的报告路径和是否计算圈复杂度改一下。报告路径默认放在项目根目录下如果你是用 Git 管理的大仓库这个文件会污染git status推荐把它也放到.codegraph/下面。复杂度计算默认是开的几百个函数规模的小项目无所谓但上万文件时这个计算会显著拉长扫描时间不是必要就不要开。3.3 graphify 生成图谱的三条核心命令初始化完成后真正的解析命令是codegraph scan ./src -o .codegraph/repo.json --exclude tests,migrationsscan只负责解析和落盘不启动可视化。跑完后会输出统计信息比如解析了多少个文件、生成了多少节点和边、解析失败的文件列表。这步是 graphify 的前置动作整个 codegraph 工具链的逻辑是先 scan 出中间产物再交给 graphify 进行图结构优化和聚合。第二条命令是真正干活的codegraph graphify .codegraph/repo.json -o .codegraph/graph.json --focus auth_service --depth 3 --filter function它读取 scan 生成的 JSON构建最终图谱。这里的--focus指定中心节点--depth控制向外扩散多少层--filter指定只保留某种类型的节点。这套参数组合是 codegraph 的精髓——一个上万节点的完整图直接可视化你根本看不清服务器也扛不住但当你只聚焦某个核心服务向外展开 3 层调用关系时图就变得非常可读了。最后一步是启动可视化服务codegraph serve .codegraph/graph.json --port 8200默认会起一个本地 Web 服务浏览器访问http://localhost:8200就能看到交互式图谱。图谱支持拖拽、缩放、搜索、按类型过滤、高亮上下游节点实测下来比导出静态 PNG 实用得多。它也支持导出为.dot格式供 Graphviz 渲染或者导出为.gephi格式到 Gephi 软件里做深度分析但这些属于进阶玩法日常用serve就够。3.4 五个常用参数与典型组合参数作用适用场景--focus指定图谱中心节点分析某个服务/模块的调用链--depth向外扩散层数默认2小范围分析与全图分析切换--filter按类型过滤节点function/file/class/module只看函数级调用关系--exclude扫描时排除路径跳过测试、迁移、第三方代码--metrics是否计算复杂度与行数做重构评估时需要普通导航时可关掉典型组合示例想看payment模块被谁依赖可以这样跑codegraph graphify repo.json --focus payment --depth 2 --filter module -o payment_dep.json codegraph serve payment_dep.json --port 8201这样页面里打开的就是一张以 payment 为中心的依赖关系图所有直接和间接依赖它的模块都会显示出来边上的箭头方向和权重很清楚。这个命令组合也是我日常用得最多的一套。4. 真实应用场景新人导航、重构评估与代码审查4.1 新人 onboarding 与架构文档对齐我团队里来了个新同事负责用户中心服务第一次跑codegraph scan之后我直接把serve的地址发给他让他在图谱上从自己负责的模块开始往外点。这是一种完全不同于传统阅读源码的体验新人在十分钟内就能知道我这个模块调用了哪些底层公共库哪些上层服务反向依赖我这种全局感是看代码无论如何都建立不起来的。更实用的是把 graphify 的结果导出成架构文档的附图。过去架构文档里的模块关系图是手工画的几乎必然是美化版。现在可以直接把图谱截图贴进 Wiki并附上 JSON 文件地址让文档和代码真实结构始终同步。我自己实践下来新同事对业务边界的理解速度至少快一倍不太会在第一周问出这个服务到底是做什么的这种方向性问题。4.2 重构评估量化改动影响面做重构时最怕的不是改代码而是不知道改这一处会炸掉哪里。codegraph 的反向依赖查询功能就是为这个场景设计的。举个实际例子我们有个老模块的数据库连接函数get_connection用了全局单例现在要改成连接池需要知道所有直接和间接调用方。用 codegraph 的--focus get_connection --depth 3 --filter function一运行受影响函数全部列出来按文件统计一下就有改动包规模预估。更关键的是它能把间接调用暴露出来——你可能只改了底层函数却影响到了三层之外的一个定时任务这种隐藏链路在传统 IDE 的 Find References 里很难一次找全。重构前后还能对比同样的图重构前底层节点被几百个节点指向重构后被拆成多个独立小模块出图效果非常直观给老板汇报时一张图胜过十页 PPT。这里建议把--metrics打开重构图中的圈复杂度分布是判断重构收益的硬指标。4.3 代码审查与架构健康度检查在评审场景里codegraph 目前更偏辅助角色但已经能发现三类有价值的问题第一循环依赖。图上如果出现成环的子图说明模块之间存在循环 import这在运行期可能不会报错但会显著拖慢启动速度也是后续改造的阻碍。codegraph 会把环内的节点用特殊颜色标出检查时直接定位。第二超级依赖节点。图谱中那些边数特别多的节点往往是架构上的重镇但同时也是最脆弱的位置——一旦改动波及面巨大。这类节点如果在业务上不需要被这么多模块依赖就是要拆分的信号。我们常说的上帝类就是这种节点。第三死代码。call graph 里孤立节点没有任何入边也没有出边的函数通常是未被引用的废弃函数。虽然编译器也能警告部分情况但跨模块的孤儿函数靠编译器查不全。清理死代码之前先用 codegraph 筛一遍比人工翻文件高效。5. 常见问题与排查技巧实录5.1 解析失败为什么 scan 报告有文件读不了codegraph 不是万能的真实仓库里总会有解析不了的文件。常见原因有三类第一语法真的太老或太新。比如你用 tree-sitter 的 Python parser 解析一个用了最新语法糖的文件parser 版本没跟上就会失败。解决办法是升级 codegraph 或者手动屏蔽这些文件一般不影响全局图谱。第二动态语言里的动态调用。Python 的getattr(obj, name)()、globals()[func_name]()这类动态调度静态分析不可能完全识别codegraph 会把这些调用标记为未知调用在图上表现为指向根节点的灰色边。遇到这种情况别期望工具能做数据流推导它只能做到静态可解析的边界。第三C/C 的宏展开。如果你扫一个 C 项目宏定义和预处理会让 AST 和真实代码不完全一致。codegraph 对 C/C 的解析需要依赖compile_commands.json编译数据库否则宏内部的函数调用可能漏掉。这算已知限制不是 bug。5.2 图太大跑不动剪枝与聚焦思路大仓库最常遇到的问题就是图谱节点太多浏览器卡死。我第一跑一个几万文件的老仓库生成的图打开以后页面直接无响应。后来总结出三招第一聚焦优先。先--focus到一个核心模块--depth 2跑出来的图通常几百个节点浏览器毫无压力。你需要全貌的时候再逐步加大 depth。第二类型过滤。文件级依赖图往往比函数级大一个数量级。做架构分析时用--filter module或--filter file做代码审查时才用 function两个粒度各跑一张图互为补充。第三排除噪声目录。测试目录、示例代码、迁移脚本、工具脚本这些在图里大多是噪声节点扫之前就在 exclude 里排掉。我习惯在配置里默认排除tests,docs,examples,scripts,migrations分析业务核心时不看它们。5.3 图结构对不上直觉边界问题有几次我拿图谱跟实际代码比对发现某些调用关系跟我预判的不一样。排查后发现不是工具错了而是我自己的认知错了——比如一个函数在父类里定义了子类继承了但没显式调用图谱上它依然会显示父类的实现入口。这是继承导致的行为不算 bug但使用时要理解codegraph 画的是代码静态结构不是运行期的动态调用栈。动态派发的调用比如多态、接口实现在静态图里会表现为指向可能的实现集合需要你自己结合业务判断。5.4 中文路径与 Windows 编码Windows 平台下项目路径含中文目录名时scan 阶段偶尔会出现编码问题生成的 JSON 里路径乱码浏览器里显示异常。我踩过一次后直接把项目放在纯英文路径下跑这算个简单位法。如果你不能改目录名那就只能手动改配置文件里的encodingutf-8选项实测能解决大部分中文路径问题。另外输出文件名尽量别用中文避免中间环节再出幺蛾子。6. 常用命令速查与配置模板6.1 命令行速查表子命令作用常用参数codegraph init初始化项目配置--language、--outputcodegraph scan扫描源码生成中间 JSON--exclude、-o、--metricscodegraph graphify构建最终图谱--focus、--depth、--filter、-ocodegraph serve启动可视化服务--port、--opencodegraph export导出为其他格式--format dot/gephicodegraph stats输出仓库统计指标--json6.2 一份可以直接抄的配置模板{ root: ./src, language: python, exclude: [tests, docs, node_modules, .venv], metrics: { complexity: true, lines: true }, output: { dir: .codegraph, format: json }, graph: { defaultDepth: 2, defaultFilter: function } }这套配置我用了很久算是常规项目的一个稳妥起点。里面的defaultDepth和defaultFilter定义了每次打开可视化时的默认视角建议保持默认函数级 2 层不然首次打开会卡。6.3 排查问题用到的三句话如果你跑出来结果明显异常先按这个顺序排查看 scan 日志里的解析失败文件数——如果大批文件失败先解决 parser 版本或语法兼容问题图才能可信。检查 exclude 是否误伤了真实源码——有人把 src 目录正则写错扫了个空目录图自然也是空的。确认 focus 节点的名字拼写——focus 要写节点 ID不是包名。先用codegraph stats .codegraph/repo.json --json列出所有节点再复制粘贴 ID 到 graphify 参数里能省很多事。我对这个工具的定位一直是导航地图而不是代码医生。它不告诉你代码哪里错了但它能让你在迷路的时候知道自己在哪里。至少在我自己带项目、带新人的过程中它的作用不是减少写代码的时间而是减少找代码的时间——这往往是更隐蔽也更严重的浪费。如果你手头也有个说不清架构的老仓库与其对着目录结构猜不如花十分钟跑一次 graphify用图说话。 codegraph 代码图谱实战：从 AST 解析到函数调用依赖可视化
1. 为什么需要 codegraph代码图谱到底是什么先交代一下背景。做后端的这些年我见过太多团队在接手老项目时的状态代码仓库几十万行模块之间绕来绕去新人进来第一周基本就是在 IDE 里点跳转从一个文件跳到另一个文件再跳回来循环往复一天下来脑子像被塞了一团毛线。这个问题不是文档能解决的——文档写得再好也常常落后于代码也不是架构图能解决的——架构图画的是你预期的样子而不是代码真实的样子。codegraph 解决的就是这个痛点它把一份代码仓库解析成一张可交互的图让函数调用、模块依赖、类继承关系不再藏在文件里而是变成你面前可以缩放、点击、搜索的可视化图谱。你管这个动作叫 codegraph graphify简单说就是把代码图化。它可以生成函数调用图、模块依赖图、类关系图还能按某个文件逆向查出它影响了哪些上游调用方。这个工具不是代码审查插件也不是 CI 里跑 lint 的东西它更像一个代码地图生成器——给定任意语言的项目吐出一张能够导航的地图。我把它实际用下来的感受是适合三类人。第一类是接盘老项目的开发需要在一个陌生仓库里快速搞清楚边界和依赖第二类是做重构的技术 leader需要量化改这个模块会波及哪些模块第三类是写架构文档的人想让文档里的图和真实代码对齐。如果你刚入职一家新公司要在一个几万文件的仓库里找方向codegraph 比人带你看代码省力得多。接下来我把核心设计、安装使用、实际场景和踩坑记录都展开讲。2. 核心设计拆解图模型、解析链路与方案取舍2.1 图模型节点、边和元数据在看它的使用之前有必要先弄清楚 codegraph 内部是怎么描述代码的。它的图模型并不复杂一共就三层节点Node、边Edge、元数据Metadata。节点分四类file文件、module包/模块、class类、function函数。每类节点保存自己的基础属性比如文件路径、函数名、类名、起始行号、结束行号。边描述关系常见的有 callsA 函数调用了 B 函数、importsA 文件导入了 B 文件、extendsA 类继承了 B 类、implementsA 类实现了 B 接口。元数据则挂在节点上默认会计算行数Lines of Code和圈复杂度Cyclomatic Complexity这两个指标后面在定位上帝类和高危函数时非常有用。这套模型的好处是足够通用。不管底层是什么语言解析出来后最终都落到节点-边这个结构上所以它可以用一套统一的可视化界面去展示不同语言的代码。坏处是它舍弃了更细粒度的信息比如变量的数据流、条件分支的具体路径这意味着它做不了特别深度的程序分析。真实使用中这个取舍是对的——做代码图谱的目标是给人看结构不是替代编译器做静态断言。2.2 解析引擎从源码到 AST 再到图谱graphify 背后的核心链路是读取文件 - 生成语法树AST- 识别符号与关系 - 构建图。具体来说codegraph 使用 tree-sitter 作为解析引擎而不是传统的正则表达式。tree-sitter 的特点是增量解析且错误容忍度好即使文件里存在局部语法错误它也能解析出大部分结构不会因为一个不完整表达式就丢弃整个文件。这也是 codegraph 能处理真实生产代码的重要原因——现实世界里的代码仓库总有各种历史遗留问题用严格的 AST 解析器比如编译器前端往往读几个文件就被不兼容语法击穿。拿到 AST 之后解析器做三件事收集声明函数定义、类定义、导入语句、收集引用函数调用点、继承声明、建立符号表做作用域消解。最后把消解后的关系写入图中。这一步最费时间的是跨文件符号消解——比如你有一个 utils.py 里的 format_name 函数别的模块都 import 它然后调用codegraph 需要把调用点准确挂到 utils.py 那个函数节点上而不是只画一个未知调用。这一步做不好图就退化成文件级别的依赖图价值大打折扣。方案上让我比较认可的是 codegraph 支持多种语言共用一个图结构不会出现Python 项目和 Go 项目产出两种格式的问题。目前官方支持 Python、JavaScript、TypeScript、Go、Java、PHP、Ruby 等主流语言冷门语言的支持靠社区贡献 parser遇到不支持的语法就跳过该文件并在日志里提示。3. 五分钟上手安装、初始化与 graphify 实战3.1 安装与环境准备codegraph 以 CLI 工具的形式提供安装非常简单。它是 Python 实现的所以一条 pip 命令就能装好pip install codegraph codegraph --version如果是在国内网络环境建议先配置好镜像源这步不展开。装完以后最好确认一下 graphify 子命令可用codegraph graphify --help我建议在一个干净的虚拟环境里装避免和项目依赖冲突。实测在 Python 3.9 到 3.12 上都能跑通底层 tree-sitter 是预编译的 wheel 包不需要本地编译环境对 Windows 用户也比较友好。你不需要安装任何数据库或服务端图谱默认以 JSON 文件落盘可视化界面用浏览器打开本地 HTML 文件就行。环境准备阶段唯一要注意的是磁盘空间。一个一万文件规模的中型仓库生成的 graph JSON 大概是几十 MB 量级可视化预览时浏览器内存占用可能接近 1GB所以跑大项目时别用太低配的机器。3.2 初始化与配置扫描范围安装完成后进入目标项目目录执行初始化cd /path/to/your/project codegraph init --language python --output .codegraph/执行后会自动识别项目结构生成一个.codegraph/config.json配置文件。这个文件建议直接用编辑器打开看一眼里面会写清楚项目根目录、语言类型、需要忽略的路径列表。官方默认会忽略.git、node_modules、vendor、dist、build等目录你可以把tests目录也加进 exclude后面扫描会快很多。我强烈建议你在首次扫码前手动在配置里把生成的报告路径和是否计算圈复杂度改一下。报告路径默认放在项目根目录下如果你是用 Git 管理的大仓库这个文件会污染git status推荐把它也放到.codegraph/下面。复杂度计算默认是开的几百个函数规模的小项目无所谓但上万文件时这个计算会显著拉长扫描时间不是必要就不要开。3.3 graphify 生成图谱的三条核心命令初始化完成后真正的解析命令是codegraph scan ./src -o .codegraph/repo.json --exclude tests,migrationsscan只负责解析和落盘不启动可视化。跑完后会输出统计信息比如解析了多少个文件、生成了多少节点和边、解析失败的文件列表。这步是 graphify 的前置动作整个 codegraph 工具链的逻辑是先 scan 出中间产物再交给 graphify 进行图结构优化和聚合。第二条命令是真正干活的codegraph graphify .codegraph/repo.json -o .codegraph/graph.json --focus auth_service --depth 3 --filter function它读取 scan 生成的 JSON构建最终图谱。这里的--focus指定中心节点--depth控制向外扩散多少层--filter指定只保留某种类型的节点。这套参数组合是 codegraph 的精髓——一个上万节点的完整图直接可视化你根本看不清服务器也扛不住但当你只聚焦某个核心服务向外展开 3 层调用关系时图就变得非常可读了。最后一步是启动可视化服务codegraph serve .codegraph/graph.json --port 8200默认会起一个本地 Web 服务浏览器访问http://localhost:8200就能看到交互式图谱。图谱支持拖拽、缩放、搜索、按类型过滤、高亮上下游节点实测下来比导出静态 PNG 实用得多。它也支持导出为.dot格式供 Graphviz 渲染或者导出为.gephi格式到 Gephi 软件里做深度分析但这些属于进阶玩法日常用serve就够。3.4 五个常用参数与典型组合参数作用适用场景--focus指定图谱中心节点分析某个服务/模块的调用链--depth向外扩散层数默认2小范围分析与全图分析切换--filter按类型过滤节点function/file/class/module只看函数级调用关系--exclude扫描时排除路径跳过测试、迁移、第三方代码--metrics是否计算复杂度与行数做重构评估时需要普通导航时可关掉典型组合示例想看payment模块被谁依赖可以这样跑codegraph graphify repo.json --focus payment --depth 2 --filter module -o payment_dep.json codegraph serve payment_dep.json --port 8201这样页面里打开的就是一张以 payment 为中心的依赖关系图所有直接和间接依赖它的模块都会显示出来边上的箭头方向和权重很清楚。这个命令组合也是我日常用得最多的一套。4. 真实应用场景新人导航、重构评估与代码审查4.1 新人 onboarding 与架构文档对齐我团队里来了个新同事负责用户中心服务第一次跑codegraph scan之后我直接把serve的地址发给他让他在图谱上从自己负责的模块开始往外点。这是一种完全不同于传统阅读源码的体验新人在十分钟内就能知道我这个模块调用了哪些底层公共库哪些上层服务反向依赖我这种全局感是看代码无论如何都建立不起来的。更实用的是把 graphify 的结果导出成架构文档的附图。过去架构文档里的模块关系图是手工画的几乎必然是美化版。现在可以直接把图谱截图贴进 Wiki并附上 JSON 文件地址让文档和代码真实结构始终同步。我自己实践下来新同事对业务边界的理解速度至少快一倍不太会在第一周问出这个服务到底是做什么的这种方向性问题。4.2 重构评估量化改动影响面做重构时最怕的不是改代码而是不知道改这一处会炸掉哪里。codegraph 的反向依赖查询功能就是为这个场景设计的。举个实际例子我们有个老模块的数据库连接函数get_connection用了全局单例现在要改成连接池需要知道所有直接和间接调用方。用 codegraph 的--focus get_connection --depth 3 --filter function一运行受影响函数全部列出来按文件统计一下就有改动包规模预估。更关键的是它能把间接调用暴露出来——你可能只改了底层函数却影响到了三层之外的一个定时任务这种隐藏链路在传统 IDE 的 Find References 里很难一次找全。重构前后还能对比同样的图重构前底层节点被几百个节点指向重构后被拆成多个独立小模块出图效果非常直观给老板汇报时一张图胜过十页 PPT。这里建议把--metrics打开重构图中的圈复杂度分布是判断重构收益的硬指标。4.3 代码审查与架构健康度检查在评审场景里codegraph 目前更偏辅助角色但已经能发现三类有价值的问题第一循环依赖。图上如果出现成环的子图说明模块之间存在循环 import这在运行期可能不会报错但会显著拖慢启动速度也是后续改造的阻碍。codegraph 会把环内的节点用特殊颜色标出检查时直接定位。第二超级依赖节点。图谱中那些边数特别多的节点往往是架构上的重镇但同时也是最脆弱的位置——一旦改动波及面巨大。这类节点如果在业务上不需要被这么多模块依赖就是要拆分的信号。我们常说的上帝类就是这种节点。第三死代码。call graph 里孤立节点没有任何入边也没有出边的函数通常是未被引用的废弃函数。虽然编译器也能警告部分情况但跨模块的孤儿函数靠编译器查不全。清理死代码之前先用 codegraph 筛一遍比人工翻文件高效。5. 常见问题与排查技巧实录5.1 解析失败为什么 scan 报告有文件读不了codegraph 不是万能的真实仓库里总会有解析不了的文件。常见原因有三类第一语法真的太老或太新。比如你用 tree-sitter 的 Python parser 解析一个用了最新语法糖的文件parser 版本没跟上就会失败。解决办法是升级 codegraph 或者手动屏蔽这些文件一般不影响全局图谱。第二动态语言里的动态调用。Python 的getattr(obj, name)()、globals()[func_name]()这类动态调度静态分析不可能完全识别codegraph 会把这些调用标记为未知调用在图上表现为指向根节点的灰色边。遇到这种情况别期望工具能做数据流推导它只能做到静态可解析的边界。第三C/C 的宏展开。如果你扫一个 C 项目宏定义和预处理会让 AST 和真实代码不完全一致。codegraph 对 C/C 的解析需要依赖compile_commands.json编译数据库否则宏内部的函数调用可能漏掉。这算已知限制不是 bug。5.2 图太大跑不动剪枝与聚焦思路大仓库最常遇到的问题就是图谱节点太多浏览器卡死。我第一跑一个几万文件的老仓库生成的图打开以后页面直接无响应。后来总结出三招第一聚焦优先。先--focus到一个核心模块--depth 2跑出来的图通常几百个节点浏览器毫无压力。你需要全貌的时候再逐步加大 depth。第二类型过滤。文件级依赖图往往比函数级大一个数量级。做架构分析时用--filter module或--filter file做代码审查时才用 function两个粒度各跑一张图互为补充。第三排除噪声目录。测试目录、示例代码、迁移脚本、工具脚本这些在图里大多是噪声节点扫之前就在 exclude 里排掉。我习惯在配置里默认排除tests,docs,examples,scripts,migrations分析业务核心时不看它们。5.3 图结构对不上直觉边界问题有几次我拿图谱跟实际代码比对发现某些调用关系跟我预判的不一样。排查后发现不是工具错了而是我自己的认知错了——比如一个函数在父类里定义了子类继承了但没显式调用图谱上它依然会显示父类的实现入口。这是继承导致的行为不算 bug但使用时要理解codegraph 画的是代码静态结构不是运行期的动态调用栈。动态派发的调用比如多态、接口实现在静态图里会表现为指向可能的实现集合需要你自己结合业务判断。5.4 中文路径与 Windows 编码Windows 平台下项目路径含中文目录名时scan 阶段偶尔会出现编码问题生成的 JSON 里路径乱码浏览器里显示异常。我踩过一次后直接把项目放在纯英文路径下跑这算个简单位法。如果你不能改目录名那就只能手动改配置文件里的encodingutf-8选项实测能解决大部分中文路径问题。另外输出文件名尽量别用中文避免中间环节再出幺蛾子。6. 常用命令速查与配置模板6.1 命令行速查表子命令作用常用参数codegraph init初始化项目配置--language、--outputcodegraph scan扫描源码生成中间 JSON--exclude、-o、--metricscodegraph graphify构建最终图谱--focus、--depth、--filter、-ocodegraph serve启动可视化服务--port、--opencodegraph export导出为其他格式--format dot/gephicodegraph stats输出仓库统计指标--json6.2 一份可以直接抄的配置模板{ root: ./src, language: python, exclude: [tests, docs, node_modules, .venv], metrics: { complexity: true, lines: true }, output: { dir: .codegraph, format: json }, graph: { defaultDepth: 2, defaultFilter: function } }这套配置我用了很久算是常规项目的一个稳妥起点。里面的defaultDepth和defaultFilter定义了每次打开可视化时的默认视角建议保持默认函数级 2 层不然首次打开会卡。6.3 排查问题用到的三句话如果你跑出来结果明显异常先按这个顺序排查看 scan 日志里的解析失败文件数——如果大批文件失败先解决 parser 版本或语法兼容问题图才能可信。检查 exclude 是否误伤了真实源码——有人把 src 目录正则写错扫了个空目录图自然也是空的。确认 focus 节点的名字拼写——focus 要写节点 ID不是包名。先用codegraph stats .codegraph/repo.json --json列出所有节点再复制粘贴 ID 到 graphify 参数里能省很多事。我对这个工具的定位一直是导航地图而不是代码医生。它不告诉你代码哪里错了但它能让你在迷路的时候知道自己在哪里。至少在我自己带项目、带新人的过程中它的作用不是减少写代码的时间而是减少找代码的时间——这往往是更隐蔽也更严重的浪费。如果你手头也有个说不清架构的老仓库与其对着目录结构猜不如花十分钟跑一次 graphify用图说话。