Go coverprofile 按包查看覆盖盲区

我第一次把一个 Go 模块的覆盖率接到持续集成时，最容易误读的不是命令，而是“这个百分比到底覆盖了谁”。go test -cover ./... 给的是按测试包展开的摘要；-coverprofile 保存的是可继续分析的语句执行记录。两者都叫覆盖率，但统计边界不同。本文只围绕生成、过滤和解释 coverprofile，帮助你按包找到真正没有测试触达的区域。

官方地址：https://pkg.go.dev/cmd/go

先确认：覆盖率数字不是模块总分

Go 官方把覆盖分析拆成两件事：测试阶段通过 go test -coverprofile=... 生成 profile，分析阶段再用 go tool cover 读取它。默认情况下，测试某个包时只统计该测试包本身；如果想让测试覆盖匹配到的多个包，就要显式指定 -coverpkg。

这形成了一个很实用的判断模式：先用摘要找包，再用 profile 找函数，最后回到代码分支判断测试是否真的缺场景。如果只看 CI 最后一行总百分比，很容易把一个测试充分的工具包和一个完全没有触达的业务包平均在一起。

按包查看：先用摘要建立基线

我通常先不生成 HTML，而是运行最短的包级摘要。它适合回答“哪个包的语句覆盖率明显偏低”，也能把没有测试文件或覆盖率为零的包尽早暴露出来。

# 对模块内匹配到的包逐个运行测试，并打印每包覆盖率摘要
go test -cover ./...

# 只查看某个业务包，缩小排查范围
go test -cover ./internal/order

这里的 ./... 是包选择范围，不等于“所有包都被同一组测试完整覆盖”。每个测试包仍按自己的测试二进制运行，摘要里的百分比通常表示该测试包被执行到的语句比例。出现一个低值时，先记录包路径，再决定是否需要保存 profile。

如果包级摘要全部看起来正常，但某个行为仍没有信心，就不要继续把命令换成更长的参数堆。下一步应该保存 profile，因为它能把“低覆盖”落到文件、函数和语句区间。

保存 coverprofile：从包摘要落到函数

-coverprofile 会把覆盖数据写入指定文件；测试失败时不要把不完整的结果当成正式报告。保存之后先用函数汇总，输出比 HTML 更适合放在日志或代码评审里。

# 测试通过后写入可复用的覆盖 profile
go test -coverprofile=coverage.out ./internal/order

# 按文件和函数查看语句覆盖率，最后一行给出总计
go tool cover -func=coverage.out

# 需要逐行查看热区时生成 HTML 报告
go tool cover -html=coverage.out -o coverage.html

读函数汇总时，我会优先看三类位置：覆盖率为零的函数、覆盖率明显低于同包平均值的函数，以及错误处理和边界分支集中出现的函数。百分比只说明被统计的语句执行情况，不等价于分支、输入组合或业务风险已经覆盖。

跨包统计：什么时候应该写 -coverpkg

一个常见反例是：internal/order 的测试调用了 internal/money，但报告只显示订单包的覆盖率，于是团队以为金额包已经被统计。默认口径并不会自动把所有被调用包都纳入覆盖分析。要研究某个测试入口对一组包的触达范围，应显式写出 -coverpkg。

# 让订单测试按模块内包模式统计被覆盖的目标包
# ./... 是匹配范围，实际项目也可以换成更窄的包模式
go test -coverpkg=./... -coverprofile=order-all-packages.out ./internal/order

# 查看该测试入口对应的函数覆盖明细
go tool cover -func=order-all-packages.out

这个命令回答的是“订单测试入口触达了哪些目标包”，不是“每个包都拥有独立完整的测试套件”。如果要比较每个包自己的单元测试，仍应分别运行 go test -cover ./... 或对目标包逐个保存 profile。两种报告同时存在时，文件名要体现测试入口和统计口径，避免把跨包报告当成包自身报告。

-coverpkg 也不应被当作提高数字的开关。它扩大的是统计对象；扩大后总百分比下降，往往只是把之前没有被纳入的代码诚实地显示出来。

反例：把一个数字当作测试设计的终点

我见过一种看似积极的做法：CI 只保留总覆盖率，低于阈值就失败；为了过线，开发者给简单 getter 增加测试，却没有为解析失败、空输入、超时和权限拒绝补场景。结果数字更漂亮，真正的盲区仍在。

更稳妥的做法是把 profile 当作导航图。先按包排序，再进入低覆盖函数，最后列出函数的输入类别和错误返回。对于一条复杂条件，覆盖率工具的语句粒度也可能掩盖逻辑组合；不要因为一行被执行就断言所有条件都被验证。

• 包级摘要用于发现范围异常。
• 函数汇总用于定位候选盲区。
• HTML 用于回看具体语句位置。
• 测试用例清单才负责确认正常、边界和失败路径。

我的判断清单：报告应该服务于取舍

最后我会把一次覆盖率分析收敛成几项可复查的问题：这个百分比对应哪个测试入口？profile 是否只包含预期包？低覆盖函数是否承担错误处理或数据边界？跨包报告和包自身报告有没有混用？新增测试是补了真实场景，还是只执行了一次无意义的直通路径？

如果目标是按包查看盲区，推荐保留两种产物：日常 CI 的 go test -cover ./... 包级摘要，以及针对重点入口生成的带名字 profile。前者让问题可排序，后者让问题可定位。覆盖率不替你决定测试优先级，但能把“我觉得这里没测到”变成一张可讨论的地图。

相关资料（复制地址查看）：Go 命令文档 https://pkg.go.dev/cmd/go；Go 覆盖率官方说明 https://go.dev/doc/build-cover；cover 工具说明 https://pkg.go.dev/cmd/cover。

常见问题

为什么 go test -cover ./... 和 profile 的总数不一样？通常是测试入口、包范围或是否使用 -coverpkg 不同，先对齐命令口径再比较。

覆盖率高是不是代表分支都测到了？不是。它主要反映被统计语句的执行情况，仍需为条件组合和错误路径设计测试。

应该优先看包覆盖率还是函数覆盖率？先用包摘要排序范围，再用函数汇总和 HTML 定位，最后回到业务场景判断优先级。