go test 覆盖率数据合并与包级报告生成方法

Go 覆盖率汇总应先区分两种情况：同一次 go test ./... 可以直接通过 -coverprofile 输出聚合文本文件；多次分片执行需要合并时，可保留二进制覆盖数据目录，用 go tool covdata merge 合并，再以 covdata percent 生成包级百分比，或转成文本后生成 HTML。不要对多个覆盖率百分比取平均，也不要把文本文件直接当作 covdata 输入。

规模背景：多包测试和多次执行不是一回事

小型项目只需一次测试进程调度，命令完成后就能得到覆盖文件。随着测试拆成不同场景、不同执行节点或独立批次，同一段代码可能在多个分片中重复出现，也可能仅被其中一个分片覆盖。这时，汇总对象必须是语句块的覆盖数据，而不是屏幕上显示的几条百分比。

先看单次多包测试的最小写法。这里的包集合、构建标签和环境应由项目定义；示例在当前模块根目录执行，atomic 用于需要正确处理并发计数的情况。它会增加计数开销，不是任何项目都必须采用的默认配置。

# 在模块根目录执行；单次测试可直接由 go test 汇总多个包。
go test -count=1 -covermode=atomic -coverpkg=./... -coverprofile=coverage.out ./...
# 该命令输出函数及总语句覆盖率，不是逐包百分比表。
go tool cover -func=coverage.out
# 生成独立 HTML 文件，不启动浏览器。
go tool cover -html=coverage.out -o=coverage.html

这条命令已经负责本次调用中各测试包的覆盖率文本汇总，不需要再把每个包的文件手工拼起来。若只是希望全项目生成一份 HTML，这通常就是更短的路径；本文后面的合并方案针对多次执行，而不是为了复杂而额外拆步骤。

原架构瓶颈：拼接文本与平均百分比都不可靠

coverage.out 开头包含 mode，后面是文件位置、语句数和计数。简单 cat 会重复头部；即使删掉重复头部，仍可能留下相同语句块的重复记录，没有表达正确的计数合并规则。对不一致的源代码版本做文本拼接，风险更大。

百分比也不能相加或简单平均。一个含 10 条语句的包与一个含 1000 条语句的包，不能各占一半权重；两个分片覆盖同一块代码时，覆盖语句并集也不是两个百分比之和。应先按元数据合并记录，再让工具计算报告。

covdata 读取的是 covmeta 与 covcounters 组成的数据目录，不会解析传统文本 coverage.out。已有文本资料不能仅靠修改扩展名“变成二进制数据”。如果能够重新采集，统一采集契约通常更可靠；已有历史文本需要专门理解该格式的处理逻辑，不能把 merge 命令当作通用文件拼接器。

新架构：保留二进制覆盖数据再生成报告

Go 1.20 引入的二进制覆盖数据工具链提供了官方合并入口。下面给出单个测试包的分片样例：先用 go test -c 编译带覆盖插桩的测试二进制，再用测试二进制的 -test.gocoverdir 参数将中间数据写入两个独立目录。这个参数属于测试程序侧，不能把集成测试中的 GOCOVERDIR 用法不加区分地照搬到普通 go test 命令上。

# POSIX shell 示例：从模块根目录启动，遇到失败立即停止。
set -eu
# 每轮使用新的绝对目录，避免读到上次运行的数据。
cov_run=$(mktemp -d)
mkdir -p "$cov_run/a" "$cov_run/b" "$cov_run/merged"
# 示例包为 internal/order；替换为实际存在且有测试的包。
go test -c -covermode=atomic -coverpkg=./... -o "$cov_run/order.test" ./internal/order
# 直接运行测试二进制时，进入原包目录以保持相对测试资源的读取习惯。
(
    cd ./internal/order
    # 示例 TestCreate 与 TestCancel 必须替换为实际分片规则。
    "$cov_run/order.test" -test.run='^TestCreate' -test.count=1 -test.timeout=2m -test.gocoverdir="$cov_run/a"
    "$cov_run/order.test" -test.run='^TestCancel' -test.count=1 -test.timeout=2m -test.gocoverdir="$cov_run/b"
)
# 输入是二进制覆盖数据目录，不是 coverage.out 文本。
go tool covdata merge -i="$cov_run/a,$cov_run/b" -o="$cov_run/merged"
# 生成逐包语句覆盖率；不对分片百分比取平均。
go tool covdata percent -i="$cov_run/merged" > "$cov_run/packages.txt"
# 生成函数级报告，保留与包级报告不同的维度。
go tool covdata func -i="$cov_run/merged" > "$cov_run/functions.txt"
# 转成传统文本格式后，再交给 cover 生成源码标注页面。
go tool covdata textfmt -i="$cov_run/merged" -o="$cov_run/coverage.out"
go tool cover -html="$cov_run/coverage.out" -o="$cov_run/coverage.html"
# 保留路径供后续上传构件；本例不自动删除结果。
printf '覆盖率资料目录：%s\n' "$cov_run"

