二七九九笔记

golang学习路线总结

Tue, 14 Apr 2026 18:30:52 +0800

基础篇

提升篇

应用篇

Golang Package 与 Module 简介

Tue, 31 Mar 2026 10:23:31 +0800

软件是由代码组成的。为了复用代码，代码的组织出现了不同层次的抽象和实现，如 Module（模块），包（Package），Lib（库），Framwork（框架）等。

通常一个Project（项目），会根据功能拆分很多 module，常用的软件会打包成一个个共享库。在开源社区分享软件包是一件十分 cool 的事儿。这些软件包也有可能引用了其他的开源包，因此开源项目上经常会有软件相互依赖，或依赖某个包，或依赖某个包的某个版本。

现代的语言都有很多好用的包管理工具，如 pip 之于 python，gem 之于 ruby，npm 之于 nodejs。然而 Golang 早期版本却没有官方的包管理器，直到 go1.5 才添加了实验性的 vendor。尽管官方的不作为（保守），还是无法阻止社区的繁荣。社区诞生了许多工具，比较有代表如 govender，glide，gopm，以及半官方的 dep 等。

百花齐放的另外一层含义也是工具链混乱的表现。

终于在 go1.12，发布了官方的包管理工具 Go Module。go module 不仅带来了统一的标准，而且对于旧软件包的处理，以及所坚持的包管理哲学都挺有意思。下面将会从 go module 之前的包管理方式和升级到 go module 方式做一个简单的说明。

下面的例子以常见的使用方式做介绍，并没有深入其背后的原理与实现。例如go.sum 以及一些最下化处理原则不会涉及。部分内容闲扯一下 go 的流派观点。

GOPATH

在 go1.12 之前，安装 golang 之后，需要配置两个环境变量----GOROOT 和GOPATH。前者是 go 安装后的所在的路径，后者是开发中自己配置的，用于存放go 源代码的地方。在 GOPATH 路径内，有三个文件夹，分别是

bin: go 编译后的可执行文件所在的文件夹
pkg: 编译非 main 包的中间连接文件
src: go 项目源代码

开发的程序源码则放在src里，可以在src里创建多个项目。每一个项目同时也是一个文件夹。

go1.12 之后，淡化了 GOPATH，因此也可以忽略这部分内容。

Package
main package

golang 的所有文件都需要指定其所在的包（package），包有两种类型，一种是 main 包，使用 package main 在代码的最前面声明。另外一种就是非main 包，使用 package + 包名。main 包的可以有唯一的一个 main 函数，这个函数也是程序的入口。也只有 main 包可以编译成可执行的文件。

下面看一个简单的例子：

➜ golang echo $GOPATH/Users/master/golang
➜ golang pwd/Users/master/golang
➜ golang tree
.
├── bin
├── pkg
└── src
└── demo
└── main.go

4 directories, 1 file

➜ demo cat main.go
package main

import ("fmt")

func main() {fmt.Println("hello world")
}

➜ demo go run main.go
hello world

从上面的目录结构可以看出，GOPATH为 /Users/master/golang 。在 src 内创建了一个项目 demo。demo 里有一个 main.go 文件。main.go 的第一行声明了这是一个 main 包，因此可以定义一个 main 函数。使用 go run 可以编译并运行 main.go。

虽然 main 包的文件名也是 main.go，其实包名和文件名没有直接关系。

自定义 package

go 使用 package 来管理源文件。package 必须在一个文件夹内，且一个文件夹内也只能有一个package，但是一个文件夹可以有多个文件。下面自定义一个 package。

➜ demo tree
.
├── main.go
└── service
└── http.go

1 directory, 2 files
➜ demo cat service/http.go
package api

import "fmt"

func HandleReq(){
fmt.Println("api - http.go Handle Request")
}
➜ demo cat main.go
package main

import (
"fmt"
"./service"
)

func main() {
fmt.Println("hello world")
api.HandleReq()
}

在 demo 文件内创建一个文件夹 service，在 service 内又创建了 http.go 文件。后者声明为 package api ，即包名为 api。然后在 main.go 文件中，通过 import "./service" 引入了api 包所在的文件夹。最后通过包名.包函数调用。

输出结果如下：

➜ demo go run main.go
hello world
api - http.go Handle Request

从上面的例子可以看到，包名为 api，文件夹为 service，文件为 http.go。它们三者的命名都是不一样的。这与很多其他语言相悖。正如前文所言，一个包可以分散在不同的同级文件里，只要都声明为一个包名即可。例如下面再增加一个文件：

➜ demo cat service/rpc.go
package api

import "fmt"func HandleResp(){fmt.Println("api - rpc.go Handle Request")
}

在 main 函数里同样使用包名.包函数 ---- api.HandleResp() 调用。其实很好理解，即同样的一个包，文件内容太多，拆分成多个文件而已。文件名跟包名没有直接关系。如果只有一个文件，通常可以写成包名。但是导入的时候，必须导入包所在的文件夹的路径。其实可以这样理解，import 的是 path（路径），那么go就去那个路径下搜索，搜索当然是查找包名。只不过通常习惯是文件名和包名一致。

这包名和文件夹名不一致，是反模式。主要是为了直观的表示包名和文件夹名没有直接关系。

内嵌 package

在 service 内再创建一个文件夹 api，此时再命名一个 api.go 文件。即文件夹名和包名一致。其内容如下：

➜ demo cat service/api/api.go
package api

import "fmt"func HandleError(){fmt.Println("api api.go Handle Error")
}

import package 就是导入包所在的文件夹，因此 main.go 如下：

import ("fmt""./service""./service/api")

但是这样编译会报错：

➜ demo go run main.go
# command-line-arguments
./main.go:6:9: api redeclared as imported package name
previous declaration at ./main.go:5:2./main.go:11:2: undefined: "_/Users/master/golang/src/demo/service/api".HandleReq
./main.go:12:9: undefined: "_/Users/master/golang/src/demo/service/api".HandleResp

显然，在 service 文件内的 http.go 和 rpc.go 声明了 package api。在 service/api 文件夹里的 api.go 也声明为 api。这是同名的两个包。

但是在 main 函数里，都是使用包名引用函数。由于名字冲突，无法确定到底使用那个 api 包，进而报错。解决方法也很简单，给包名增加一个别名即可。

