【必看】标准的 Go 项目布局

Original link: github.com/golang-stan…html

这是 Go 应用程序项目的基本布局。它不是核心 Go 开发团队定义的官方标准；然而，它是 Go 生态系统中一组常见的老项目和新项目的布局模式。其中一些模式比其余模式更受欢迎。它还具备许多小的加强，以及对任何足够大的实际应用程序通用的几个支持目录。git

若是你尝试学习 Go，或者你正在为本身创建一个 PoC 或一个玩具项目，这个项目布局是没啥必要的。从一些很是简单的事情开始(一个 main.go 文件绰绰有余)。随着项目的增加，请记住保持代码结构良好很是重要，不然你最终会获得一个凌乱的代码，这其中就包含大量隐藏的依赖项和全局状态。当有更多的人参与这个项目时，你将须要更多的结构。这时候，介绍一种管理包/库的通用方法是很重要的。当你有一个开源项目时，或者当你知道其余项目从你的项目存储库中导入代码时，这时候拥有私有(又名 internal)包和代码就很重要。克隆存储库，保留你须要的内容，删除其余全部的内容!仅仅由于它在那里并不意味着你必须所有使用它。这些模式都没有在每一个项目中使用。甚至 vendor 模式也不是通用的。github

Go 1.14 Go Modules 终于能够投入生产了。除非你有特定的理由不使用它们，不然使用 Go Modules 。若是你使用，就无需担忧 $GOPATH 以及项目放置的位置。存储库中的 go.mod 文件基本假定你的项目托管在 Github 上，但这不是要求。模块路径能够是任何地方，尽管第一个模块路径组件的名称中应该有一个点（当前版本的 Go 再也不强制使用该模块，但若是使用稍旧的版本，若是没有 mod 文件构建失败的话，不要惊讶）。若是你想知道更多信息，请参阅 Issues 37554 和 32819 。golang

此项目布局是通用的，而且不会尝试强加一个特定的 Go 包结构。web

这是社区的努力。若是看到新的模式，或者认为一个现有的模式须要更新，请提一个 issue。docker

若是须要命名、格式和样式方面的帮助，请运行 gofmt 和 golint 。还要确保阅读这些 Go 代码风格的指导方针和建议:windows

参见 Go Project Layout 了解更多的背景信息。api

更多关于包的命名和组织以及其余代码结构的建议:安全

Go 目录

`/cmd`

本项目的主干。服务器

每一个应用程序的目录名应该与你想要的可执行文件的名称相匹配(例如，/cmd/myapp)。

不要在这个目录中放置太多代码。若是你认为代码能够导入并在其余项目中使用，那么它应该位于 /pkg 目录中。若是代码不是可重用的，或者你不但愿其余人重用它，请将该代码放到 /internal 目录中。你会惊讶于别人会怎么作，因此要明确你的意图!

一般有一个小的 main 函数，从 /internal 和 /pkg 目录导入和调用代码，除此以外没有别的东西。

有关示例，请参阅 /cmd 目录。

`/internal`

私有应用程序和库代码。这是你不但愿其余人在其应用程序或库中导入代码。请注意，这个布局模式是由 Go 编译器自己执行的。有关更多细节，请参阅Go 1.4 release notes 。注意，你并不局限于顶级 internal 目录。在项目树的任何级别上均可以有多个内部目录。

你能够选择向 internal 包中添加一些额外的结构，以分隔共享和非共享的内部代码。这不是必需的(特别是对于较小的项目)，可是最好有有可视化的线索来显示预期的包的用途。你的实际应用程序代码能够放在 /internal/app 目录下(例如 /internal/app/myapp)，这些应用程序共享的代码能够放在 /internal/pkg 目录下(例如 /internal/pkg/myprivlib)。

`/pkg`

外部应用程序可使用的库代码(例如 /pkg/mypubliclib)。其余项目会导入这些库，但愿它们能正常工做，因此在这里放东西以前要三思:-)注意，internal 目录是确保私有包不可导入的更好方法，由于它是由 Go 强制执行的。/pkg 目录仍然是一种很好的方式，能够显式地表示该目录中的代码对于其余人来讲是安全使用的好方法。由 Travis Jeffery 撰写的 I'll take pkg over internal 博客文章提供了 pkg 和 internal 目录的一个很好的概述，以及何时使用它们是有意义的。

