go项目的布局标准

# 5. Go项目的布局标准

# 5.1 创世项目-Go 语言项目自身

$loccount .
all          SLOC=460992  (100.00%)  LLOC=193045  in 2746 files
Go           SLOC=256321  (55.60%)  LLOC=109763  in 1983 files
C            SLOC=148001  (32.10%)  LLOC=73458   in 368 files
HTML         SLOC=25080   (5.44%)  LLOC=0       in 57 files
asm          SLOC=10109   (2.19%)  LLOC=0       in 133 files

1
2
3
4
5
6

go 1.3 结构布局

$cd go // 进入Go语言项目根目录
$git checkout go1.3 // 切换到go 1.3版本
$tree -LF 1 ./src // 查看src目录下的结构布局
./src
├── all.bash*	//以 all.bash 为代表的代码构建的脚本源文件放在了 src 下面的顶层目录下
├── clean.bash*
├── cmd/		//cmd 下面存放着 Go 相关可执行文件的相关目录
├── make.bash*
├── Make.dist
├── pkg/	//pkg 下面存放着运行时实现、标准库包实现，这些包既可以被上面 cmd 下各程序所导入，也可以被 Go 语言项目之外的 Go 程序依赖并导入
├── race.bash*
├── run.bash*
... ...
└── sudo.bash*

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 5.2 go语言布局的演进

# 5.2.1 演进一

Go 1.4 版本删除 pkg 这一中间层目录并引入 internal 目录

删除pkg目录：为了简化源码树层次
引入internal包机制：Go 项目里internal 目录下的 Go 包，只可以被本项目内部的包导入

# 5.2.2 演进二

Go 1.6 版本增加 vendor 目录

解决 Go 包依赖版本管理的问题
让 Go 项目第一次具有了可重现构建（Reproducible Build）的能力

# 5.2.3 演进三

Go 1.13 版本引入 go.mod 和 go.sum

解决 Go 包依赖版本管理的问题
实现精准的可重现构建

# 5.3 go 可执行项目的典型结构布局

可执行程序项目是以构建可执行程序为目的的项目，Go 社区针对这类 Go 项目所形成的典型结构布局是这样的：

$tree -F exe-layout 
exe-layout
├── cmd/		//存放项目要编译构建的可执行文件对应的 main 包的源文件
│   ├── app1/
│   │   └── main.go
│   └── app2/
│       └── main.go
├── go.mod		//go.mod 和 go.sum，是Go 语言包依赖管理使用的配置文件
├── go.sum
├── internal/
│   ├── pkga/
│   │   └── pkg_a.go
│   └── pkgb/
│       └── pkg_b.go
├── pkg1/	//存放项目自身要使用、同样也是可执行文件对应 main 包所要依赖的库文件，同时这些目录下的包还可以被外部项目引用
│   └── pkg1.go
├── pkg2/
│   └── pkg2.go
└── vendor/		//用于在项目本地缓存特定版本依赖包的机制，在 Go Modules 机制引入前，基于 vendor 可以实现可重现构建，保证基于同一源码构建出的可执行程序是等价的。引入Go Modules 机制后，可视为一个可选目录

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

对于以生产可执行程序为目的的 Go 项目，它的典型项目结构分为五部分：

放在项目顶层的 Go Module 相关文件，包括 go.mod 和 go.sum；
cmd 目录：存放项目要编译构建的可执行文件所对应的 main 包的源码文件；
项目包目录：每个项目下的非 main 包都“平铺”在项目的根目录下，每个目录对应一个 Go 包；
internal 目录：存放仅项目内部引用的 Go 包，这些包无法被项目之外引用；
vendor 目录：这是一个可选目录，为了兼容 Go 1.5 引入的 vendor 构建模式而存在的。这个目录下的内容均由 Go 命令自动维护，不需要开发者手工干预。

# 5.4 Go 库项目的典型结构布局

Go 库项目的初衷是为了对外部（开源或组织内部公开）暴露 API，对于仅限项目内部使用而不想暴露到外部的包，可以放在项目顶层的 internal 目录下面。当然 internal 也可以有多个并存在于项目结构中的任一目录层级中，关键是项目结构设计人员要明确各级 internal 包的应用层次和范围。

Go 库项目仅对外暴露 Go 包，这类项目的典型布局形式是这样的：

$tree -F lib-layout  //这类项目不需要构建可执行程序，所以去除了 cmd 目录，不需要vendor 目录去缓存库自身的第三方依赖
lib-layout
├── go.mod
├── internal/
│   ├── pkga/
│   │   └── pkg_a.go
│   └── pkgb/
│       └── pkg_b.go
├── pkg1/
│   └── pkg1.go
└── pkg2/
    └── pkg2.go

1
2
3
4
5
6
7
8
9
10
11
12

对于有一个且仅有一个包的 Go 库项目来说，我们也可以将上面的布局做进一步简化，简化的布局如下所示：

$tree -L 1 -F single-pkg-lib-layout
single-pkg-lib-layout
├── feature1.go
├── feature2.go
├── go.mod
└── internal/

1
2
3
4
5
6

上次更新: 2022/06/12, 15:48:09

← go的程序结构 go包依赖管理→