import ("fmt""./service"apiNew "./service/api")

func main() {fmt.Println("hello world")
api.HandleReq()
api.HandleResp()
apiNew.HandleError()
}

这样 api 就是 service 空间下的，apiNew 就是 service/api 空间下，两者相互隔离。

导入规则

前面 import 语句内，通过相对路径导入了包。对于*nix系统，相对路径 . 通常是可以省略的。下面就省略试试：

import ("fmt""service"apiNew "service/api")

此时会发现报错：

➜ demo go run main.go
main.go:5:2: cannot find package "service" in any of:/usr/local/go/src/service (from $GOROOT)/Users/master/golang/src/service (from $GOPATH)
main.go:6:9: cannot find package "service/api" in any of:/usr/local/go/src/service/api (from $GOROOT)/Users/master/golang/src/service/api (from $GOPATH)

报错信息也简单明了。即 go 先从 $GOROOT/src 搜索 service 包，找不到然后从 $GOPATH/src 里搜索。也找不到，进而报错。

这里就涉及到 go 的包搜索方式。通常 standard pkg（标准库）都在$GOROOT/src 里，因此会从这里搜索。而用户自定义的包，或者三方包，go是统一从 $GOPATH/src 里搜索的。当不使用 . 显式表明相对导入，那么 go 就会相对于 $GOPATH/src 导入。解决上面的方法就是把 service 包放到 demo 外面

➜ src tree
.
├── demo
│ ├── main.go
│ └── service
│ ├── api
│ │ └── api.go
│ ├── http.go
│ └── rpc.go
└── service
├── api
│ └── api.go
├── http.go
└── rpc.go5 directories, 7 files

通常，如果 service 是 demo 的一个内部模块，那么就放到 demo 内，使用 . 方式相对导入。如果它是一个可以共享的 package，就可以放到 GOPATH 下。为什么 go会使用 GOPATH 这样的集中文件夹呢？

此外，想要把这个 service 包发布出去，可以使用 github 管理源代码和包版本。

首先需要从 github 创建一个 repo（仓库）。常见的形式是 github.com/username/repo。因此软件包的名也是这个规则。

例子：

初始化 service

在 github上创建一个 repo 叫 service，并打上了 v1.0.0 的版本 tag。那么在mian.go 里引用就是这样：

import ("fmt""github.com/rsj217/service")

上述的 import 语句，无非就是增加了包 servic e的文件夹层级 github.com/rsj217 而已。这样做的主要目的是为了让 go get 工具从网络上的 url 地址拉取包。go get 会自动从 github.com/rsj217/service 拉取源码，并 copy 到 $GOPATH/src 下。运行go get 或者 go run main.go ，go 都会从 import 语句中解析并下载软件包。

➜ demo go get github.com/rsj217/service
➜ demo tree ../../├── demo
│ └── main.go
└── github.com
└── rsj217
└── service
├── LICENSE
├── README.md
├── api
│ └── api.go
├── http.go
└── rpc.go5 directories, 6 files

从前面包的搜索方式就很容易理解。import "github.com/rsj217/service" go 就从 $GOPATH/src 下搜索，正好能搜索到 github.com/rsj217/service。

进入到 service文件夹内，可以看到就是完整的 git repo 的clone。修改提交后，即使删掉这个包。再使用 go get 也能再次下载。

Why GOPATH

前面我们抛了一个问题：为什么 go 会使用 GOPATH 这样的集中文件夹呢？go 不像 python 有一个中央仓库 PyPI 用来管理存储软件包，以提供给包管理工具 pip 下载。而 python 也不像 go 那样有个本地的 GOPATH 用来搜索软件包。

对于 python 开发者而言，源码怎么管理都无所谓。但是只要想分发软件包，就可以打包然后传到 pypi 即可。想要使用软件包，从 pypi 搜索即可（或从github.com）。

但是go是另外一种开发方式。从一些朋友了解到Google的开发方式。他们本身就有一个中央集中式中心用来管理软件包。使用，构建都从那里获取。因为外人无法访问google的中央，但是这种引用中央的开发模式被保留下来，因此就抽象成本地的GOPATH。

至于软件的分发，就从源代码拉取即可。有名的源代码版本管理无非就是 github 之类。google的做法就是让用户自己维护一个在本地类似 pypi 的中央库。

自己怎么维护呢？就是通过 go get 从 github 或者其他类似的网站上获取，然后打包，处理依赖。这样的一个好处就是自己把分散式的 github 开源包进行了本地的集中式处理。处理依赖的时候会比较方便，毕竟本地什么东西都有了。

但是从上面的 case 可以看出，go get 就类似 git clone。即使每次 go get 拉取仓库都是最新的版本。如何处理好版本依赖呢？

在go module之前也有不少解决方案，但是都或多或少有优劣。下面就介绍一下 go module 的使用方式。

go module

go1.12 引入了 go Module，即 go 的软件包都可以声明为 module。同时淡化了GOPATH，之所以说淡化，是因为即使使用1.12版本，用户不用配置GOPATH环境变量，但是它还是以另外一种形式存在。

go1.12 会在用户的 $home 目录下创建一个 go 文件夹作为默认的 GOPATH。

➜ ~ echo $GOPATH

➜ ~ go env | grep GOPATH
GOPATH="/Users/master/go"

虽然引入了 module，但是并没有废弃 go get，go get 还是基于 GOPATH 运作的，并且 go 的开发方式也没有放弃。只是减少了用户的心智负担，但也提升了用户体验。go get 会将远程的软件包 download 在 $home/go/pkg/mod 目录里。

没有了显示的 GOPATH，开发者的项目就不用像之前一样放到 GOPATH/src 下面了。用户可以在任何一个文件创建自己的项目。下面是一个例子:

随意创建一个 demo 文件夹作为项目。使用 mod 命令声明一个 module。然后编写 main.go

➜ demo go mod init demo
go: creating new go.mod: module demo
➜ demo lsgo.mod
➜ demo echo $GOPATH

➜ demo cat go.mod
module demo

go 1.12➜ demo tree
.
├── go.mod
└── main.go0 directories, 2 files
➜ demo less main.go

package main

