Go -race 在 CI 中分层运行的资源配置

把 -race 直接塞进 CI 的每一个测试作业，通常会得到两个问题：反馈变慢，失败原因变得模糊。更稳妥的做法是把竞态检测当成一种高成本的架构能力，按检测范围和资源压力分层安排。

这篇只讨论 CI 中的检测范围、耗时与不确定失败。建议保留普通测试作为快速反馈，再把并发重点包、全量竞态和长链路测试放到不同资源预算的作业里。这样既不会因为资源紧张掩盖真正的竞态，也不会把所有提交都绑定到最重的检查。

官方资料：https://go.dev/doc/articles/race_detector

命令参考：https://pkg.go.dev/cmd/go

先把 -race 看成一种高成本检测能力

-race 不是“把普通测试再跑一遍”的轻量开关。Go 会为内存访问加入检测，并由运行时观察并发访问；它只能发现实际执行路径上被触发的竞态。官方文档给出的典型范围是：内存可能增加约 5–10 倍，执行时间可能增加约 2–20 倍，具体数字取决于程序和测试。

因此，CI 里有两个必须分开的问题：

• 检测范围：哪些包、哪些测试和哪些工作负载有机会触发共享状态访问。
• 资源预算：这些测试在带检测插桩后，允许使用多少构建并行度、测试并行度和 runner 内存。

如果只调整第二项而不考虑第一项，作业可能只是更慢；如果只扩大 runner 而不限制并行度，多个带检测的测试进程仍可能同时争抢内存。

先把 CI 拆成不同压力层

一个可维护的分层方案不依赖某一家 CI 平台，核心是让每层拥有清楚的职责。下面的层次不是固定的时间顺序，而是四种可以独立配置的作业画像。

这里的关键不是“每层都必须存在”，而是不要让一条作业同时承担快速反馈、全仓库编译、竞态插桩和长链路依赖。作业职责越混杂，资源型失败越难解释。

用 -p 和 -parallel 控制两种不同并行度

最容易混淆的是 -p 和 -parallel。前者属于 go 命令的构建并行度，影响同时构建多少个包；后者是测试二进制的测试并行度，主要影响通过 t.Parallel() 声明可并行的测试。它们都不能替代对业务 goroutine 的设计，也不能把竞态检测变成确定性证明。

# 并发重点包使用较小的构建和测试并行度，降低瞬时内存峰值
go test -race -count=1 -p 2 -parallel 2 ./internal/worker/...

# 全量竞态作业可以提高并行度，但应根据 runner 预算逐步调大
go test -race -count=1 -p 4 -parallel 4 ./...

-count=1 用来显式关闭成功测试结果的缓存，适合希望每次都实际运行的竞态作业。它不会减少竞态检测的开销，却能避免把“缓存命中很快”误判成一次新的覆盖。

如果 runner 只有少量 CPU 或内存，先降低 -p 和 -parallel，再考虑换更大的 runner。盲目把两个数字同时调高，会让带插桩的测试进程叠加，最后表现为超时、被系统杀死或构建阶段内存不足。

把 Go 运行时并发预算单独写出来

GOMAXPROCS 解决的是单个 Go 进程可以使用的逻辑处理器预算，它和包构建并行度、测试并行度不是同一层控制。对于资源紧张但仍希望保留 -race 的作业，可以先给运行时一个明确上限，再观察作业是否稳定。

# 只限制这个竞态作业里的 Go 运行时并发，不改变仓库代码
GOMAXPROCS=2 go test -race -count=1 -p 2 -parallel 2 ./...

# 先确认竞态检测的目标平台和 cgo 状态，避免把环境不支持误判成代码失败
go env GOOS GOARCH CGO_ENABLED

官方要求竞态检测在支持的平台上运行；非 Darwin 系统通常还需要启用 cgo 并准备 C 编译器。这个检查属于作业环境契约，不是给每个测试增加一个业务断言。

不要用扩大 runner 掩盖覆盖不足

竞态检测的一个边界是：它只报告运行时真正走到的并发访问。全量包测试仍然可能漏掉需要特定请求顺序、特定负载或长生命周期 goroutine 才会出现的问题。扩大内存只能解决“作业装不下”的问题，不能让未执行的代码路径突然被覆盖。

