一文告诉你当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核心技术，并继续加强与星友的互动。欢迎大家加入！

img{512x368}

著名云主机服务厂商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

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

一文告诉你当module path为main时执行go test失败的真正原因

1. 建立试验环境，复现问题

2. go module、go package与import path

3. module root directory的包的导入路径是什么

4. go test的原理

5. 真相大白

6. 参考资料

仅有 1 条评论

添加新评论

欢迎使用邮件订阅我的博客

文章

评论

分类

归档

链接

开源项目

翻译项目

一文告诉你当module path为main时执行go test失败的真正原因

1. 建立试验环境，复现问题

2. go module、go package与import path

3. module root directory的包的导入路径是什么

4. go test的原理

5. 真相大白

6. 参考资料

仅有 1 条评论

添加新评论

欢迎使用邮件订阅我的博客

文章

评论

分类

标签

归档

链接

开源项目

翻译项目