这是命令方案，本文没有运行测试、生成报告或声称取得某个覆盖率。internal/order、TestCreate 和 TestCancel 是明确的示例名称，需要替换为项目实际的包与规则。分片规则应共同覆盖预定测试集；没有选中任何测试，也可能不会以失败退出，不能把退出码 0 等同于“所有目标测试均已执行”。

编译一次再运行同一个二进制，减少了这两个分片的插桩结构差异。直接运行测试程序时，需要带 -test. 前缀，也需要自己维护工作目录和超时。示例进入包目录以兼容相对 testdata 读取习惯；多包项目应为各包生成独立测试二进制与采集目录，再把完成的目录作为合并输入。

关键取舍：覆盖范围比一个总百分比更重要

-coverpkg=./... 指定候选插桩包范围，但并不保证每个包都被某个测试二进制实际链接、采集或执行。本文的单包示例不能代替全模块测试覆盖。若全项目报告需要包含所有目标包，应记录期望包清单，并确保这些包由相应测试或应用二进制纳入采集，而不是只看一个较高的百分比。

合并前应保持同一代码快照、工具链和覆盖模式，记录 GOOS、GOARCH、构建标签等条件。不同平台的资料可以按明确目的形成联合覆盖视角，但它不等于任一单平台都达到同样覆盖率。不要把不同提交、不同产品分支或不兼容插桩范围的资料无解释地混成发布指标。

包级报告用 covdata percent；函数维度用 covdata func；HTML 用 textfmt 加 go tool cover。go tool cover -func 里的 total 是语句加权后的汇总，不是包级表。需要只观察某些包时，可以使用 covdata 的 -pkg 过滤，但过滤会改变观察范围，应同时保存过滤条件。

分片重复运行会影响 count 或 atomic 的计数总量，因此执行次数不宜直接当成真实业务访问次数。若目标只是“哪些语句至少执行过”，主要关注覆盖集合；计数分析还需要清楚重复执行与合并的来源。

上线结果：应观察哪些变化

这套方案上线后，首先应观察报告是否包含预期包、每个分片是否成功交付数据、源码标注是否指向本次提交，以及报告范围是否与此前一致。这些是读者落地时的观察项目，不是本文已经完成的运行结论。

若合并后覆盖率下降，不应立即归因于测试退化。先看分母是否扩大、此前缺失的包是否被纳入、构建标签是否变化，以及某个分片是否缺失。反过来，报告变高也可能只是遗漏了低覆盖包。覆盖率需要与采集范围一起解读。

输入目录应按运行批次隔离，不能让旧构件静默留在本轮目录中。示例使用 mktemp 创建新的绝对目录；在 CI 中，可以将同样的归属信息写入构件路径和元数据，并等待所有必要分片完成后再汇总。合并成功仅说明数据处理完成，不会替代各分片测试结果的失败判定。

后续改进与常见问题

保留原始分片数据、合并数据、包级报告和生成时的构建条件，能够让后续排查解释“数字为何变化”。测试失败时先保留失败状态，即使仍有覆盖数据，也应将报告标为不完整；不要靠生成 HTML 掩盖失败的测试任务。

可不可以直接把两个 coverage.out 传给 merge？不可以。merge 的输入是覆盖数据目录；textfmt 的方向是二进制数据转传统文本，不是传统文本反向导入。

单次 go test ./... 还需要 covdata 吗？只生成一份传统覆盖文件时通常不需要。多次执行、分片汇总或需要二进制资料的包级报表时，再采用相应采集方案。

为什么包级报告没有某个包？可能未插桩、未链接进执行对象、没有生成对应资料或被过滤。应结合预期包集合和构建条件检查，不能把缺失行直接解释成零覆盖或满覆盖。

官方资料：https://go.dev/doc/build-cover、https://pkg.go.dev/cmd/covdata、https://pkg.go.dev/cmd/go、https://go.dev/src/testing/testing.go。