本文永久链接 – https://tonybai.com/2024/04/09/choose-the-right-go-module-path

最近我在查看项目代码时，注意到有人在go.mod文件中将module path写为com.example.foo了。根据这个写法，相信屏幕前的读者也可以推断出这位开发人员可能是从Java阵营转到Go的。实际开发中可能有很多开发者会使用类似的内容作为module path，但这显然不是Go的推荐写法或惯用法。

在这篇简短的文章中，我就来介绍一下module path对Go源码构建、包导入路径以及开发协作的影响，以及符合惯例的module path应该是什么样子的。

我们先来复习一下什么是Go module path。

1. 什么是module path

在Go语言中，module path（模块路径）是指在Go开发中用来标识和定位模块的唯一字符串，用于指定在远程仓库或本地文件系统中存储模块代码的位置。

module path在go.mod文件中定义，比如下面这个示例：

// go.mod
module github.com/user/module

go 1.21.1

我们看到：一个典型的模块路径是一个URL格式字符串，可能是类似于github.com/user/module的形式，其中github.com/user/module就是module path。

在Go语言中，模块（module）是一种组织和管理代码的方式，也是Go代码版本管理的基本单元，我们可以在模块路径中包含主版本信息，比如：

// go.mod
module github.com/user/module/v2

go 1.21.1

这表明该模块为v2版本，与前面的github.com/user/module是不向后兼容的两个模块。模块的使用者可以同时导入这两个不兼容的模块下的包，比如：

import (
    "github.com/user/module/foo"
    foov2 "github.com/user/module/v2/foo"
)

那么module path的选取和使用，对Go开发有何影响呢？我们继续向下看。

2. module path的影响

2.1 指示Go module网络位置

前面提到过，在Go语言中，我们通常使用模块的存储库地址作为模块路径的基础。这样做的好处是，Go编译器可以直接通过模块路径确定模块在网络上的位置，并从指定的位置下载需要的代码。这使得在使用第三方模块时非常方便，开发者只需要指定模块的路径，Go工具链就能够自动处理依赖关系，下载并编译所需的模块代码。

例如，如果一个模块的路径是github.com/user/module，那么Go工具链（尤其是Go编译器)就会认为该模块的代码存储在GitHub上的user用户下的module仓库中。当Go工具链需要引入该模块时，它会根据这个路径通过goproxy或直接去GitHub上下载相应的代码。

这种基于存储库地址的模块路径设计简化了模块的管理和依赖关系的处理，使得在Go项目中使用第三方模块变得更加方便和可靠。

2.2 对Go包路径的影响

Go module下的包的导入路径为module path+到包所在目录的相对路径，以module path为github.com/user/module的module下的pkg/foo目录下的包为例，foo包的导入路径为github.com/user/module/pkg/foo。

而如果像本文开头那样，使用com.example.foo作为module path，那么foo包的导入路径就变为了com.example.foo/pkg/foo，这显然难以理解，同时，com.example.foo这样的Java模式的字符串也无法指示go module的网络位置。

2.3 对编译的影响

module path对编译的影响体现在两方面：

首先，Go编译时通过module path来查找依赖的模块。如果Go module path不正确或不完整，那么编译可能会失败。非idiomatic的Go module path可能导致编译错误或难以诊断的问题。

其次，module path会影响采用go build默认构建出的二进制文件的名字，比如如果一个module path为github.com/user/mymodule，那么在该module下执行go build（不使用-o命令行标志），默认得到的二进制文件名为mymodule。

但如果module path为com.example.foo，那么得到的二进制文件名就为com.example.foo，这显然不是我们想要的。

2.4 对开发者协作的影响

Go模块路径的命名对开发者之间的协作也有着重要的影响，主要体现在两方面：

• 唯一性和命名空间

模块路径应当保持唯一，以避免与其他模块产生冲突。通常情况下，使用域名作为模块路径的一部分可以确保全球唯一性。在团队内部，也可以基于公司或组织的名称来命名模块路径，以确保模块的唯一性。

• 依赖管理

使用清晰、有意义、可以指示位置和版本的模块路径可以帮助开发者更好地管理依赖关系。当其他开发者在引入你的模块时，他们可以通过模块路径来确定正确的依赖版本，以及如何与你的模块进行集成。

3. 如何选择一个好的module path

通过上面的秒数，其实我们已经可以勾勒出一个好的module path的画像了。当然这也是Go社区的最佳实践。

通常情况下，module path应该基于模块的存储库地址，并使用简短、易于理解的路径。

就像前面提到的那样，如果你的module存储在GitHub上并可公开，那么module path一般是github.com/user/module。

如果你的module公司内部，不能公开的，那么可以使用一个私有的存储库地址，例如：company.com/dept/go/module。

