本文永久链接 – https://tonybai.com/2024/10/05/using-git-submodules-in-go-projects

在软件开发中，依赖管理一直是一个重要的议题，特别是在像Go这样的编程语言中，随着项目的扩展，如何有效管理依赖变得至关重要。Git Submodule作为Git的一个重要功能，允许在一个Git仓库中嵌入另一个仓库，从而方便地管理跨项目的代码共享。然而，Go语言引入的Go Module机制似乎已经解决了依赖管理的问题，那么在Go项目中，是否还有使用Git Submodule的必要呢？本文将简单探讨一下Go项目中Git Submodule的使用方法，并分析它是否还值得使用。

1. Git Submodule是什么？

Git Submodule是Git版本管理工具提供的一个功能，允许你将一个Git仓库作为另一个Git仓库(主仓库)的子目录。主仓库通过记录Submodule的URL和commit hash来追踪Submodule。当你克隆一个包含Submodule的仓库时，需要额外的步骤来初始化和更新Submodule。

下面是一个将github.com/rsc/pdf仓库作为git submodule的示例。

我们先建立主仓库：

$mkdir main-project
$cd main-project
$go mod init main-project
$git init
$git add -A
$git commit -m"initial import" .
[master (root-commit) 8227e65] initial import
 1 file changed, 3 insertions(+)
 create mode 100644 go.mod

接下来，我们来添加submodule：

$git submodule add https://github.com/rsc/pdf.git
Cloning into '/Users/tonybai/Test/Go/submodule/main-project/pdf'...
remote: Enumerating objects: 48, done.
remote: Counting objects: 100% (30/30), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 48 (delta 21), reused 21 (delta 21), pack-reused 18 (from 1)
Unpacking objects: 100% (48/48), done.

$git commit -m "Add rsc/pdf as a submodule"
[master 2778170] Add rsc/pdf as a submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 pdf

git submodule在主仓库的顶层目录下创建一个.gitmodules文件：

$cat .gitmodules
[submodule "pdf"]
    path = pdf
    url = https://github.com/rsc/pdf.git

pdf子目录下的.git不再是目录而是一个文件，其内容指示了pdf仓库的git元数据目录的位置，即主仓库下的.git/modules/pdf下：

$cat pdf/.git
gitdir: ../.git/modules/pdf

git submodule这种机制的主要用途是当多个项目之间有共享代码时，避免将共享的代码直接复制到每个项目中，而是通过Submodule来引用外部仓库。这种方式使得共享代码的版本控制更加明确和独立，也方便了项目之间的更新、管理与版本控制。

通过git submodule status可以查看主仓库下各个submodule的当前状态：

$git submodule status
 c47d69cf462f804ff58ca63c61a8fb2aed76587e pdf (v0.1.0-1-gc47d69c)

通过git submodule update还可以更新各个submodule到最新版本。 但通常在主仓库中会锁定Submodule的特定版本，通过锁定Submodule的版本，可以确保主仓库使用的是经过测试和验证的Submodule代码，这减少了因Submodule更新而导致的意外问题。同时，锁定版本还可以确保所有开发者和构建环境都使用完全相同版本的Submodule，这对于保证构建的一致性和可重现性至关重要。版本锁定让你还可以精确控制何时更新Submodule，你可以在准备好处理潜在的变更和进行必要的测试时，有计划地更新Submodule版本。submodule的版本锁定可以通过下面命令组合实现：

cd path/to/submodule
git checkout <specific-commit-hash>
cd -
git add path/to/submodule
git commit -m "Lock submodule to specific version"

这个提交会更新主仓库中记录的Submodule版本，其他克隆主仓库的人在初始化和更新Submodule时，就会自动获取到这个特定版本。

在以Git为版本管理工具的项目中，Submodule在以下一些场景中还是很有用的：

• 在多项目依赖场景下，我们可以使用Submodule共享公共库；
• 在大型单一仓库中，Submodule有助于我们模块化管理各个子项目；
• 统一对Submodule的版本进行严格管理，避免在更新时引入未测试的新代码。

