Go模块内部测试规范与internal目录使用指南

Go模块中internal包的测试需遵循导入规则：internal仅限父级及子级目录导入，测试文件须与被测代码同目录同包，确保访问私有标识符；跨包测试可建测试桥接包，且应在模块根目录执行测试命令以正确解析路径。

Go 模块要支持内部测试，关键在于正确组织 internal 包和测试代码的位置，并遵守 Go 的导入可见性规则。核心原则是：internal 包只能被其父目录或同级子目录中“能直接导入它的模块”引用，而测试文件（*_test.go）必须与被测代码在同一包内、同一目录下，才能访问未导出标识符。

internal 目录的可见性边界必须清晰

Go 规定：任何位于 path/to/internal/ 下的包，仅允许被 path/to/ 及其子路径（但不能跨过其他 internal）下的模块导入。例如：

• github.com/user/project/internal/handler 可被 github.com/user/project/cmd 或 github.com/user/project/internal/service 导入
• 但 github.com/user/other-project 绝对无法导入它，即使路径看起来“可达”
• 若你在 internal 外新建一个 testutil 目录并想让 internal/handler 用它，不行——因为 testutil 不在 internal 的“可信任父路径”内

测试文件必须和被测代码同目录、同包名

Go 测试机制依赖包级作用域。要测试 internal/handler 中的私有函数 parseQuery()，你不能把测试写在 internal/handler_test/ 或 test/ 目录里——那样会变成另一个包，无法访问未导出名。

• ✅ 正确做法：在 internal/handler/ 目录下放 handler_test.go，且文件顶部写 package handler
• ❌ 错误做法：放在 internal/handler/test/xxx_test.go 并声明 package test —— 这属于外部包，连 handler 的公开类型都要加 import，更别说私有函数
• ⚠️ 注意：如果测试需要额外依赖（比如 mock 工具），建议用 //go:build unit + build tag 隔离，避免污染主构建

需要跨 internal 包测试？用“测试桥接包”折中

有时你需要从 internal/service 测试 internal/handler 的集成逻辑，但又不能直接 import（因不在同一父路径）。这时可建一个临时测试专用包：

• 在 internal/handler 同级新建 internal/handler_testbridge/
• 该包声明 package handler_testbridge，并只暴露测试所需的小接口或构造函数
• internal/service 可以安全导入 handler_testbridge（因同属 internal/ 父目录）
• 这个包不参与生产构建，仅用于测试，CI 中通过 go test ./... 自动包含

go.mod 和测试执行要匹配模块根路径

确保你在模块根目录（即含 go.mod 的目录）下运行测试命令：

• ✅ go test ./internal/handler —— 正确识别模块路径，能解析 internal 规则
• ❌ 在 internal/handler/ 目录下执行 go test —— Go 会尝试以当前目录为模块根，找不到 go.mod，可能报 no required module provides package
• ? 小技巧：在 internal/handler 下加一个空的 go.mod 是反模式，会破坏模块一致性

基本上就这些。internal 不是黑盒，而是显式划定的“信任边界”；测试不是附属品，而是包的一等公民——只要目录和包名对齐，Go 自然支持你测到最深的私有逻辑。