无论公开的，还是私有的，你都可以定制module path，这方面的方案可以参考我之前编写的有关定制Go module的拉取方案。

如果是仅在本地使用的日常练习项目，那么Go module path的使用可以宽松一些，可以无需在乎其对go module网络位置、开发者协作的影响，可使用像demo这样的单个词的module path，仅注意下其对包路径和编译结果的影响即可。

4. 小结

综上，我们看到：Go module path对Go module网络位置、包路径、编译和开发者协作都有重要影响。遵循Go社区的最佳实践，选择一个好的Go module path可以提高代码可读性和可维护性，并简化多人协作，帮助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://gopherdaily.tonybai.com

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

本文永久链接 – https://tonybai.com/2023/10/05/the-official-guide-of-organizing-go-project

长久以来，在Go语言进阶的学习和实践之路上，Go项目目录究竟如何布局一直是困扰大家的一个问题，这是因为Go官方针对这个问题迟迟没有给出说法，更没有提供标准供大家参考。仅有Go语言项目技术负责人Russ Cox在一个开源项目的issue中给出了他关于Go项目结构的最小标准布局的想法。

熟悉我的博客/公众号的读者可能会知道，关于Go项目目录布局，我在以往文章中曾写过多次。在我的纸版书《Go语言精进之路》、极客时间的专栏Go语言第一课以及Go高级工程师训练营中，对Go项目目录组织与布局方式也都有过全面系统地说明。

我虽然很努力为大家答疑，提供的建议也很具参考价值，但这仅是我的个人观点，权威性有限，大家依然期待Go官方的说法。

近期Go官方文档集合中新增了一篇名为“Organizing a Go module”的文档，细读之后，我发现这不就是大家期待已久的Go项目目录布局的官方指南吗！

在这篇文章中，我们就来看看这份官方指南，看看官方推荐的Go项目目录布局是什么样子的。

1. Go项目的类型

我们知道Go项目(project)一般有两类：library和executable。library是以构建库为目的的Go项目，而executable则是以构建二进制可执行文件为目的的Go项目。

“Organizing a Go module”这篇文档也是按照Go项目类型为Gopher提供项目布局建议的。这篇文档将library类的项目叫作package类，executable类的项目叫作command。下面的示意图展示了“Organizing a Go module”这篇文档的说明顺序：

从图中看到，“Organizing a Go module”这篇文档总共给出7种项目的布局建议。接下来，我们就来逐一看一下。

2. 官方版Go项目目录布局指南

2.1 basic package

我们先从package类开始。最简单的package类的Go项目是basic package，下面就是一个basic package类的项目目录布局的示例：

project-root-directory/
├── go.mod
├── modname.go
└── modname_test.go

或

project-root-directory/
├── go.mod
├── modname.go
├── modname_test.go
├── auth.go
├── auth_test.go
├── hash.go
└── hash_test.go

我们看到basic package类项目非常简单，repo下面只有一个导出package，这个package包含一个或多个包源文件。以repo托管在github上为例，如果这个repo的url为github.com/someuser/modname，那么该repo下的module root和导出package的导入路径通常与repo url一致，都为github.com/someuser/modname。

你的代码要依赖该module，直接通过下面import语句便可以将该module导入：

import "github.com/someuser/modname"

注：本文的Go项目目录布局示例均来自或改自“Organizing a Go module”那篇文档。

2.2 basic command

和basic package一样，basic command类项目是以构建可执行二进制程序为目的的Go项目中最简单的一类。下面是basic command类项目的一个示例：

project-root-directory/
├── go.mod
└── main.go

或

project-root-directory/
├── go.mod
├── main.go
├── auth.go
├── auth_test.go
├── hash.go
└── hash_test.go

从示例我们可以看到，basic command类项目的repo下面只可构建出一个可执行文件，main函数放在main.go中，其他源文件也在repo根目录下，并同样放在main包中。

还是以repo托管在github上为例，如果这个repo的url为github.com/someuser/modname，那么我们可以通过下面命令安装这个command的可执行程序：

$go install github.com/someuser/modname@latest

2.3 package with supporting packages

稍复杂或规模稍大的一些package类项目，会将很多功能分拆到supporting packages中，并且通常项目作者是不希望导出这些supporting packages的，这样这些supporting packages便可以不作为暴露的API的一部分，后续重构和优化起来十分方便，对package的用户也是无感的。这样Go官方建议将这些supporting packages放入internal目录。

注：internal目录是Go 1.4版本引入的机制，简单来说放在internal中的包是local的，不能导出到module之外，但module下的某些内部代码可以导入internal下的包。如今一般都会将internal放在项目的根目录下，所以项目下的所有代码都可以导入internal下的包。

下面是一个带有supporting packages的package类项目的目录布局示例：

