主要依据项目的复杂度按需选用如下两种分层风格:
- 扁平化架构风格:适用于简单的微服务(只做一件事)以及工具类库等的实现,不需要复杂的分层结构。示例项目如下:
- 分层架构风格:适用于成熟的、大型的、复杂的、需要多人共享开发的应用实现。示例项目如下:
扁平化风格
github.com/allen/toolkit
├── CHANGELOG.md
├── CONTRIBUTORS
├── LICENSE
├── README.md
├── main.go
├── main_test.go
├── utils.go
├── utils_test.go
├── ...
├── configs/
├── docs/
└── examples/
可以全部文件都在顶层目录中,不再分子目录,同时,也可以按需将公共模块(configs/utils)、各个子领域(tcp/udp/collector/user/articles)等独立出一层目录来。一般用于我们写exporter等客户端代理。
分层架构风格
一个基本的go项目一般会有cmd
, internal
, pkg
三个基础目录来分层,而vendor
目录一般由go mod
自动管理,当然这不是官方go
核心开发团队定义的标准。但这个确实是目前go
生态系统中比较常见的布局形式,不管从之前的和还是现在开发项目的分层来看。这些基础目录同样适用更大的项目,并且还有一些小的增强功能。
github.com/servi-io/api
├── cmd/
│ ├── servi/
│ │ ├── cmdupdate/
│ │ ├── cmdquery/
│ │ └── servi.go
│ └── servid/
│ ├── routes/
│ │ └── handlers/
│ ├── tests/
│ └── servid.go
├── internal/
│ ├── attachments/
│ ├── locations/
│ ├── orders/
│ │ ├── customers/
│ │ ├── items/
│ │ ├── tags/
│ │ └── orders.go
│ ├── registrations/
│ └── platform/
│ ├── crypto/
│ ├── mongo/
│ └── json/
├── pkg/
│ ├── logging/
│ ├── pool/
│ ├── runtime/
└── vendor/
├── github.com/
│ ├── ardanlabs/
│ ├── golang/
│ ├── prometheus/
└── golang.org/
常用目录解析
/cmd
一般存放应用程序的入口可执行文件。
每个应用程序的目录名应该与你想要的可执行文件的名称相匹配(例如,/cmd/myapp
),主文件名既可以是main.go
,也可以与可执行文件保持同名,例如,myapp.go
。
不要在这个目录中放置太多代码,尽量保持简洁。可以共享给其他项目使用的代码应该位于 /pkg
目录中。如果代码不可重用,或者不希望其他人重用,请将该代码放到 /internal
目录中。通常会有一个小的 main
函数,从 /internal
和 /pkg
目录导入和调用代码,除此之外没有别的东西。
/internal
私有应用程序和库代码放置于此。这是你不希望其他人在其应用程序或库中导入代码。请注意,这个布局模式是由 Go 编译器本身执行的。有关更多细节,请参阅Go 1.4 [release notes](https://golang.org/doc/go1.4#internalpackages)
。注意,这并不局限于顶级 internal
目录。在项目树的任何级别上都可以有多个内部目录。
可以选择向 internal
包中添加一些额外的结构,以分隔共享和非共享的内部代码。这不是必需的(特别是对于较小的项目),但是最好有可视化的线索来显示预期的包的用途。你的实际应用程序代码可以放在 /internal/app
目录下(例如 /internal/app/myapp
),这些应用程序共享的代码可以放在 /internal/pkg
目录下(例如 /internal/pkg/myprivlib
)。
/pkg
外部应用程序可以使用的库代码(例如 /pkg/mypubliclib
)。其他项目会导入这些库,所以在这里放东西之前要三思:-)。注意,internal
目录是确保私有包不可导入的更好方法,因为它是由 Go 强制执行的。/pkg
目录仍然是一种很好的方式,可以显式地表示该目录中的代码对于其他人来说是安全使用的好方法。
当根目录包含大量非 Go 应用的组件和目录时,为了避免复杂度,可以考虑通过pkg
统一管理这些可共享的组件及目录。
/vendor
应用程序依赖项(手动管理或使用你喜欢的依赖项管理工具,如新的内置 [Go Modules](https://github.com/golang/go/wiki/Modules)
功能)。go mod vendor
命令将为你创建 /vendor
目录。请注意,如果未使用默认情况下处于启用状态的 Go 1.14,则可能需要在 go build
命令中添加 -mod=vendor
标志。
如果你正在构建一个库,那么不要提交你的应用程序依赖项。
服务及Web应用程序目录
对于HTTP的Handler及注册、服务器的启动等内容应该放哪里没有统一的规范,例如,kubernetes的/api
目录就只是放了OpenAPI/Swagger 规范,JSON 模式文件,协议定义文件,并不涉及实际HTTP服务器的相关内容,这部分散落在各个/cmd
实际的应用中;而prometheus则将如下两个目录合并为/web/api/v1、/web/ui/
,以此来供前端服务。
总体原则如下:
- 服务器端的Handler注册等还是散落在各个服务器的可执行文件中
- 前端的内容放置到
/web
目录中,如果存在 /api
目录就只存放OpenAPI/Swagger 规范,JSON 模式文件,协议定义文件,并不涉及实际HTTP服务器的相关内容
/api
OpenAPI/Swagger 规范,JSON 模式文件,协议定义文件。
/web
特定于 Web 应用程序的组件:静态 Web 资产、服务器端模板和 SPAs。
通用应用目录
/configs
配置文件模板或默认配置。
将你的 confd
或 consul-template
模板文件放在这里。
/init
System init(systemd,upstart,sysv)和 process manager/supervisor(runit,supervisor)配置。
/scripts
执行各种构建、安装、分析等操作的脚本。
这些脚本保持了根级别的 Makefile 变得小而简单(例如, [https://github.com/hashicorp/terraform/blob/master/Makefile](https://github.com/hashicorp/terraform/blob/master/Makefile)
)。
/build
打包和持续集成。
将你的云( AMI )、容器( Docker )、操作系统( deb、rpm、pkg )包配置和脚本放在 /build/package
目录下。
将你的 CI (travis、circle、drone)配置和脚本放在 /build/ci
目录中。请注意,有些 CI 工具(例如 Travis CI)对配置文件的位置非常挑剔。尝试将配置文件放在 /build/ci
目录中,将它们链接到 CI 工具期望它们的位置(如果可能的话)。
/deployments
IaaS、PaaS、系统和容器编排部署配置和模板(docker-compose、kubernetes/helm、mesos、terraform、bosh)。注意,在一些存储库中(特别是使用 kubernetes 部署的应用程序),这个目录被称为 /deploy
。
/test
注意:此处主要是额外的外部测试应用程序和测试数据。而单测程序按照Go的规范一般与被测试程序在相同的位置,只是文件后缀不一样,例如,server.go
与server_test.go
。
你可以随时根据需求构造 /test
目录。对于较大的项目,有一个数据子目录是有意义的。例如,你可以使用 /test/data
或 /test/testdata
(如果你需要忽略目录中的内容)。请注意,Go 还会忽略以“.”或“_”开头的目录或文件,因此在如何命名测试数据目录方面有更大的灵活性。
其他目录
/docs
设计和用户文档(除了 godoc 生成的文档之外)。
/tools
这个项目的支持工具。注意,这些工具可以从 /pkg
和 /internal
目录导入代码。
/examples
你的应用程序和/或公共库的示例。
/third_party
外部辅助工具,分叉代码和其他第三方工具(例如 Swagger UI)。
/plugin
如果你开发有灵活自定义的插件,可以参考kubernetes中的/plugin
子目录,就存放了其admission及auth
插件内容。
/githooks
Git hooks。
/assets
与存储库一起使用的其他资产(图像、徽标等)。当然,你可以将Logo独立出来logo
一级子目录,kubernetes就是这么干的。
/website
如果你不使用 Github 页面,则在这里放置项目的网站数据。
你不应该拥有的目录
/src
有些 Go 项目确实有一个 src
文件夹,但这通常发生在开发人员有 Java 背景,在那里它是一种常见的模式。如果可以的话,尽量不要采用这种 Java 模式。你真的不希望你的 Go 代码或 Go 项目看起来像 Java:-)
不要将项目级别 src
目录与 Go 用于其工作空间的 src
目录(如 [How to Write Go Code](https://golang.org/doc/code.html)
中所述)混淆。$GOPATH
环境变量指向你的(当前)工作空间(默认情况下,它指向非 windows 系统上的 $HOME/go
)。这个工作空间包括顶层 /pkg
, /bin
和 /src
目录。你的实际项目最终是 /src
下的一个子目录,因此,如果你的项目中有 /src
目录,那么项目路径将是这样的: /some/path/to/workspace/src/your_project/src/your_code.go
。注意,在 Go 1.11 中,可以将项目放在 GOPATH
之外,但这并不意味着使用这种布局模式是一个好主意。