Go build tags 测试文件专用标签怎么组织

Go 项目里最稳妥的做法是：普通单元测试直接放在 *_test.go 文件中；需要数据库、消息队列或外部网络的测试，单独放进同样以 _test.go 结尾、但带 //go:build integration 的文件。日常执行 go test ./... 时不带集成标签，只有明确执行 go test -tags=integration ./... 才把这类测试加入测试集合。

不要把“测试文件专用标签”理解成 Go 会自动提供一个 test 标签。_test.go 负责让文件只参与测试构建，integration 等自定义标签负责表达额外依赖，两者是两层不同的筛选条件。

先按依赖边界拆分单元测试和集成测试

判断一个测试是否需要专用标签，不要先看测试函数名字，而要看它是否依赖当前进程以外的资源。纯函数、内存仓储、固定输入输出的测试可以每次运行；真实数据库、容器、消息队列、第三方 HTTP 服务则应放到独立的集成集合。

例如，目录可以保持简单：

store.go
store_unit_test.go
store_integration_test.go

这三个文件都属于同一个 Go 包，但最后一个文件只在满足 integration 时参与测试。文件名中的 _test.go 已经说明它不是生产构建的一部分；不要再为“测试文件”虚构一个自动标签。

在测试文件顶部声明一个明确的 build tag

集成测试文件可以这样写。标签必须出现在文件前部、package 之前，并用空行与包声明隔开：

//go:build integration

package store_test

import (
	"testing"
)

func TestStoreAgainstDatabase(t *testing.T) {
	// 这里的测试需要外部数据库，默认 go test 不会选中本文件。
	if err := pingDatabaseForTest(); err != nil {
		t.Fatalf("测试数据库不可用: %v", err)
	}
}

//go:build integration 是一个布尔表达式，后续也可以扩展成 integration && postgres。但标签越多，CI 组合越容易失控，所以建议先用一个能说明依赖边界的词。若项目还维护很老的 Go 工具链，可让 gofmt 维护对应的旧式 // +build 行，不要手工写出互相矛盾的两套表达式。

给默认测试和集成测试分别设计命令

默认命令应该不需要启动数据库，也不应该因为网络抖动变红：

# 先跑不依赖外部服务的快速测试
go test ./...

# CI 的集成阶段显式打开 integration 标签
go test -tags=integration ./...

# 只定位集成测试，减少排查时的噪声
go test -tags=integration -run '^TestStoreAgainstDatabase$' ./...

这里的 -tags=integration 只是告诉 Go 这个标签在当前构建中成立，并不会替你创建数据库、填充表数据或清理队列。集成阶段仍然要在 CI 前置步骤准备依赖，测试函数也要负责明确的资源清理。

用 go list 和命名约定排查标签误用

当你怀疑标签没有生效时，先观察 Go 实际识别到的测试文件，不要只凭终端输出猜测。可以查看默认集合与 integration 集合的差异：

# 查看带 integration 标签时的文件集合
go list -tags=integration -json ./... > package-list.json

# 过滤出测试文件名，便于确认专用文件是否被纳入
grep -E 'TestGoFiles|XTestGoFiles' package-list.json

检查时重点看三件事：标签是否写在文件顶部；文件是否真的以 _test.go 结尾；CI 是否使用了和文件相同的标签名。test、tests、integration 不是等价词，命令里的一个拼写差异就会让测试悄悄缺席。

把标签规则写进 CI 和测试说明

建议把测试分成两个显式阶段：提交检查只执行 go test ./...，定时或合并前流水线再准备依赖并执行 go test -tags=integration ./...。如果集成测试需要凭据、端口或临时表，把这些前置条件写在 CI 配置附近，并在失败时打印“依赖未就绪”与“断言失败”的区别。

不要用一个巨大的标签表达所有环境。数据库集成、消息队列集成和端到端测试可以分别使用 integration、mq、e2e，但只有在确实需要独立调度时才拆分。标签的价值不是增加开关，而是让测试集合和运行成本一眼可见。

常见问题

为什么写了 //go:build test，普通 go test 还是不执行？

因为 test 不会被 go test 自动设置。只有命令显式加上 -tags=test，这个文件才满足标签；但更建议使用能表达真实依赖的 integration 或 e2e。

集成测试必须改成另一个 Go 包吗？

不必须。只要导入边界和测试目标允许，它可以继续使用当前包或使用 package store_test 的黑盒形式。是否拆包是可见性和架构选择，不是 build tag 的要求。

文件名已经是 integration_test.go，还需要标签吗？

需要时仍然需要。文件名中的 _test.go 只表示它属于测试文件；integration 标签才表示“默认测试集合之外的依赖边界”。

最后可以把规则压缩成一句团队约定：_test.go 决定“只在测试时编译”，integration 或 e2e 决定“什么时候才把这组测试纳入集合”。命令和文件标签保持同名，默认测试就能保持快而稳定。