因此，资源层和覆盖层应分别讨论：

• 资源层关注作业能否稳定完成：CPU、内存、构建并行、测试并行和超时。
• 覆盖层关注是否触发关键共享状态：并发请求、取消、重试、队列堆积和长生命周期任务。
• 若某个集成场景很有价值，就把它放进长链路层，而不是仅仅把全量单元测试的机器规格继续加大。

也不要用 -race 作业的耗时直接替代普通测试的性能基线。插桩改变了运行时成本，竞态报告的目标是找共享状态访问问题，而不是给业务吞吐量做最终结论。

从日志证据区分真实竞态和资源型失败

当 CI 失败且没有立刻得到清晰结论时，可以先按日志证据分层。真实数据竞态通常会出现 WARNING: DATA RACE，并给出冲突访问及 goroutine 创建位置；这类失败应回到共享状态、同步方式和测试覆盖上处理。

另一类失败没有竞态报告，而是出现进程被杀死、内存不足、超时或 cgo/编译器不可用。这时不要直接把失败归咎于测试不稳定，可以保留原始日志，把作业迁移到更合适的资源画像，或先降低并行预算。

# 保存一次竞态作业的原始输出，便于按证据分类失败
set -o pipefail
go test -race -count=1 -p 2 -parallel 2 ./... 2>&1 | tee race.log

# 只有出现官方竞态报告标记时，才把它归入代码竞态处理路径
if grep -q "WARNING: DATA RACE" race.log; then
  echo "发现数据竞态：回到共享状态与同步关系排查"
else
  echo "未发现竞态报告：继续检查资源、超时、平台和覆盖范围"
fi

这段命令只是日志分流示例，不能证明“没有标记就没有竞态”。测试可能没有覆盖到触发路径，也可能因为资源失败而没能跑到相关代码。

几个看似合理但代价很高的做法

所有提交都对整个仓库开启 -race

这样规则简单，但把高成本检查绑定到了每一次最短反馈上。更好的折中是：PR 上保留并发重点层，合并或定时作业运行全量竞态层；如果仓库很小，再逐步合并两层。

只调大机器，不调小并行度

更大 runner 能缓解单进程资源不足，却不能阻止多个测试进程同时峰值。先为 -p、-parallel 和 GOMAXPROCS 写出可解释的预算，再按趋势调整机器规格。

竞态失败自动重跑直到通过

竞态本来就可能受调度影响，但自动重跑会把真实问题包装成偶发失败。可以把重跑用于确认资源型失败是否恢复，却不要用它替代对竞态报告的处理。

最后用一张清单判断分层是否合理

• 普通测试是否仍能在短时间内反馈编译与基础回归？
• 并发重点包是否有独立的 -race 作业，而不是依赖全量作业碰运气？
• -p 是否控制了构建并行，-parallel 是否控制了可并行测试？
• runner 的 CPU、内存和超时预算是否与插桩后的成本匹配？
• 失败日志能否区分 WARNING: DATA RACE、资源终止、超时和环境不支持？
• 关键长链路是否真的被执行，而不是只扩大普通单元测试的机器规格？

把 -race 分层运行，本质上是在检测价值和资源成本之间做明确取舍。快速层负责反馈，并发重点层负责高价值路径，全量层负责扩大覆盖，长链路层负责触发单元测试难以触发的共享状态。只要每层的范围、并行度和失败证据都写清楚，CI 就不必在“完全不开”与“全部开启”之间二选一。

相关问题

-race 能证明代码没有数据竞态吗？

不能。它只报告运行时执行到的竞态，测试覆盖不足时仍可能漏报。

-p 和 -parallel 可以只保留一个吗？

不建议混用概念。它们分别约束构建包并行度和测试内部可并行测试数量，资源紧张时通常需要分别设定。

为什么本地通过，CI 的 -race 才失败？

CI 可能使用了不同平台、cgo 工具链、调度压力或测试顺序。先看竞态报告是否存在，再区分环境与资源因素。