submodule虽然可以解决一些问题，但由于增加了项目管理复杂度以及学习成本，应用算不上广泛，但也不乏一些知名的开源项目在使用，比如git项目自身、openssl、qemu等。

不过，对于Go项目而言，Go Modules是Go在Go 1.11引入的新的官方依赖管理机制，它通过go.mod文件声明依赖关系，通过go.sum文件确保依赖的完整性，实现了构建的可重现性。那么，在Go项目中还有必要引入sub modules吗？

这里我们先不下结论，而是先来看看Go项目引入submodule后该如何使用呢。

2. Go项目的Git Submodule使用方法

在前面我们在本地建立了一个main-project，然后将rsc/pdf作为submodule导入到了main-project中，main-project是一个Go项目，它的go.mod如下：

// main-project/go.mod

module main-project

go 1.23.0

我们现在就继续使用这个示例来看看Go项目中git submodule的使用方法。

我们先来看一种错误的使用方法：使用相对路径。

我们在main-project下建立一个main.go的源文件：

// main-project/main.go

package main

import (
    _ "./pdf"
)

func main() {
    println("ok")
}

建完后，整个main-project的目录布局如下：

$tree -F
.
├── go.mod
├── main.go
└── pdf/
    ├── LICENSE
    ├── README.md
    ├── lex.go
    ├── name.go
    ├── page.go
    ├── pdfpasswd/
    │   └── main.go
    ├── ps.go
    ├── read.go
    └── text.go

在第一版main.go中，我们期望使用相对路径来导入submomdule中的pdf包，运行main.go，我们得到下面结果：

$go run main.go
main.go:4:2: "./pdf" is relative, but relative import paths are not supported in module mode

我们看到：在go module构建模式下，Go已经不再支持以相对路径导入Go包了！但是如果我们直接通过rsc.io/pdf这个路径导入，那显然使用的就不是submodule中的pdf包了。

下面我们试试第二种方法，即将pdf目录看成main-project的子目录，将pdf包看成是main-project这个module下的一个包，这样pdf包在main-project这个module下的导入路径就变成了main-project/pdf：

// main-project/main.go
package main

import (
    _ "main-project/pdf"
)

func main() {
    println("ok")
}

这次构建和运行main.go，我们将得到正确的预期结果。

到这里，我们似乎又找到了go module之外go项目依赖管理的新方法，并且这种方法特别适合当某些依赖项目尚未发布，还无法直接通过Go Module导入的库，甚至是一些永远不会发布的内部库或私有库。这种方法让pdf看起来是main-project的一部分，但实际上pdf包的版本却是需要开发人员自己通过git submodule命令管理的，pdf包的版本无法用go.mod(和go.sum)控制，因为它被视为是main-project的一部分了，而不是外部依赖包。

如果你不想将其视为main-project的一部分，还想将其以外部依赖的方式管理起来，那就需要利用到go module的replace或go.work了。不过这种方法的前提是submodule下必须是一个go module，即有自己的go.mod。rsc.io/pdf包是一个legacy package，还没有自己的go.mod，我们先在本地pdf目录下为其添加一个go.mod：go mod init rsc.io/pdf。

接下来，我们先来简单看看用replace如何实现导入pdf包，我们需要修改一下main-project/go.mod：

// main-project/go.mod

module main-project

go 1.23.0

require rsc.io/pdf v0.1.1

replace rsc.io/pdf => ./pdf

这里我们用replace指示符将rsc.io/pdf替换为本地pdf目录下的go module，这样修改后，我们运行main.go也会得到正确的结果。

另外我们还可以使用go.work来导入pdf，下面命令初始化一个go.work：

$go work init .

编辑go.work，添加workspace包含的路径：

go 1.23.0

use (
    .
    ./pdf
)