import ("fmt"// "github.com/rsj217/service")

func main() {fmt.Println("hello world")// api.HandleReq()// api.HandleResp()}

go mod init 会在当前文件夹下创建一个 go.mod 文件，里面声明了当前 module 的名字。以后也可以把相关依赖写在这个文件里，就像 python 的 requirements.txt 文件一样。

编译运行 main.go，会发现项目即使没有 $GOPATH/src 下，也能正常运行。下面把上面的main.go 的注释去掉。再次编译运行

➜ demo go run main.go
go: finding github.com/rsj217/service v1.0.0go: downloading github.com/rsj217/service v1.0.0go: extracting github.com/rsj217/service v1.0.0hello world
api - http.go Handle Request
api -- rpc.go Handle Response
➜ demo cat go.mod
module demo

go 1.12require github.com/rsj217/service v1.0.0 // indirect➜ demo go list -m all
demo
github.com/rsj217/service v1.0.0

go 会检测 main.go 里的 import 语句。并尝试根据 go.mod 的依赖引用关系导入三方包。如果发现本地cache没有，就会从远程拉取。就像是 go get。当 go module下载了远程包后，同时会自动更新 go.mod 。

如上面就追加了 require github.com/rsj217/service v1.0.0 // indirect 这样一句。require 指令后跟软件包名和版本号。

对于 demo，其包名为 module demo 里声明的 demo，对于 service，当前不是一个 module，因此其包名是 github.com/rsj217/service。版本号就是 repo 的 tag。

软件包被缓存在 $home/go/pkg/mod 目录里， mod 目录就像之前的 src 一样。里面也有 github.com 目录。最终可以看到在 github.com/rsj217/ 文件下有 service@v1.0.0文件夹，里面正好就是之前 service 的代码

➜ service@v1.0.0 pwd/Users/master/go/pkg/mod/github.com/rsj217/service@v1.0.0➜ service@v1.0.0 tree
.
├── LICENSE
├── README.md
├── api
│ └── api.go
├── http.go
└── rpc.go1 directory, 5 files

service@v1.0.0 与之前的 go get clone 的service 项目不一样。前者只下载了版本号为 1.0.0 的仓库（如果没有打tag，就是指定的某个commit），而后者是整个 repo 的clone。由此可见，go module 是可以精确的拉取目标版本。

语义化版本

go module 同时引入了 semver (Semantic Versioning)。它定义的版本号格式是：

vMAJOR.MINOR.PATCH

v：表示版本
MAJOR：主版本，通常是大版本升级，导致向前不兼容
MINOR：次版本，通常是向下兼容的 feture
PATCH：修订版本，如一些bugfix。

下面针对刚才的 service@v1.0.0 升级到1.1.0 版本。通过 git 修改 http.go，然后push一个v1.1.0 的 tag。

v1.0.0

然后使用 go get -u 升级版本

➜ demo go get -u
go: finding github.com/rsj217/service v1.1.0go: downloading github.com/rsj217/service v1.1.0go: extracting github.com/rsj217/service v1.1.0

要升级或降级到更具体的版本，go get 允许通过在包参数中添加 @version 后缀搜索。如 go get service@v1.0.0，go get service@dsa1ewr，或者 go get service@<v1.3.2。
使用 go get -u 会把所依赖的次级包也跟着升级，原因参考golang modules问题的理解与踩坑记
)，不是特别友好。比较好的方式是指定版本的具体包或者修改 go.mod 文件。这里没有次级依赖，为了方便，下面的更新也使用了 go get -u

可以看到，mod 里多了一个 service@v1.2.0 的文件夹包，go.mod 也引用了 v1.2.0的软件。运行main.go ，也输出了 1.1.0 升级后的内容。

大版本升级

升级 MINOR 和 PATCH 都比较简单，升级 MAJOR 稍微复杂一点点。再次修改service 仓库，然后打一个 V2.1.0 的tag。推送到远程分支。再使用go get -u 升级

➜ demo go get -u
go: downloading github.com/rsj217/service v2.1.0+incompatible
go: extracting github.com/rsj217/service v2.1.0+incompatible
➜ demo go list -m all
demo
github.com/rsj217/service v2.1.0+incompatible
➜ demo cat go.mod
module demo

go 1.12require github.com/rsj217/service v2.1.0+incompatible

➜ demo go run main.go
hello world
api - http.go Handle Request
v2.1.0api -- rpc.go Handle Response

可以看到，在下载软件包的时候，版本号跟着有一个 incompatible 标记。incompatible 表示是大版本升级，与之前的版本可能不兼容。但是运行main.go的时候，依然可以正确的找到 2.1.0的版本。并且 $home/go 里的软件包也多了一个 service@v2.1.0+incompatible。

旧包升级到 go module

本地的项目 demo 已经使用了 go module 声明，对于其依赖 service，也可以改造成 go module，只需要增加一个 go.mod 文件即可。然后打上一个 v2.2.0的 tag。当然修改 http.go ，以便测试是 v2.2.0 的内容。

然后更新下载依赖

➜ demo go get github.com/rsj217/service@v2.2.0go: finding github.com/rsj217/service v2.2.0go: downloading github.com/rsj217/service v0.0.0-20190508051156-b9ee113ae63e
go: extracting github.com/rsj217/service v0.0.0-20190508051156-b9ee113ae63e

从上面的输出可以看到，因为已经有了v2的版本，就应该在声明 module 的时候加上v2。如果不加，那么go貌似认为 tag 没有打上。不管怎么样，代码库还是下载了。

查看本地的包会发现有之前的好几个版本，其中 v2.2.0 的被命名为 service@v0.0.0-20190508051156-b9ee113ae63e 。因为刚初始化的 module 认为没有打上 tag，对于没有打 tag 的，go.mod 的格式是 pseudo-version。它的含义是v0.0.0-yyyymmddhhmmss-abcdefabcdef

查看所下载的软包

➜ rsj217 lsservice@v0.0.0-20190508051156-b9ee113ae63e service@v1.1.0service@v1.0.0 service@v2.1.0+incompatible

➜ demo cat go.mod
module demo

go 1.12require github.com/rsj217/service v0.0.0-20190508051156-b9ee113ae63e

➜ demo go run main.go
hello world
api - http.go Handle Request
v2.2.0api -- rpc.go Handle Response

从go.mod 和运行效果来看，确实升级到 v2.2.0版本的代码库了。只是go module对于大于 v1 的版本库，其声明的 module 也要加上vMAJOR。

go module 多版本共存

上述的 v2.2.0 没有被 go module 识别，是因为 go.mod 的 module github.com/rsj217/service 没有带上 MAJOR 版本号。将 go.mod 改成 module github.com/rsj217/service/v3，即新的 go.mod，然后再打上一个v3.0.0 的版本再更新。

由于（假设） v3.0.0 与之前的版本都不兼容，但是demo项目又同时需要两个版本的包，此时就是 go module 比之前 go get 方式优越了。

正如 v3.0.0 的 go.mod 加上了版本号，因此对于使用者而言，其实可以理解为是不同命名空间包。就像之前 service 下的 api 和 service/api 下的 api 一样。需要用别名区别。

修改 go.mod 增加两个版本的包。v2.2.0 和 v3.0.0

➜ demo cat go.mod
module demo

go 1.12require (
github.com/rsj217/service v0.0.0-20190508051156-b9ee113ae63e
github.com/rsj217/service/v3 v3.0.0)

➜ demo cat main.go
package main

import ("fmt""github.com/rsj217/service" // 使用 v2.2.0 的包apiv3 "github.com/rsj217/service/v3" // 使用 v3.0.0 的包)

func main() {fmt.Println("hello world")
api.HandleReq()
api.HandleResp()
apiv3.HandleReq()
}


➜ demo go run main.go
go: downloading github.com/rsj217/service/v3 v3.0.0go: extracting github.com/rsj217/service/v3 v3.0.0hello world
api - http.go Handle Request
v2.2.0api -- rpc.go Handle Response
api - http.go Handle Request
v3.0.0

可以看到 main.go 里的 import 语句，显示的区分了 v2 版本和 v3 版本。查看 home/go 下面的目录，会发现多了一个 service 文件夹，里面放了一个 v3 版本的包。

不管怎样，go module 通过 vMAJOR 让用户可以同时使用多个版本的软件包。但是需要修改使用者的代码，还是略麻烦。不过既然进行了向前不兼容，又得保证旧代码正常work，想来也没有更好的办法。

本地包

开源社区的最大好处就是共享智慧。可是实际开发中，开源的包也未必都十分可靠。通常可以提 PR 提 ISSUE 参与改进。但是原作者要是不维护就得需要自己 fork 修改。

还有一些涉及到商业方向的代码包，总不能扔到 github 上开源。因此本地构建也是一个需求。例如上面的 v3.0.0 有类似的 bug。可以在本地修改一个版本，然后通过 go module 的 replace 指令替换到 github 上的包。

➜ demo go mod vendor
➜ demo lsgo.mod go.sum main.go vendor
➜ demo cd vendor
➜ vendor tree
.
├── github.com
│ └── rsj217
│ └── service
│ ├── LICENSE
│ ├── README.md
│ ├── go.mod
│ ├── http.go
│ ├── rpc.go
│ └── v3
│ ├── LICENSE
│ ├── README.md
│ ├── go.mod
│ ├── http.go
│ └── rpc.go
└── modules.txt4 directories, 11 files

使用 go vendor，可以将依赖包copy到项目的 vendor文件下。如上面的例子 vendor下的结构和之前的 GOPATH/src home/go 类似。修改 v3 下的 http.go

➜ v3 cat http.go
package api

import "fmt"func HandleReq(){fmt.Println("api - http.go Handle Request")fmt.Println(" vendor v3.0.0")
}

然后修改 go.mod ，添加 replace指令

➜ demo cat go.mod
module demo

go 1.12require (
github.com/rsj217/service v0.0.0-20190508051156-b9ee113ae63e
github.com/rsj217/service/v3 v3.0.0)

replace github.com/rsj217/service/v3 v3.0.0 => ./vendor/github.com/rsj217/service/v3

➜ demo go run main.go
hello world
api - http.go Handle Request
v2.2.0api -- rpc.go Handle Response
api - http.go Handle Request
vendor v3.0.0➜ demo

从运行结果可以看到，go module找到了本地的 vendor里的版本。如果一开始 service项目就不想开源。声明其module 就可以不加 github.com 。可以直接声明成一个 service module。最好是使用git init 初始化为本地的 repo。然后使用 replace 指令，将 service 包指定到本地某个目录。

除了针对大版本声明 module 需要 vMARJOR，其他时候，module 的名字是否加 github.com/username 并不是硬性要求，毕竟有 replace 大法。

依赖关系

通过上面从一个普通的 go package 的改造成 go module 的例子。可以看到 go 在包管理工具上的努力。尤其是对不兼容版本的支持，还是有一定防范。但是需要改源文件，还是略显不够优雅。另外，go mod还提供了一些了命令。如 go list 可以看出当前 module 的依赖

➜ demo go list -m -json all
{"Path": "demo","Main": true,"Dir": "/Users/master/demo","GoMod": "/Users/master/demo/go.mod","GoVersion": "1.12"}
{"Path": "github.com/rsj217/service","Version": "v0.0.0-20190508051156-b9ee113ae63e","Time": "2019-05-08T05:11:56Z","Dir": "/Users/master/go/pkg/mod/github.com/rsj217/service@v0.0.0-20190508051156-b9ee113ae63e","GoMod": "/Users/master/go/pkg/mod/cache/download/github.com/rsj217/service/@v/v0.0.0-20190508051156-b9ee113ae63e.mod","GoVersion": "1.12"}
{"Path": "github.com/rsj217/service/v3","Version": "v3.0.0","Replace": {"Path": "./vendor/github.com/rsj217/service/v3","Dir": "/Users/master/demo/vendor/github.com/rsj217/service/v3","GoVersion": "1.12"},"Dir": "/Users/master/demo/vendor/github.com/rsj217/service/v3","GoMod": "/Users/master/demo/vendor/github.com/rsj217/service/v3/go.mod","GoVersion": "1.12"}

从上面的 json 可以看出，demo 项目依赖 github.com/rsj217/service 的 "v0.0.0-20190508051156-b9ee113ae63e" 版本，即 git 的（v2.2.0）。还依赖 github.com/rsj217/service/v3 的 v3.0.0 也是 git 的（v3.0.0）

总结

golang 1.12 正式发布了 go module 特性。go module 作为官方的包管理解决方案。既然针对旧软件包能work，也可以将旧软件包升级为 go module。

go module 淡化了 GOPATH 的概念。用户不设置 GOPATH，golang会自动在 home/go/pkg/mod 中，并且可以存储多个版本的包。

为了管理包依赖，go module 引入了 go.mod文件，通过 module 指令声明一个module，通过 require 指定依赖，通过 replace 替换依赖。

同时软件包的版本提供了一个版本格式，并且针对大于 v1 的软件包，声明的module 也需要加上vMarjor。

总而言之，go module在不对原有的包管理带来破坏的情况下，引入了新的workflow，只要遵循这些约定，还是可以轻松的解决日常开发的包管理问题。

【Go】理解包、模块

Tue, 31 Mar 2026 10:19:58 +0800

Go 作为一门成熟的语言，有着详尽的文档。但官方的入门文档过于简单，而参考手册又过于丰富，让新人觉得无从着手。

本文由浅入深地解释清楚：在Go语言中，包（package）是代码组织和重用的基本单位，而模块（module）是控制版本和管理依赖的单元。

本文主要受众应该是：有一定Go使用经验，但是在使用包和模块时还偶有迷惑的同学。

一、什么是包、模块

Go 语言官方文档 How to Write Go Code 对包和模块有比较清晰的介绍。

A package is a collection of source files in the same directory that are compiled together.
A module is a collection of related Go packages that are released together.

当然，远不止这两句话。我们已经熟悉一些点，我这里先列举一下：

一个文件夹对应着一个包，包名是文件夹的路径名，而非声明的 package xxxx，包名通常与目录名一致
同一个包中所有 .go 文件，声明的package xxx不能冲突，都可以相互访问变量、函数、结构等
import 导入的是包名
一个包中可以有多个 init()，会在被导入的时候执行。同一个文件中的多个 init()按顺序执行，不同文件中的多个不保证执行顺序。

模块也是文件夹，有个 go.mod 文件，包含一个或多个包
模块有模块路径 (module path)，通常是个仓库地址

一个简单的、典型的 Go 项目的目录结构和文件可能像下边这样：

接下来，将详细地说明：在Go语言中，包（Package）是代码组织和重用的基本单位，而模块是控制版本和管理依赖的单元。

还包括一些可能大家不太清楚的问题解释，比如：子模块、版本编号规则与发布、go.sum的作用、indirect 依赖模块、包的循环引入、模块的版本冲突、仓库地址和模块路径不一致等问题。

二、包 - 组织代码和复用的单元

A package is a source code organization unit: it defines a context for identifier names, determining the visibility of an identifier within the package. Every package is associated with a directory of the same name. All the files in a package’s directory must declare the same package name. – Go doc

包是源代码的组织单位：它为标识符名称定义了一个上下文，决定了一个标识符在包内的可见性。每个包都与一个同名的目录关联。包目录中的所有文件必须声明相同的包名。

这是一种组织和封装代码的方式。这种方式使得代码结构清晰，易于理解和维护。

更直白的翻译一下：Go 程序组织代码的基本单位是包（package），就像说生物体的基本组成单位是细胞一样。

包为什么是代码组织的基本单位？接下来从命名空间、封装以及代码复用等方面聊聊。

2.1 命名空间

命名空间(namespace) 是一个用于管理变量名的区域范围，要保证同一个命名空间内的变量名（更确切的应该是标识符名称）是唯一的。

Go语言中，每个包都会提供一个独立的命名空间。这意味着在不同的包中，你可以使用相同的标识符名称，而不会产生冲突。而在同一个包内，不同文件之间中定义的变量、方法，都可以直接进行访问。

避免命名冲突极大地提高了代码的可维护性。特别是在大型程序中，不同模块或库很可能会使用相同的变量名、函数名。

2.2 封装

封装是将数据和操作这些数据的方法组合在一起的机制，其主要目标是隐藏对象的内部状态和实现细节，只暴露必要的接口给外部使用者。

封装通常用于面向对象编程（OOP）中，可以通过类和对象来实现。而 Go 语言并不是传统意义上的面向对象编程语言，但其通过使用包也实现了良好的封装。

在一个包内部，类型、变量、常量和函数分为耳熟能详的两类：

可导出（Exported）：大写字母开头，可以被包外的代码访问
非可导出（Unexported）：以小写字母开头，只能在包内访问

这种方式提供了良好的封装性，可以隐藏实现细节，只暴露必要的接口给其他包。而通过大小写字母来开头的方式来实现，比一些复杂的类的 public，extern 之类的方式，更简洁明了。

2.3 代码复用

代码复用是软件开发中的一个关键实践，通过代码复用，可以提高开发效率、减少错误、提高代码质量和维护性。

Go语言的包也是代码重用的基本单位。通过 import 语句可以引入其他包。

标准库：Go语言提供了丰富的标准库，这些标准库以包的形式组织，涵盖了常见的功能模块，如I/O操作、字符串处理、网络编程等。
自定义包：开发者可以创建自定义包，在一个仓库/模块中，创建多个包，包之间可以引入
第三方包：Go语言生态系统中有大量第三方包，通过 go get 命令可以轻松获取和使用这些包。

通过 go get -u 命令+包的路径，可以从指定的远程仓库中获取包，并将其安装到本地的Go环境中。比如：

2.4 其他语言类似的概念

Go语言中的包概念在其他语言中也有类似的概念，主要用于组织和管理代码，但是不完全相同。接下来，以我用过的几类语言来比较一下。

Python

在Python中，有 模块(module) 和 包(package) 的概念。

模块是一个包含Python定义和语句的文件，一个文件有独立的命名空间。

包是一个包含多个模块的目录，其中有个__init__.py 文件，正是这个文件，使得包在导入时，也被视为一个特殊的模块。

Python的包可以用来组织模块，类似于Go的包。

C++

C++好像没有直接对应Go的包的概念，但是C++有显式的 namespace 支持。

命名空间非常灵活，可以跨越不同的目录和文件，还支持嵌套命名空间来进一步组织代码。换句话说，开发者需要自己来组织命名空间。

此外，C++的头文件和源文件的组织方式也可以看作是一种代码管理的方式，虽然它不像Go的包那样强大。

Java

因为之前开发实时计算任务，也有用到 Java 和 Scala。

Java的代码组织单元是类（Class）。每个 Java 源文件通常只包含一个公共类，该文件名与公共类名相同，并以 .java 结尾。这种文件级别的组织方式使得Java程序易于管理和维护。

Java中，包（Package）用于组织类、接口以及其他子包，提供了命名空间的管理机制，可以避免命名冲突。包名使用点分隔符来分级，例如 java.util，其中 java 是顶级包，util 是它的子包。

看上去跟 Go 的导入是不是还有点像？

import com.google.gson.Gson;

三、模块 - 依赖管理和版本控制的单元

相对于包是组织代码的基本单元，模块则是管理依赖和版本控制的基本单元，两者的目标是不同的。

关于模块的使用，Go 官方一系列文档提供了详细的介绍，包括版本号如何定义、如何发布、如何维护依赖等等。

既然有了包这个概念，为什么还需要模块？

之所以会模块通常包含了多个包，最主要可能是实践中，复用代码的粒度会比较细，而版本管理的没有那么必要那么细。另外，模块通常要实现一系列的功能，很少有一个项目会只有一个包就可以完成的（虽然有些包和模块确实在一个文件夹中，也有的模块确实只有根目录一个包）。

3.1 版本管理功能

Go 版本号和发布模块两个文档简明地介绍如何发布模块版本。

语义化版本

文档里我们会看到 semantic version，这个我们之前有提到过 语义化版本，版本号包括：不兼容的 API 修改的主版本号、新增向下兼容特性的次版本号、新增向下兼容的补丁的修订版本号。最后还可以有个预发布版本号，通过横线连接一个字符串，意思是还没有到达前边的标准版本。

语义化版本的好处，是能让我们一眼就能看出哪些版本更新，哪些版本之间是兼容的。

比如以下版本之间，越往右版本越高（越新）。

1.0.0-alpha < 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1

通过 git tag 标记版本

Go 的模块版本，依赖于版本控制仓库，可以使用 Git，也支持 Subversion, Mercurial, Bazaar, Fossil 等其他版本控制的形式。

因为我们主要使用 Git，接下来主要介绍基于 Git 的版本发布。Go 模块路径，也就是我们在调用 go mod init 的时候后边加的路径，通常是一个仓库名。这样做有两个功能：

可以唯一标识一个模块
可以指示下载地址

这里跳过 git init/add 等前序操作，到 git commit 之后使用 git tag，比如我们要发布第一个版本 v0.1.0：

git commit -m "Init: v0.1.0" git tag v0.1.0 git push origin v0.1.0

推送到远端仓库之后，我们可以通过 go list 指令查看模块的可用版本：

✗ go list -m git.woa.com/jasonzxpan/m1 git.woa.com/jasonzxpan/m1 v0.1.0

这里再提一下前面提到的 预发布版本号：如果我们提供的包/模块，不是稳定的版本，但同时也需要打 tag 的话，就可以使用像 v0.1.0-beta.1 这样的预发布版本号。这种版本不必保证版本的稳定性。

如果我们做了变动需要发布，可以再根据前面的【语义化版本】的规则，打上新的 tag，比如 v0.1.1 并推送到仓库。

3.2 使用第三方包和模块

Go 语言的标准库是随着 Go 版本发布的，因此在编写Go代码时，引入标准库的包（例如 import "fmt"）不需要指定具体的版本号。

你可以通过 IDE 点到源代码查看中，在Mac上，默认安装的 Go 语言通常位于 /usr/local/opt/go/libexec 目录下。这里边有 VERSION 文件，标识当前安装的 Go 语言版本及其标准库的版本信息。

指定版本的依赖

本节中，第三方包和模块是指除了模块自身中的包与标准库之外的包和模块。

我们上边创建的模块 git.woa.com/jasonzxpan/m1，假设其中有一个包 p1，其中有个导出函数 M1P1F1()。

我们再创建一个模块 go mod init git.woa.com/jasonzxpan/m2，要使用这个 m1/p1 的包，可以直接在文件中引入。

package main import (     m1p1 "git.woa.com/jasonzxpan/m1/p1" ) func main() {     m1p1.M1P1F1() }

这时候可以直接通过 go mod tidy 让其自己分析依赖，并且获得最新版本的包。

➜  m2 git:(master) ✗ go mod tidy go: finding module for package git.woa.com/jasonzxpan/m1/p1 go: downloading git.woa.com/jasonzxpan/m1 v0.1.1 go: found git.woa.com/jasonzxpan/m1/p1 in git.woa.com/jasonzxpan/m1 v0.1.1

go get 可以让我们获得指定版本的模块：

go get git.woa.com/jasonzxpan/m1/p1@v0.1.0

如果要更新某个模块，也可以用 go get -u 来更新：

默认拉取最新的go get -u example.com/mypackage，但是要先删掉 go.mod 中对应的 require 之前指定的版本。
也可以直接指定 latest 版本，go get -u example.com/mypackage@latest

替换模块依赖 - `repalce`

有些场景，我们需要替换掉依赖远端的第三方库：

依赖自己写的模块，没有稳定的版本，在开发过程中还需要不断调整
依赖别人写的模块，但是需要调试或者增加一些特性，可以从源仓库 fork，然后在本地开发，然后push到自己的仓库

无论是哪种场景，大概的操作流程都类似：

将第三方模块，clone 到本地
通过 replace 的方式，修改 go.mod 中的依赖，替换成本地目录
开发过程、修改第三方模块；完成开发，推送第三方模块
去掉 replace 到本地的依赖：

依赖自己模块的，去掉replace，指向正式版本
依赖 fork 自别人仓库的，通过 replace 的方式，指向自己fork的版本

仍以上边 m2 依赖 m1 模块为例，我们可以直接通过 replace，在开发过程中使用本地的 m1：

go mod edit -replace=git.woa.com/jasonzxpan/m1@v0.1.1=../m1

类似地，可以替换成远端的仓库：

go mod edit -replace=git.code.oa.com/trpc-go/trpc-go=git.woa.com/trpc-go/trpc-go@v0.15.0

其实，还有另外一种常见场景，就是后边会提到的多个模块的，可能会有直接 replace xxx => ../.. 的操作，比如，grpc-go 子模块 grpc-go/examples 中的 go.mod

为什么需要间接依赖

如果我们项目复杂点，打开 go.mod 文件，会看到一些信息。除了 module_path、Go 版本以及直接依赖的模块和版本信息之外，还有另外一个间接依赖。与直接依赖类似，也是模块路径和版本号，区别在于最后有个 // indirect 的注释，其实上节图 grpc-go/examples 中就有。

为了简明，我们再以被广泛使用的 uber 日志库 zap 的 go.mod 为例，可以看到有三个间接依赖的模块：

我们可以理解间接依赖是指：如果我们直接使用 moduleA 中的包，而 moduleA 依赖 moduleB，那么 moduleB 就是我们模块的间接依赖。

是不是 go.mod 会将所有间接依赖都列出来？答案是否定的。以上边的依赖关系来说，只有 moduleA 的 go.mod 文件中，没有指定 moduleB 的版本，才会在我们的自己的模块 go.mod 文件中指定间接依赖的版本。如果 moduleA 已经指定了 moduleB 的版本，就不需要指定了。

运行 go mod tidy 命令来更新你的go.mod文件，这个命令会添加缺失的模块，删除无用的模块，以及更新间接依赖的版本。

那究竟为什么需要指定间接依赖的版本呢？

记录间接依赖的版本信息是为了确保项目的构建稳定性和可重现性。因为间接依赖的版本可能会影响直接依赖模块的行为和版本兼容性。只有记录清楚所有依赖的版本，才能够重现完全相同的依赖版本树，从而避免由于间接依赖的不一致而导致的问题。

3.3 单仓库多模块

Go 的官方文档中，有子包 sub-package 的表述，但是没有 sub-module 的表述。

但我们能看到部分项目中，可能存在多个 go.mod 的情况：模块中还有模块的，其实外层目录是一个模块和子目录是另外一个模块，并非真正意义上的子模块。

在 How to Write Go Code 的文档中，有这么一段话，也描述包、模块、仓库的关系：

A Go repository typically contains only one module, located at the root of the repository. A file named go.mod there declares the module path: the import path prefix for all packages within the module.
The module contains the packages in the directory containing its go.mod file as well as subdirectories of that directory, up to the next subdirectory containing another go.mod file (if any).

但是，上边提到了模块包含当前目录、以及所有子目录的中的包。但是如果一个子目录包含另外一个 go.mod 文件，则这个目录中及其子目录的包，不属于当前模块。

多模块的项目

我们确实见到过类似的项目，比如 trpc-go和 grpc-go 的仓库中都有多个 go.mod 文件，这就意味着这些仓库中有多个模块。

这些子模块大多是依赖顶层模块，或者项目的一些工具。我们以 grpc-go 仓库为例：

grpc-go 是 gRPC Go 项目的根模块，Go版本的gRPC 实现都在这模块中
grpc-go/cmd/protoc-gen-go-grpc 是使用 gRPC Go 时，要通过 protoc 将 .proto文件转换成Go语言库，其具体使用的工具就是这个 protoc-gen-go-grpc。该模块本身只有根目录那一个包
grpc-go/examples 是 gRPC Go 的示例模块，其中有三个子包

为什么要多模块

多个模块有关联性，但是又不那么强烈的耦合的场景，就适合拆分成多个模块。

比如 grpc-go/examples 模块，只是 grpc-go 的示例，单独放个仓库过于简单，没有必要。而如果直接放在 grpc-go 模块中作为一个包，不加 go.mod 单独一个模块，又会对 grpc-go 包的纯洁性有影响——用户不会依赖 examples 包。

另外，这样划分，客观上还带来了一些好处：

依赖管理是独立的：这里的 examples 依赖等不会影响到外层 grpc-go 模块的依赖；而examples 中的依赖，也可以依赖 grpc-go 中没有的或者版本不一样的模块
版本管理是独立的：这里examples直接没有打版本的需要，我们看另外一个 protoc-gen-go-grpc 的版本情况。

我们可以通过 go list -m -versions 来看两个模块的版本信息，可以看到这个工具只有到6个版本，而根模块有到 v1.66.0-dev 等几十个版本：

如何对不同的模块不同的版本？在官方文档 Managing module source 中有介绍。根目录直接打 v1.2.1，子目录打标签时候带上目录即可。比如我们看到 protoc-gen-go-grpc 对应的版本在仓库中有打对应的 tag 如 cmd/protoc-gen-go-grpc/v1.1.0：

可以上下层次，也可以两个目录并行，比如官方介绍的：

四、其他疑惑

4.1 go.sum 里边有什么

在官方文档管理依赖一文中，有这样一段描述：

When you add dependencies, Go tools also create a go.sum file that contains checksums of modules you depend on. Go uses this to verify the integrity of downloaded module files, especially for other developers working on your project.
Include the go.mod and go.sum files in your repository with your code.

当添加依赖（创建 go.mod）的同时，也会创建 go.sum 文件。go.sum 记录了项目中使用的每个依赖模块的模块路径（module path）以及对应的校验和，用于验证依赖模块在下载时的完整性。go get 和 go mod tidy 的时候，在更新 go.mod 的同时，也会更新 go.sum。

go.mod 文件定义了项目的模块依赖关系和版本约束，而 go.sum 文件则提供了依赖模块的安全性保证，确保每次构建时都能使用正确的依赖版本，可以防止恶意或不良网络条件下的中间人攻击。

go.sum 和 go.mod 一样，都要加入到版本控制中。

4.2 依赖下载到本地，存放在哪里

Go Modules 会将依赖下载到本地的模块缓存目录，默认情况下，这个目录是 $GOPATH/pkg/mod。如果没有设置 GOPATH 环境变量，默认的 GOPATH 是用户主目录下的 go 目录：

如果缓存的模块太多导致磁盘占用太大，或者缓存的模块出现问题导致构建失败，这些情形下，我们可以调用 go clean -modcache 来清理模块缓存，这会删除 $GOPATH/pkg/mod 目录中的所有内容。

对比之下还有 go clean 指令，他只是用来清理项目自身构建的二进制文件、测试缓存文件、临时文件等。

4.3 如果仓库地址和模块路径不一样怎么办？

虽然仓库地址是 github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc，但是他模块路径自己写的是 google.golang.org/grpc/cmd/protoc-gen-go-grpc，这两者是不一致的，到时候会报错：

✗ go get github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc go: downloading github.com/grpc/grpc-go v1.65.0 go: downloading github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc v1.4.0 go: github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc@upgrade (v1.4.0) requires github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc@v1.4.0: parsing go.mod: module declares its path as: google.golang.org/grpc/cmd/protoc-gen-go-grpc         but was required as: github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc

你需要在你的go.mod文件中添加一个 replace 指令，将 github.com 模块名替换为google.golang.org 开头的模块名。例如：

replace github.com/grpc/grpc-go/cmd/protoc-gen-go-grpc => google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.4.0

比如我们之前的仓库地址是 git.code.oa.com, 之后迁移到了 git.woa.com，那很多之前很多代码仓库的 module path 都是以 git.code.oa.com 开头的。这时候如果直接 go get git.woa.com/trpc/trpc-go，可能会遇到跟上边一样的错误：

✗ go get git.woa.com/trpc-go/trpc-go go: git.woa.com/trpc-go/trpc-go@upgrade (v0.18.1) requires git.woa.com/trpc-go/trpc-go@v0.18.1: parsing go.mod: module declares its path as: git.code.oa.com/trpc-go/trpc-go         but was required as: git.woa.com/trpc-go/trpc-go

而如果直接使用老仓库地址，go get git.code.oa.com/trpc-go/trpc-go 可能老的服务已经停止了，无法获得对应的包。除了使用上边replace 之外，还可以使用公司内提供的 GOPROXY：

问：为什么 goproxy.woa.com 能去 git 下载到 import path 为 git.code.oa.com 的库？
答：是因为 goproxy.woa.com 服务 git clone 时会自动将 git.code.oa.com 替换为 git.woa.com

4.4 导入的多个包依赖同一模块，其版本冲突如何处理

对于版本冲突，Go Modules 使用了一种称为“最小版本选择”（Minimal Version Selection, MVS）的机制。MVS 机制确保在构建过程中使用的每个模块的版本是所有依赖项中要求的最低版本。

考虑下图中的示例。主模块需要版本 1.2 或更高版本的模块 A，以及版本 1.2 或更高版本的模块 B。A 1.2 和 B 1.2 分别需要 C 1.3 和 C 1.4。

C 1.3 和 C 1.4 都需要 D 1.2。所以根据 MVS 的机制，加粗黑框中的模块将会被选中。

这里你可能有疑问，C 的两个冲突版本 1.3 和 1.4 中最小的不是1.3吗？为什么选择1.4。MVS 不是要找依赖的最低版本，而是找满足所有模块依赖的最低版本，比如 B 1.2 如果使用到了 C 1.4 中的新增接口，那么 C 1.3 是不能满足 B 1.2 的需求的。所以，所有依赖项对 C 模块依赖的最低版本是 1.4。

B 和 D 的更高版本可用，但 MVS 不会选择它们，因为没有任何内容需要它们

如果发生依赖的冲突无法解决，可能会涉及到升级依赖、降级依赖、替代、排除等方法来解决

名言一则

Sat, 14 Mar 2026 09:18:14 +0800

伟大的人不是生下来就伟大的，而是在成长过程中显示其伟大的

实质的大道理往往很简洁

Fri, 13 Feb 2026 20:00:15 +0800

实质的大道理都是很简单，如果如果讲的一大堆不知道说啥，那么这个作者肯定是自己不清楚，要不是为了凑字数要不是为了赚稿费。

原理到要一针见血地说出来那样才是一个技术人员或者一个管理者应该做到的事情

npm install卡住出现npm WARN old lockfile解决办法

Mon, 20 Oct 2025 11:23:34 +0800

问题描述：

npm报错：npm install 出现"npm WARN old lockfile"

解决办法：

第一步：手动删掉 node_modules、package-lock.json 文件

第二步：更换 npm 源

npmconfig set registry=https://registry.npmmirror.com

第三步：输入npm install即可（那两个文件会被重新下载）

npm install

就成功啦！

go get 拉取第三方包过慢、卡住解决方案

Thu, 09 Oct 2025 15:50:25 +0800

问题

由于某种不可抗拒力量，go get 在国内下载特别慢，

解决方案

代理镜像拉取

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.io,direct# 设置不走 proxy 的私有仓库，多个用逗号相隔（可选）go env -w GOPRIVATE=*.corp.example.com# 设置不走 proxy 的私有组织（可选）go env -w GOPRIVATE=example.com/org_name

国内镜像

收集了几个代理地址：

win 下

go env -w GO111MODULE=on

# https://mirrors.aliyun.com/goproxy/ 为例go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/

macOS 或 Linux

export GO111MODULE=on
export GOPROXY=https://mirrors.aliyun.com/goproxy/

通过 GitHub 镜像项目下载

golang在github上建立了一个镜像库，如https://github.com/golang/net就对应是 https://golang.org/x/net的镜像库。要下载golang.org/x/net包，可以在本地创建包的目录后使用git clone来拉取相应包的源代码文件，具体操作如下：

mkdir -p $GOPATH/src/golang.org/x
cd $GOPATH/src/golang.org/x
git clone https://github.com/golang/net.git

效果

这里用的是阿里云镜像，没有修改镜像前，拉半天都没有反应，

修改镜像后，

二七九九笔记

golang学习路线总结

基础篇

提升篇

应用篇

Golang Package 与 Module 简介

【Go】理解包、模块

一、什么是包、模块

二、包 - 组织代码和复用的单元

2.1 命名空间

2.2 封装

2.3 代码复用

2.4 其他语言类似的概念

Python

C++

Java

三、模块 - 依赖管理和版本控制的单元

3.1 版本管理功能

语义化版本

通过 git tag 标记版本

3.2 使用第三方包和模块

指定版本的依赖

替换模块依赖 - repalce

为什么需要间接依赖

3.3 单仓库多模块

多模块的项目

为什么要多模块

四、其他疑惑

4.1 go.sum 里边有什么

4.2 依赖下载到本地，存放在哪里

4.3 如果仓库地址和模块路径不一样怎么办？

4.4 导入的多个包依赖同一模块，其版本冲突如何处理

名言一则

实质的大道理往往很简洁

npm install卡住出现npm WARN old lockfile解决办法

问题描述：

解决办法：

go get 拉取第三方包过慢、卡住解决方案

问题

解决方案

代理镜像拉取

国内镜像

win 下

macOS 或 Linux

通过 GitHub 镜像项目下载

效果

替换模块依赖 - `repalce`