在 Go monorepo 里排查 dead code，比单仓库麻烦得多。仓库里有几十个 cmd 入口、几百个业务包、跨模块的 internal 引用，单靠go vet或者只针对单个 module 的 deadcode 工具，很难把不可达代码完整找出来。Deadmono 这个项目的目标很直接：detect dead code in Go monorepo，把整个仓库的入口集合整理出来，再去判断哪些代码真正不可达。适合维护中大型多模块仓库、正在做存量清理或想降低维护成本的技术团队关注。我最关心的不是它报出了多少死代码，而是它能否在真实的多模块结构里把误报压住，让后续删除动作可以安全推进。
下面按我自己的落地思路拆一遍。先讲清楚为什么 monorepo 场景会特殊，再讲分析对象、核心流程、误报判断，最后说大规模仓库怎么接 CI 和分批清理。
1. Monorepo 里的 dead code 为什么比单仓库更难发现
1.1 编译通过不等于代码活着
很多团队判断一段 Go 代码能不能删，第一反应是“编译一下，没人引用就删”。这个判断在单模块小仓库里接近有效，在 monorepo 里基本不成立。
Go 编译器的链接粒度是 package，不是 function。go build ./...能通过，只代表仓库里每个包自身语法正确、类型检查通过、依赖图完整，并不代表每个函数都被真正调用。一个包里的私有函数可以被全仓库无视，依然编译成功；一个导出函数没有内部调用者，同样不影响构建。
在 monorepo 里更隐蔽的是两种场景：
- A 模块里的函数没被 A 模块和 B 模块引用，但被 C 模块通过 go workspace 或者 replace 指令间接使用。
- 某个函数只被配置文件、计划任务入口、命令行参数分支或者测试数据引用，静态文本里搜不到函数名，代码里也确实没有直接调用。
这些情况下，“能编译”和“被使用”是两套完全不同的问题。Deadmono 这类工具的价值，就是尝试把“被使用”这件事量化，而不是靠编译结果去猜。
1.2 常规死代码检测工具在 monorepo 下的盲区
单模块场景下，大家常用这几类方法：
golang.org/x/tools/cmd/deadcode，从入口开始分析调用图，输出不可达函数。go vet里的 unreachable 检查，主要看单个函数内是否有不可达语句，粒度很小。staticcheck的 U1000 检查，能发现未使用的代码元素，但对跨模块和反射场景仍然偏保守。
这些工具在普通仓库表现不错，一旦进入 monorepo，会陆续出现盲区。
第一个盲区是入口定义不清。单模块仓库通常只有一两个main包，而 monorepo 可能有几十个独立 cmd 目录，每个目录都可能对应一个发布产物。只分析当前 module 内的 main 包，会漏掉其他 module 里的真实入口。
第二个盲区是跨模块依赖。A 模块暴露的公开函数是否被 B、C 模块使用，单模块工具不会跨 module 去构建完整索引。它会把很多“当前模块内没人调用”的导出函数直接归类为死代码，结果误报率非常高。
第三个盲区是 library 包。monorepo 里大量代码以 library 形式存在，它们不上线、不编译成二进制，只被内部其他模块 import。如果工具不理解“凡是导出的公开 API 都不能简单判死”这个规则，就会把整个包标记成可清理。
Deadmono 这类专门面向 monorepo 的工具，至少要处理这些盲区：识别全部模块的入口、跨模块构建引用关系、区分“仓库内死代码”和“外部使用者可能调用的公开 API”。
1.3 Deadmono 的定位：面向多模块入口体系
从项目描述和命名看，Deadmono 不是要替代go vet和staticcheck，而是补上它们在 monorepo 下的空缺。
它的核心分析对象不是单个 main 包，而是一整套入口体系：
- 所有 module 下的
main包； - 被内部工具、定时任务、脚本显式运行的命令行入口；
- 对外服务的 HTTP/gRPC handler 注册入口；
- 需要保留的公开导出 API（以包名为单位按规则跳过）。
从这些入口出发，按调用关系标记可达代码。标记结束后，仍然没有被任何入口触达的代码，才进入候选清理范围。
这个思路和单模块 deadcode 工具一致，差别在于“入口”不再是程序自动猜的默认值，而是可以按仓库实际情况配置。配置越准确，误报越少。
2. 先确认分析对象：仓库结构和入口点
2.1 大型仓库里哪些符号真正算“入口”
想降低误报，第一步不是运行工具，而是整理入口清单。我一般会把入口分成四类，分别处理。
| 入口类型 | 典型特征 | 处理策略 |
|---|---|---|
| 二进制入口 | cmd/*下的 main 包，会构建为独立可执行文件 | 必须标记为入口 |
| 服务注册入口 | HTTP handler、gRPC service、消息队列 consumer 的注册函数 | 必须标记为入口 |
| 内部库的公开 API | 被其他模块 import 的导出函数、类型、方法 | 按公共 API 保留，或单独配置白名单 |
| 脚本和代码生成入口 | go generate、CI 脚本调用的工具包、插件加载点 | 按实际调用链分析，不能一刀切 |
很多仓库的 dead code 集中在第一类和第二类之间的“灰色地带”。比如某个包的RegisterRoutes函数，静态扫描时没有人直接调用它，但 main 函数在初始化流程里通过反射或配置文件注册了它。单纯从调用图看，这就是死代码；从业务上讲，它是核心入口。
在运行 Deadmono 之前，我建议先在仓库里搜一遍这些关键模式：
func main()出现的目录；http.Handle、r.Handle、Register、MustRegister这类注册函数；grpc.Register、pb.Register开头的方法；go:generate指令附近被调用的工具函数。
把这些结果整理成入口清单，再让工具基于清单分析，会准确很多。
2.2 准备环境时先确认 Go 模块边界和分析依赖
分析 monorepo 死代码前，环境准备看起来简单，实际坑不少。
首先要确认仓库是怎么组织多模块的。常见有三种：
- 单
go.mod+ 大量目录，本质是一个大模块。 - 多
go.mod分布在子目录，各自独立。 go.workworkspace 管理多个 module，开发时统一构建。
Deadmono 要解决的是后两种，尤其是多 module 结构。如果仓库只有一个go.mod，那用单模块 deadcode 工具可能就够，未必需要额外引入项目。如果仓库已经使用go.work，先确认分析工具能否识别 workspace 的模块列表。
其次要确认 Go 工具链版本。静态分析工具通常紧跟 Go 版本，如果仓库里同时存在多个 Go 版本编译出来的代码，分析结果可能会因为标准库分析不同而产生差异。我的建议是：在准备引入 Deadmono 时，先用和 CI 一致的 Go 版本跑分析，避免本地和 CI 结果不一致。
第三个要注意的是 build tags 和平台差异。monorepo 里常见_linux.go、_windows.go、//go:build条件编译文件。如果没有明确指定平台，工具只会分析当前环境的编译路径，其他平台独有代码会被当成死代码。这是一个非常典型的误报来源。
这部分的处理策略是：跑分析时把目标平台设置成仓库实际发布的平台，比如GOOS=linux GOARCH=amd64；如果仓库有多个发布平台，就分别跑一遍，再合并结果。
2.3 资源占用预判：全仓分析为什么容易内存紧张
Go 静态分析工具最耗资源的阶段是构建调用图和全量类型检查。
单仓库几百个包还好，monorepo 几千个包时，类型检查会消耗大量内存。如果分析工具还需要把每个 module 的依赖索引加载进内存，内存增长会更快。
以我碰到的仓库规模为例，一个包含 800 到 1200 个包的 Go 仓库，全量分析时内存可能冲到 4GB 到 8GB。低配置开发机跑起来会有明显卡顿。这不代表工具本身有问题，而是全量分析本身就贵。
更稳妥的做法是：
- 本地先用小范围模块分析，不要直接全仓扫描；
- 分析前关闭 IDE、浏览器等吃内存的进程；
- 用 CI 专用任务跑全量分析，本地只做抽样验证；
- 如果支持增量分析或缓存，优先开启。
如果你在自己的机器上跑全仓分析出现 OOM，不要急着怪工具。先看是不是构建缓存没开、单次分析的包数量过大、或者模块索引没有复用。这三个原因占了绝大多数情况。
3. 核心检测流程：入口标记、调用图构建、不可达输出
3.1 第一步：定义入口集合，而不是让工具猜
我认为死代码分析工具最大的使用误区，就是“直接运行然后相信输出”。除非仓库非常简单，否则第一步必须先给工具一份入口列表。
按照我前面说的四类入口，入口集合大概可以这样组织：
# 示意格式，不代表真实项目命令 deadmono \ -modules ./module-a,./module-b,./module-c \ -entry ./cmd/api/... \ -entry ./cmd/worker/... \ -entry ./internal/server/... \ -exported-api keep这里核心参数有三个：
- 模块列表：告诉工具分析哪些范围，避免把 vendor 或第三方依赖一起分析；
- 入口集合：所有 main 包、注册函数、被框架调用的初始化点；
- 公开 API 策略：哪些包下所有导出符号都按保留处理。
如果工具本身没有专门参数，也要在仓库里建立一个deadcode.ignore或者白名单文件，把不应该判死的包路径写进去。这个文件的价值会在第一次误报后体现得很明显。
3.2 第二步：按包依赖和调用链做可达性标记
入口定义清楚后，分析器会做两件事：构建包依赖图，然后沿着调用链做可达性标记。
这个过程的原理可以理解成图搜索：
- 从每个入口函数开始，把入口直接调用的函数加入“已访问”集合；
- 递归分析这些函数内部的调用关系；
- 跨包调用时，进入对应包的函数继续展开；
- 遇到接口方法调用、反射调用、go 语句、defer 等特殊结构时，采用保守策略；
- 最终没有被访问到的函数，进入候选死代码列表。
伪代码大致是这样的：
def mark_reachable(entries): visited = set() worklist = list(entries) while worklist: func = worklist.pop() if func in visited: continue visited.add(func) for callee in resolve_calls(func): if callee not in visited: worklist.append(callee) return visited这段逻辑不复杂，难点在于resolve_calls怎么处理间接调用。直接函数调用好办，接口方法调用需要找到所有实现该接口的类型；反射调用在静态分析里基本无法准确求解，只能靠过滤和配置处理。
这就是为什么 Deadmono 这类工具在 monorepo 里需要“整个仓库一起分析”。如果只看单个模块，跨模块调用链会断掉，接口实现类也无法完整枚举。
分析完成后，死代码候选通常是按包分组的。每个候选会包含包路径、函数名、所在文件、行号这些基础信息。有些工具还会输出“为什么不可达”，也就是缺少哪条调用链能到达它。
3.3 第三步：输出报告时一定要带包路径、函数名、引用来源
死代码清单有用没用，关键在于信息是否完整。
我见过有些工具只输出一行函数签名，删代码时完全没法定位，最后还是要靠grep重新找。一个好的报告至少应该包含这些字段：
| 字段 | 作用 |
|---|---|
| 包路径 | 定位到具体模块 |
| 函数/类型/方法名 | 明确符号 |
| 文件路径和行号 | 方便直接跳转 |
| 符号类别 | 函数、方法、变量、类型、常量 |
| 候选死代码原因 | 不可达、未使用、被排除入口 |
| 是否导出 | 判断是否参与公开 API 保留策略 |
拿到报告后，不要急着批量删除。先按“导出/未导出”分类，再按包维度统计。未导出的私有函数通常是安全候选；导出的函数和方法需要再对照入口策略判断。
如果工具支持，建议把报告导出成 JSON 或者结构化文本，方便后续用脚本按模块拆分，分发到不同负责人手里。CSV 也可以，但字段一多容易乱；JSON 更适合做增量比较和 CI 集成。
4. 结果里哪些是真死代码，哪些是误报
4.1 从“不可达”到“可删除”还需要判断条件
分析结果给出的是“不可达”，不等于“可以删”。中间还隔着一层业务判断。
我认为可以进入删除候选的代码，至少满足下面几个条件：
- 代码从入口不可达，且不是公开导出 API；
- 搜索整个仓库（包括测试文件）没有字符串、配置、反射方式引用；
- 不在生成代码目录里，或者生成后确实没被任何入口使用；
- 没有在文档、示例、注释中作为对外使用方式被推荐；
- 不是通过插件机制、动态链接、外部进程间接调用。
这些条件里，前三个可以用脚本自动化检查，后两个需要人工判断。Deadmono 能做的是把“不可达候选”过滤出来，但最终确认删除，仍然需要至少一次人工复核。
我一般会建议团队把死代码清单分三个等级：
- 高置信度：未导出、无引用、无配置引用、不在生成目录，可以直接提交删除；
- 中置信度：导出的函数但仓库内无调用，需要确认是否对外发布；
- 低置信度：涉及反射、动态注册、代码生成、跨仓库依赖，不建议直接删除。
低置信度这部分不是工具误报，而是静态分析本身的边界。任何工具都绕不开反射调用和动态加载的取模问题。
4.2 反射、序列化、动态加载是最常见的误报来源
Go 的静态分析在遇到界面反射时，基本只能靠猜。好在仓库里的反射场景大多数有规律可循。
我统计过自己维护的仓库，误报主要集中在三类模式：
第一类，reflect.TypeOf或reflect.ValueOf触发的反射调用。某个结构体可能只被反射代码读取，静态调用图上完全看不到引用。处理方式是把实现某个接口注册方法、被反射操作的目标类型，加入白名单。
第二类，JSON/序列化相关的类型定义。很多 DTO 类型只是被encoding/json反序列化使用，需要满足字段名和小写字段的匹配。它不需要有明确的构造函数，却不能被删除。处理方式是所有实现了MarshalJSON、UnmarshalJSON、json.Marshaler、json.Unmarshaler接口的类型，默认保留。
第三类，代码生成器输出。protoc-gen-go生成的*.pb.go、gqlgen 生成的*.generated.go，从 main 入口分析时可能找不到调用方，但它们会被其他代码 import。如果工具没做生成文件过滤，这些文件会大面积进入死代码清单。
处理这三类误报的经验是：先跑一次分析，把报告按文件目录过滤掉生成目录，再按接口注册方法排除反射场景，最后看剩余清单。大部分高置信度死代码会集中在这时暴露出来。
4.3 测试代码和生成代码要不要一起清理
测试代码要单独看待。
_test.go文件里的函数、类型、变量，通常不参与主二进制构建。有些工具默认不分析测试代码，这会漏掉一种情况：测试文件引用了某个生产代码函数，但生产代码函数没有其他调用者。这种函数从生产入口看是死代码，从测试入口看是活代码。
我的处理建议是：默认把测试文件加入分析范围，但独立统计。当一个函数只被测试引用，其他生产代码都不用时，它仍然有删除价值，只是需要同时清理测试文件和待删除函数，不能只删一边。
生成代码则相反。无论有没有被入口引用，都不建议完全交给静态分析判断。因为生成代码会随上游定义变化而重新生成，手动删除后下一次生成又会回来。正确做法是把生成目录加入忽略列表，除非你确定生成配置已经停止输出该文件。
5. 大规模仓库落地：分批执行、缓存、CI 接入
5.1 不要一次扫描整个仓库
规模越大，越要克制“全仓分析”的冲动。全仓分析问题很多：耗时长、内存大、误报多、结果难消化。
我建议从三个维度拆分。
按模块拆分：先跑一个业务模块，比如./module-a，观察输出数量和误报类型，确认配置没问题后再扩大范围。
按入口类型拆分：第一轮只分析 cmd 二进制入口，把最基础的死代码找出来；第二轮加入服务注册入口；第三轮再加入公开 API 白名单。每一轮都是对配置的校准。
按报告置信度拆分：处理报告时先处理高置信度清单，不要在低置信度清单上花大量时间。
分批执行的核心目标，是让每一次分析结果都可控。全仓几千个候选死代码一次性抛出来，团队根本没法处理，最后结果就是没人管，下次再跑一次又重复一遍。
5.2 增量分析和 CI 门禁怎么设计
CI 接入死代码检测，最有价值的位置是合并请求检查，而不是定时全量扫描。
全量扫描适合每周或每月跑一次，输出趋势报告。合并请求检查适合只报告本次改动引入的死代码。如果每次提交都跑全量分析，几千个包跑下来，开发者等结果的时间比写代码还长。
增量检查的思路是这样的：
- 对比分支和目标分支的代码差异；
- 只分析有改动的包及其依赖范围；
- 跑完分析后，把新增的死代码候选过滤出来；
- 如果新增候选数量超过阈值，则 CI 失败。
这个方案需要一个额外能力：能够缓存之前的分析结果。否则每次 PR 都从零开始分析，还是慢。缓存粒度可以到包级别，包没变就直接读取上一次结果。
CI 门禁我不建议直接设成“0 死代码”，那样历史存量会阻塞所有新代码提交。更合理的配置是：
- 历史死代码候选全部记录，但不在 PR 中强制处理；
- 新增死代码候选数量超过 0 或某个小阈值时，CI 失败；
- 定期任务扫描全仓，把新增量同步到负责人。
这样团队既能逐步清理存量，又不会因为历史问题卡住日常开发。
5.3 清理动作要配合提交历史和责任人
死代码清单真正落地到删除，需要配合仓库的提交历史。
我推荐三种辅助信息：
第一，最后修改时间。如果一个函数已经被判断为死代码，同时在 git 记录里好几个版本没有变动过，删除风险相对低。如果最近一次提交就在一两个版本前，需要多问一句“是不是正在被改造”。
第二，代码负责人。按 git blame 或者 CODEOWNERS 文件把清单分给对应负责人。很多人看到“全仓库死代码”不觉得与自己有关，按目录拆分后，责任人明确，推动起来容易很多。
第三，删除方式。不要一次性把所有候选代码删干净。先按模块提交删除，跑一遍测试和构建，再继续下一批。这样可以快速定位某个删除是否破坏了隐藏依赖。
实际操作里，我经常用三步删除法：
- 先给候选函数加
// Deprecated: 待确认注释，合入后观察一两个版本周期； - 确认没有反馈和构建问题后，再真正删除；
- 删除后跑一次静态分析，确认清单里对应项消失。
这个方法比“当天扫描、当天删除”稳妥得多，尤其适合团队成员多、代码归属不清晰的大仓库。
6. 我建议的落地顺序和几个真实坑点
6.1 从新的或小规模服务开始
第一次使用 Deadmono 时，建议选仓库里最独立的服务或模块作为试点。这个模块最好满足三个条件：
- 模块数量少，依赖关系简单；
- 有明确的 main 入口，不用处理大量 library 包；
- 最近刚做过重构，代码里有较多迁移后残留下来的旧函数。
这类模块的分析结果最容易验证。删掉一批函数后，构建、测试、运行都很快反馈，能够快速建立对工具的信任。
不要一上来就在最核心的业务模块上跑。核心模块包多、依赖复杂、反射和生成的代码也多，跑出来的低置信度候选大量堆积，反而很难评估工具到底有没有用。
6.2 先处理 cmd 下的单个二进制入口
试点模块里，我一般会优先看cmd目录下的独立二进制入口。
原因是这类入口最接近“程序真实启动点”，从它分析出去的调用链最可信。而且删除cmd内部未被调用的私有函数，基本不会影响对外 API。
具体做法是：
- 先扫描
cmd/xxx主包及其依赖包； - 只保留主包内部未导出且无引用的函数作为清理目标；
- 删除后运行
go build ./cmd/xxx和该服务的测试； - 结果稳定后再扩展到其他 cmd 目录。
这块跑顺之后，再考虑 library 包的导出符号，处理逻辑完全不同。
6.3 别把误报处理成“删掉再恢复”
处理误报时，最容易犯的错误是“先删掉试试，不行再恢复”。
在 monorepo 里，这个思路会带来两个问题：
一是删除代码会影响多个模块的构建。提交 A 删除了函数，提交 B 因为缺少依赖而编译失败，中间可能牵连一批开发和发布任务。
二是恢复困难。函数删掉后，如果没有人注意到依赖它的代码，可能过了一两个月才被发现。此时 git 历史已经被大量提交推远，恢复成本比当时高得多。
更合理的做法是：先用白名单方式把误报排除。每次确认一个新的误报场景，就把“为什么会被误判”记录下来。比如：
internal/kafka包下的所有类型，因为会被消息反序列化使用；internal/proto包下所有生成文件，忽略扫描；- 实现了
cobra.Command的RunE方法的函数，全部标记为入口。
这些规则积累到一定程度，工具输出质量会明显提升。之后再出现的新误报，往往是仓库引入了新的反射模式或生成工具，这时去补规则就行。
死代码清理不是一次性的“大扫除”，更像是对代码库做持续维护。工具能做的，是把原本靠人肉搜索和猜疑链完成的工作变成可重复的检查项。真正让清理动作安全落地的，还是入口定义、误报规则和分批删改这三件事。
如果你准备在团队里引入类似方案，我建议先从一个小模块开始，跑出第一份报告，然后花一两个迭代周期校准规则。等规则稳定了，再逐步覆盖到整个 monorepo。这样整个过程风险可控，结果也能真正沉淀进 CI。