这样go编译器会默认在当前目录和pdf目录下搜索rsc.io/pdf模块，运行main.go也是ok的。

相对于将pdf包看成是main-project module下的一个包并用main-project/pdf这个内部依赖的包导入路径的方法，使用replace或go.work的好处在于一旦pdf包得以发布，main.go可以无需修改pdf包导入路径，并可以基于go.mod精确管理pdf包的版本。

3. 小结

那么我们在Go项目中到底是否有必要使用sub modules呢？我们来小结一下。

总的来说，在大多数情况下，Go Modules确实已经覆盖了Git Submodule在Go项目中的主要功能，甚至做的更好，比如：Go Modules提供了更细粒度的版本控制，能自动解析和下载依赖，并也可以确保了构建的可重现性。因此，对于大多数Go项目而言，使用Go Modules已经足够满足依赖管理需求，而无需再使用git submodule。 并且，在Go项目以及Go社区的实践中，应对类似共享未发布的依赖包的场景(git submodule适用的场景)，使用replace或go.work是比较主流的实践，或者说go.work以及replace就是为了这种情况而添加的。

当然如果组织/公司内部尚未构建可以很好地支持内部Go项目间依赖包获取、导入和管理的基础设施，那么git submodule不失为一种可以在内部Go项目中实施的可行的依赖版本管理和控制方案。

最后，无论选择使用Git Submodule、Go Modules，还是两者结合，最重要的是要确保项目结构清晰，依赖关系明确，以便于团队协作和项目维护。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

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

本文永久链接 – https://tonybai.com/2024/10/02/why-canonical-import-paths-no-longer-necessary-in-go

Go语言自推出以来，一直以其简洁和高效的包管理系统著称。在Go 1.11版本之前，Canonical Import Path注释曾是一个重要的工具，用于防止包路径的导入冲突。然而，随着Go Modules的引入，这一工具的作用逐渐被淡化。那么Canonical Import Path注释是否还有必要存在呢？在这篇文章中，我就来介绍一下Canonical Import Path的历史及作用，并通过在Go Modules环境下的向后兼容性测试，讨论是否仍有必要继续使用这一注释。

1. 什么是Canonical Import Path注释？

Go在1.4版本中增加了Canonical Import Path，Canonical Import Path用于解决同一个包可能被通过多个导入路径导入的问题。比如当代码托管在像github.com这样的服务上时，导入路径会包含托管服务的域名，比如“github.com/rsc/pdf。但是Go开发者也可以为同一个包提供一个“自定义”或“vanity”导入路径，例如rsc.io/pdf。这样就会产生两个有效的导入路径，这会带来以下问题：

• 同一个程序中可能会通过不同路径导入同一个包，造成不必要的重复。
• 使用非官方路径时可能会错过包更新，因为路径没有得到正确识别。
• 将包迁移到另一个托管服务时，可能会中断使用旧路径的客户端。

为了解决这个问题，Go 1.4引入了Canonical Import Path注释。在包声明中加上注释后，如果通过非Canonical Import Path导入包，Go命令将拒绝编译导入包的程序。

Canonical Import Path的语法很简单，在包声明的注释部分加上标识。例如，对于rsc.io/pdf包，声明可以写成：

package pdf // import "rsc.io/pdf"

这样，Go命令就会拒绝编译任何通过github.com/rsc/pdf路径导入的包，确保代码可以在不破坏用户代码的前提下自由迁移。

2. Go Modules及其对导入路径的影响

Go 1.11引入Go Modules后，Go通过go.mod文件管理包的依赖关系和版本，极大简化了包的管理过程。通过在go.mod中定义模块的根路径，Go Modules可以自动指示项目中所有包的导入路径，并且是唯一的，这使得Canonical Import Path在Go Modules环境下基本没什么必要性了。

例如，假设go.mod文件定义了以下模块路径：

// go.mod
module rsc.io/pdf