project-root-directory/
├── go.mod
├── modname.go
├── modname_test.go
└── internal/
    ├── auth/
    │   ├── auth.go
    │   └── auth_test.go
    └── hash/
        ├── hash.go
        └── hash_test.go

modname.go或modname_test.go可以通过下面导入语句使用internal下面的包：

import "github.com/someuser/modname/internal/auth"

2.4 command with supporting packages

有了package with supporting packages的说明后，再来看command with supporting packages就更简单了，下面是一个示例：

project-root-directory/
├── go.mod
├── main.go
└── internal/
    ├── auth/
    │   ├── auth.go
    │   └── auth_test.go
    └── hash/
        ├── hash.go
        └── hash_test.go

和package with supporting packages不同的是，main.go使用的包名为main，这样Go编译器才能将其构建为command。

2.5 multiple packages

作为一个库项目，作者可能要暴露不止一个package，可能是多个packages。这不会给Go项目目录布局带来过多复杂性，我们只需多建立几个导出package的目录就ok了。下面是一个multiple packages的示例：

project-root-directory/
├── go.mod
├── modname.go
├── modname_test.go
├── auth/
│   ├── auth.go
│   ├── auth_test.go
│   └── token/
│       ├── token.go
│       └── token_test.go
├── hash/
│   ├── hash.go
│   └── hash_test.go
└── internal/
    └── trace/
        ├── trace.go
        └── trace_test.go

我们看到这个示例在repo(以托管在github.com/user/modname下为例)顶层放置了多个导出包：

github.com/user/modname
github.com/user/modname/auth
github.com/user/modname/hash

并且顶层的auth目录下还有一个二级的导出包token，其导入路径为：

github.com/user/modname/auth/token

所有这些导出包的supporting packages还是按惯例放在了internal目录下，比如：github.com/user/modname/internal/trace，这些包是local的，不能被该module之外的代码所依赖。

2.6 multiple commands

有multiple packages类型的项目，就会有multiple commands类的项目，下面是一个这类项目的示例：

project-root-directory/
├── go.mod
├── prog1/
│   └── main.go
├── prog2/
│   └── main.go
└── internal/
    └── trace/
        ├── trace.go
        └── trace_test.go

这个示例将每个command放置在一个单独的目录下(比如prog1、prog2等)，supporting packages和之前的建议一样，统一放到internal下面。这样我们可以通过下面步骤来编译command：

$go build github.com/someuser/modname/prog1
$go build github.com/someuser/modname/prog2

command的用户通过下面步骤可以安装这些命令：

$go install github.com/someuser/modname/prog1@latest
$go install github.com/someuser/modname/prog2@latest

2.7 multiple packages and commands

最后我们来看看最复杂的一种项目类型：multiple packages and commands，即在同一个项目下面，既有多个可导出的packages，又有多个commands。下面是一个此类复杂项目的示例：

project-root-directory/
├── go.mod
├── modname.go
├── modname_test.go
├── auth/
│   ├── auth.go
│   ├── auth_test.go
│   └── token/
│       ├── token.go
│       └── token_test.go
├── hash/
│   ├── hash.go
│   └── hash_test.go
├── internal/
│       └── trace/
│           ├── trace.go
│           └── trace_test.go
└── cmd/
    ├── prog1/
    │   └── main.go
    └── prog2/
        └── main.go

我们看到：为了区分导出package和command，这个示例增加了一个专门用来存放command的cmd目录，prog1和prog2两个command都放在这个目录下。这也是Go语言的一个惯例。

这样，这个示例项目既导出了下面的包：

github.com/user/modname
github.com/user/modname/auth
github.com/user/modname/hash

又包含了两个可安装使用的command，用户按下面步骤安装即可：

$go install github.com/someuser/modname/cmd/prog1@latest
$go install github.com/someuser/modname/cmd/prog2@latest

3. 小结

经过对“Organizing a Go module”的文档这篇Go官方项目目录布局指南的学习，我发现指南中的建议与我个人在以往文章、书和专栏中对Go项目目录布局的建议非常相近，几乎一致，唯独不同的是在pkg目录的使用上。

在multiple packages类型项目中，如果要导出的package非常多，那么项目顶层目下会有大量的目录，这让项目顶层目录显得很“臃肿”，我个人建议将这些导出包统一放置到project-root-directory/pkg下面，这样项目顶层目录就会显得很简洁。

注：无论是“Organizing a Go module”这篇文档中的官方建议，还是我个人对Go项目目录布局的建议，针对的都是Go项目的基础布局。而像很多Gopher经常问的采用DDD、clean architecture或Hexagonal Architecture(六边形架构)设计的项目的目录布局是一种业务层面的布局，是在基础布局之上进行再设计的，不在本篇的说明范围之内。

“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://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

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