一文告诉你当module path为main时执行go test失败的真正原因
本文永久链接 – https://tonybai.com/2023/04/08/the-reason-why-go-test-fails-when-module-path-is-main
近期收到新加入“Gopher部落”知识星球的星友“凌风”的一个问题，内容如下：
在一个目录下，我编写了a.go和a_test.go，在go mod init main后执行go test，会报错：could not import main( can not import "main")。我知道它的解决方法是改变包名。我的问题是：
1. 难道无法对 main 包执行包内测试了么。
2. 这里的报错的底层原因是什么。
本文将针对这个问题做一个简要的分析，这将涉及到go module、go package和package import的相关概念以及go test的工作原理等内容。
1. 建立试验环境，复现问题
我们先搭建一个试验环境，复现一下这位星友遇到的问题：
// https://github.com/bigwhite/experiments/blob/master/module-path-main
$tree module-path-main
module-path-main
├── go.mod
├── pkg.go
└── pkg_test.go
$cat go.mod
module main
go 1.20
$cat pkg.go
package main
func Add(a, b int) int {
return a + b
}
$cat pkg_test.go
package main
import (
"testing"
)
func TestAdd(t *testing.T) {
n := Add(5, 6)
if n != 11 {
t.Errorf("want 11, got %d\n", n)
}
}
好了！我们执行go test运行测试：
$go test
# main.test
/var/folders/cz/sbj5kg2d3m3c6j650z0qfm800000gn/T/go-build1902276879/b001/_testmain.go:14:8: could not import main (cannot import "main")
FAIL main [build failed]
我们看到：这里使用Go 1.20版本执行的go test命令报错！报错内容与星友的问题一致！问题复现了！接下来我们就来分析一下为何会报错！
2. go module、go package与import path
分析问题之前，我们还是要理清楚go module、go package与import path这几个概念。
go package的概念大家已经很熟悉了，这是Go的基本编译单元，是go从娘胎里就带的概念。后面的go module、import path与package概念都相关。
Go在1.11版本引入go module，之后go module就替代gopath构建模式成为了Go标准构建模式。
Go mod参考手册中关于go module的定义是：“一个module由一个module path来识别，go.mod文件中声明了module path以及关于该module的依赖信息(require、replace等)。包含go.mod文件的目录被称为module root directory。main module是包含调用go命令的目录的module。
注：本文只讨论go module模式，过时的GOPATH模式不再讨论之列。
注：main module的说法极易造成概念混淆，在Go 1.21版本或后续版本中可能会改为work module。
Go module的引入是为了解决依赖管理问题，所以go module是一组package的集合，这组package的版本与module版本绑定。但go module的引入，也对package的import path的确定与含义产生了些许影响。
GOPATH构建模式时代，go package的导入路径(import path)是该package所在目录相对于\$GOPATH/src的路径来确定的。比如你的package放在了\$GOPATH/src/github.com/user/repo下，那么你的package的导入路径就是import “github.com/user/repo”。这和当时go get下载包的路径规则是一致的。
在Go module时代，\$GOPATH/src不再强制，go module与\$GOPATH/src也没有任何耦合关系了。这时，go package的导入路径由go module path和package在module中的相对路径共同确定：
- 如果你的module path(go.mod文件中声明)为github.com/user/yourmodule，你的package在yourmodule根路径下的foo/bar目录下，那么你的package的导入路径就是github.com/user/yourmodule/foo/bar。
- 如果你的module使用了自定义module路径，比如：example.com/go/yourmodule，那么同样，如果你的package在yourmodule根路径下的foo/bar目录下，这个package的导入路径将为example.com/go/yourmodule/foo/bar。
- 如果你的module采用的不是上述两种url的方式，而是使用tonybai/yourmodule这样的“本地路径”形式，那么如果你的package在yourmodule根路径下的foo/bar目录下，这个package的导入路径将为tonybai/yourmodule/foo/bar。
注：除了做包导入路径的前缀，module path还可以用来指示module存放的版本托管服务的url地址。
上面概念与它们的关系对解决我们文首处的问题有什么帮助呢？别急！下面这个推论与本文那个问题强相关。
3. module root directory的包的导入路径是什么
好了，下面就是与本文开头那个问题最相关的一个问题了：go module的根目录(module root directory)下的package的导入路径是啥？根据上面对go module模式下package导入路径的定义：go module根目录下包的导入路径就是module path。
以我们上面的试验项目为例，main module的根路径为module-path-main目录，该目录下面存放了一个包main(pkg.go)，那么该main包的导入路径就为go module的module path：”main”。即便你将pkg.go中的包名由”main”改为”demo”，demo包的包导入路径依旧为”main”。
注：《Go语言第一课》专栏04讲和06讲有关于包导入路径的深入理解。
注：星友凌风在问题中说：改变go包名可以解决这个问题，这个说法是不正确的。将上面的包名main改为demo，go test依然会报同样的错误。
4. go test的原理
好了！关于go module、package以及package import路径的概念复习的差不多了，这些概念的复习是解决文首问题的一个前提，我们先把它们暂存在大脑里。我们再聊看另一半知识：go test。
Go test是Go内置的测试框架，我们可以用它来驱动单元测试、集成测试甚至是自动化测试。
在一个包内执行go test后，go test会首先编译目标包，然后编译测试包(测试包和目标包可能是一个包，也可能是不同包)，即目录下所有以_test.go为后缀的源文件。go test会将测试包编译为一个可执行文件，这个可执行文件的main包会依赖并导入测试包，并会调用测试包中的TestXxx导出方法执行测试。
注：go test -c可以得到这个可执行文件pkg.test
5. 真相大白
好了，有了上述关于两个知识准备后，我们来揭开问题的真相！
我们使用go test -work来查看go test执行生成的可执行文件的main函数所在文件(传入-work标志的目的是让go编译器在编译后依然保留构建测试源文件的临时目录)：
// 在module-path-main下执行
$go test -work
WORK=/var/folders/cz/sbj5kg2d3m3c6j650z0qfm800000gn/T/go-build2039841248
# main.test
/var/folders/cz/sbj5kg2d3m3c6j650z0qfm800000gn/T/go-build2039841248/b001/_testmain.go:14:8: could not import main (cannot import "main")
FAIL main [build failed]
打开临时路径下b001下面的_testmain.go，这个文件是go test工具生成的：
// Code generated by 'go test'. DO NOT EDIT.
package main
import (
"os"
"testing"
"testing/internal/testdeps"
_test "main"
)
var tests = []testing.InternalTest{
{"TestAdd", _test.TestAdd},
}
var benchmarks = []testing.InternalBenchmark{
}
var fuzzTargets = []testing.InternalFuzzTarget{
}
var examples = []testing.InternalExample{
}
func init() {
testdeps.ImportPath = "main"
}
func main() {
m := testing.MainStart(testdeps.TestDeps{}, tests, benchmarks, fuzzTargets, examples)
os.Exit(m.Run())
}
我们看到这就是我们要编译出来的测试可执行文件的main包和main函数的内容，其中最关键的一行是：
import (
... ...
_test "main" // 这行是导致go test执行出错的“罪魁祸首”
... ...
)
根据我们之前复习的go module下package导入路径的定义，这里的”main”其实是module-path-main这个module根路径下的包的导入路径，前面说了：这个顶层包(无论包名是什么，是main也好，是demo也罢)的导入路径就是module path，而这里我们定义的module path是main，因此这里的路径为”main”。
根据包导入路径规则，如果是像”fmt”、”io”这样的导入路径，go编译器会从标准库中搜索；如果是”main”，则认为是main包。
好了，问题来了！这个_testmain.go是go test生成的测试可执行程序的main包，它现在又导入了一个”main”包，而Go语言是不允许导入main包的。因为main包以及main函数通常是用来集成你的各个代码单元（也就是包）的，如果你的其他代码单元再依赖main，就会造成“循环导入”，这在Go中是绝对禁止的。这就是文首问题的真正原因。
注：main包支持单元测试，但通常建议不要针对main包进行单元测试。如果你在main里有值得测试的代码（用于单元测试；而不是用于集成测试），可以考虑把它移到一个库包里。
知道了真因后，解决方法也十分简单，那就是重命名module path，比如改为demo，这样go test就会成功执行了。而改为demo后，_testmain中导入代码变成了：
import (
... ...
_test "demo"
... ...
)
这显然不会导致go编译器报错！
6. 参考资料
- go mod reference – https://go.dev/ref/mod
- “Tests in main package don’t work with GO111MODULE=on” – https://github.com/golang/go/issues/28514
本文涉及的代码可以在这里下载 – https://github.com/bigwhite/experiments/blob/master/module-path-main
“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！
著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。
Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily
我的联系方式：
- 微博(暂不可用)：https://weibo.com/bigwhite20xx
- 微博2：https://weibo.com/u/6484441286
- 博客：tonybai.com
- github: https://github.com/bigwhite
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。
评论