那么位于项目根目录下的包的导入路径将被自动解析为rsc.io/pdf，避免了包路径冲突问题。因此，在Go Modules的支持下，手动设置Canonical Import Path注释变得不再必要。

Go提供了Go1向后兼容，在Go module下使用Canonical Import Path注释会是什么情况呢？我们接下来来看看。

3. 在Go Modules下使用Canonical Import Path注释

虽然Go Modules简化了包管理，很多老项目仍然保留了Canonical Import Path注释。为了验证在Go Modules环境下继续使用这些注释的兼容性，我进行了以下测试(测试环境使用的是包括Go 1.23.0版本在内的多个Go版本)。

在这个测试中，我们保持项目中的Canonical Import Path注释不变，看看它是否影响在Go Modules环境中的编译和运行。

这里我们直接使用位于github.com/rsc/pdf中的pdf包，该包在read.go文件中使用了Canonical Import Path注释：

// https://github.com/rsc/pdf/blob/master/read.go
package pdf // import "rsc.io/pdf"

我们先用Go 1.11版本之前的Go版本测试一下导入rsc.io/pdf包。由于Go 1.11版本之前依然采用的是GOPATH构建模式，因此需要先将github.com/rsc/pdf下载到\$GOPATH/src的github.com/rsc下，因为GOPATH模式下，go编译器回到\$GOPATH路径下搜寻依赖包。

接下来，我们建立demo1目录，并直接将github.com/rsc/pdf/pdfpasswd/main.go复制到demo1目录下，该main.go导入了”rsc.io/pdf”，我们将其改为导入”github.com/rsc/pdf”：

// demo1/main.go

package main

import (
    "flag"
    "fmt"
    "log"
    "os"

    "github.com/rsc/pdf"
)

var (
    alphabet  = flag.String("a", "0123456789", "alphabet")
    maxLength = flag.Int("m", 4, "max length")
)

func usage() {
    fmt.Fprintf(os.Stderr, "usage: pdfpasswd [-a alphabet] [-m maxlength] file\n")
    os.Exit(2)
}

func main() {
    log.SetFlags(0)
    log.SetPrefix("pdfpasswd: ")

    flag.Usage = usage
    flag.Parse()
    if flag.NArg() != 1 {
        usage()
    }

    f, err := os.Open(flag.Arg(0))
    if err != nil {
        log.Fatal(err)
    }

    last := ""
    alpha := *alphabet
    ctr := make([]int, *maxLength)
    pw := func() string {
        inc(ctr, len(alpha)+1)
        for !valid(ctr) {
            inc(ctr, len(alpha)+1)
        }
        if done(ctr) {
            return ""
        }
        buf := make([]byte, len(ctr))
        var i int
        for i = 0; i < len(buf); i++ {
            if ctr[i] == 0 {
                break
            }
            buf[i] = alpha[ctr[i]-1]
        }
        last = string(buf[:i])
        println(last)
        return last
    }
    st, err := f.Stat()
    if err != nil {
        log.Fatal(err)
    }
    _, err = pdf.NewReaderEncrypted(f, st.Size(), pw)
    if err != nil {
        if err == pdf.ErrInvalidPassword {
            log.Fatal("password not found")
        }
        log.Fatal("reading pdf: %v", err)
    }
    fmt.Printf("password: %q\n", last)
}

func inc(ctr []int, n int) {
    for i := 0; i < len(ctr); i++ {
        ctr[i]++
        if ctr[i] < n {
            break
        }
        ctr[i] = 0
    }
}

func done(ctr []int) bool {
    for _, x := range ctr {
        if x != 0 {
            return false
        }
    }
    return true
}

func valid(ctr []int) bool {
    i := len(ctr)
    for i > 0 && ctr[i-1] == 0 {
        i--
    }
    for i--; i >= 0; i-- {
        if ctr[i] == 0 {
            return false
        }
    }
    return true
}

然后，我们先用Go 1.10.8版本编译该main.go，得到下面结果：