当根目录包含大量非 Go 组件和目录时，这也是一种将 Go 代码分组到一个位置的方法，这使得运行各类 Go 工具变得更加容易（正如在这些演讲中提到的那样: 来自 GopherCon EU 2018 的 Best Practices for Industrial Programming , GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps 和 GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go ）。

若是你想查看哪一个流行的 Go 存储库使用此项目布局模式，请查看 /pkg 目录。这是一种常见的布局模式，但并非全部人都接受它，一些 Go 社区的人也不推荐它。

若是你的应用程序项目真的很小，而且额外的嵌套并不能增长多少价值(除非你真的想要:-)，那就不要使用它。当它变得足够大时，你的根目录会变得很是繁琐时(尤为是当你有不少非 Go 应用组件时)，请考虑一下。

`/vendor`

应用程序依赖项(手动管理或使用你喜欢的依赖项管理工具，如新的内置 Go Modules 功能)。go mod vendor 命令将为你建立 /vendor 目录。请注意，若是未使用默认状况下处于启用状态的 Go 1.14，则可能须要在 go build 命令中添加 -mod=vendor 标志。

若是你正在构建一个库，那么不要提交你的应用程序依赖项。

注意，自从 1.13 之后，Go 还启用了模块代理功能(默认使用 https://proxy.golang.org 做为他们的模块代理服务器)。在here 阅读更多关于它的信息，看看它是否符合你的全部需求和约束。若是须要，那么你根本不须要 vendor 目录。

国内模块代理功能默认是被墙的，七牛云有维护专门的的模块代理 。

服务应用程序目录

`/api`

OpenAPI/Swagger 规范，JSON 模式文件，协议定义文件。

有关示例，请参见 /api 目录。

Web 应用程序目录

`/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 )。

有关示例，请参见 /scripts 目录。

`/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`

额外的外部测试应用程序和测试数据。你能够随时根据需求构造 /test 目录。对于较大的项目，有一个数据子目录是有意义的。例如，你可使用 /test/data 或 /test/testdata (若是你须要忽略目录中的内容)。请注意，Go 还会忽略以“.”或“_”开头的目录或文件，所以在如何命名测试数据目录方面有更大的灵活性。

有关示例，请参见 /test 目录。

其余目录

`/docs`

设计和用户文档(除了 godoc 生成的文档以外)。

有关示例，请参阅 /docs 目录。

`/tools`

这个项目的支持工具。注意，这些工具能够从 /pkg 和 /internal 目录导入代码。

有关示例，请参见 /tools 目录。

`/examples`

你的应用程序和/或公共库的示例。

有关示例，请参见 /examples 目录。

`/third_party`

外部辅助工具，分叉代码和其余第三方工具(例如 Swagger UI)。

`/githooks`

Git hooks。

`/assets`

与存储库一块儿使用的其余资产(图像、徽标等)。

`/website`

若是你不使用 Github 页面，则在这里放置项目的网站数据。

有关示例，请参见 /website 目录。

你不该该拥有的目录

`/src`

有些 Go 项目确实有一个 src 文件夹，但这一般发生在开发人员有 Java 背景，在那里它是一种常见的模式。若是能够的话，尽可能不要采用这种 Java 模式。你真的不但愿你的 Go 代码或 Go 项目看起来像 Java:-)

不要将项目级别 src 目录与 Go 用于其工做空间的 src 目录(如 How to Write Go Code 中所述)混淆。$GOPATH 环境变量指向你的(当前)工做空间(默认状况下，它指向非 windows 系统上的 $HOME/go)。这个工做空间包括顶层 /pkg, /bin 和 /src 目录。你的实际项目最终是 /src 下的一个子目录，所以，若是你的项目中有 /src 目录，那么项目路径将是这样的: /some/path/to/workspace/src/your_project/src/your_code.go。注意，在 Go 1.11 中，能够将项目放在 GOPATH 以外，但这并不意味着使用这种布局模式是一个好主意。

Badges

Go Report Card - It will scan your code with gofmt, go vet, gocyclo, golint, ineffassign, license and misspell. Replace github.com/golang-standards/project-layout with your project reference.
GoDoc - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.
Release - It will show the latest release number for your project. Change the github link to point to your project.

Notes

A more opinionated project template with sample/reusable configs, scripts and code is a WIP.