$go run main.go
main.go:9:2: code in directory /Users/tonybai/Go/src/github.com/rsc/pdf expects import "rsc.io/pdf"

我们看到go 1.11之前的版本对pdf包声明的Canonical Import Path做了检查，如果实际导入路径(github.com/rsc/pdf)与其不符，Go编译器会报错！

接下来，我们来看看切换到go module模式后的编译结果，这里我们使用Go 1.12.7版本。我们创建go.mod文件：

// demo1/go.mod
module demo1

go 1.12

编译执行main.go：

$go run main.go
go: finding github.com/rsc/pdf v0.1.1
go: downloading github.com/rsc/pdf v0.1.1
go: extracting github.com/rsc/pdf v0.1.1
usage: pdfpasswd [-a alphabet] [-m maxlength] file
exit status 2

我们看到，go 1.12.7可以成功编译并运行main.go，即便后者没有使用Canonical Import Path导入pdf包。

而用最新的Go 1.23.0编译和运行，也是没问题的：

$go run main.go
usage: pdfpasswd [-a alphabet] [-m maxlength] file
exit status 2

由此可以得出结论：go module模式下，Go编译器已经不再校验导入包的Canonical Import Path了。

并且，即便main.go同时导入rsc.io/pdf和github.com/rsc/pdf也是没问题的：

import (
    "flag"
    "fmt"
    "log"
    "os"

    "github.com/rsc/pdf"
    _ "rsc.io/pdf"
)

这是因为github.com/rsc/pdf下没有go.mod，go编译器无法识别github.com/rsc/pdf和rsc.io/pdf是同一个包。我们再看一个uber-go/zap的例子：

package main

import (
    "fmt"

    _ "github.com/uber-go/zap"
    _ "go.uber.org/zap"
)

func main() {
    fmt.Println("hello, zap!")
}

针对这个main.go所在的go module进行go mod tidy，我们会得到如下错误结果：

$go mod tidy
go: finding module for package go.uber.org/zap
go: finding module for package github.com/uber-go/zap
go: downloading go.uber.org/zap v1.27.0
go: downloading github.com/uber-go/zap v1.27.0
go: found github.com/uber-go/zap in github.com/uber-go/zap v1.27.0
go: found go.uber.org/zap in go.uber.org/zap v1.27.0
go: demo imports
    github.com/uber-go/zap: github.com/uber-go/zap@v1.27.0: parsing go.mod:
    module declares its path as: go.uber.org/zap
            but was required as: github.com/uber-go/zap

我们看到：go命令检测出了github.com/uber-go/zap仓库下的go module是go.uber.org/zap，我们只能使用go.uber.org/zap作为zap包的导入路径。

4. 是否应移除Canonical Import Path注释？

在Go Modules已经成为Go项目默认包管理方式的背景下，Canonical Import Path的使用显得冗余。虽然保留这些注释不会导致兼容性问题，但移除它们可以让项目代码更加简洁，减少不必要的历史包袱。

对于已经迁移到Go Modules的老项目，开发者可以考虑逐步移除Canonical Import Path注释。对于新项目，则是没有必要添加Canonical Import Path注释，Go Modules已经足够强大，能够管理包路径和依赖；如果项目的用户仍依赖旧版Go工具链(GOPATH模式)，保留Canonical Import Path注释则可以作为一种保险措施。

5. 小结

Canonical Import Path注释在Go 1.4引入时是为了解决包路径冲突和包迁移问题。然而，随着Go Modules的引入，包管理和路径控制功能逐渐被自动化，Canonical Import Path的作用显得不再必要。对于现代Go项目，开发者应考虑移除这一冗余的注释，这不仅是代码简化的一部分，也反映了Go生态系统中包管理方式的演进，并使项目更加符合Go语言的现代开发环境。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

• 微博(暂不可用)：https://weibo.com/bigwhite20xx
• 微博2：https://weibo.com/u/6484441286
• 博客：tonybai.com
• github: https://github.com/bigwhite
• Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
• Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

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