Go 项目布局标准

Table of Contents

不管是什么语言,稍微大的项目,目录布局都会有问题,只不过有些语言的框架自身就提供了目录结构规范。

对于 Golang 尤为明显,还是语言比较年轻的缘故,还没有权威性的规范。

project-layout 提供了 Go 大中型项目的目录规范。本文对内容进行了整理,隔段时间会根据原项目中更新一次。


Go 项目布局标准(Standard Go Project Layout)

不是 Go 官方的标准;但是它参考了 Go 生态中常见的布局模式(以前的和新兴的)。

如果你仅仅是用来学习 Go 或者写一个小的 Demo 是不需要按照此项目结构的(一个 main.go 可能就足够了)。 但如果你打算做一个长期的项目来维护,合理的代码结构是非常重要的,不然随着代码变多,依赖关系会变的混乱不堪,难以维护。 有很多人参同时维护一个项目的时候,代码结构就更重要了,就需要引入通用的管理软件包和库的方法。

如果需要命名、代码风格方面的帮助,请先运行 gofmtgolint , 推荐阅读 Go 代码风格指南和建议的文档:

更多的关于命名和代码组织结构的建议资料:

Go 目录

/cmd

项目的主应用目录。目录中名称一般与可执行文件相对应(比如: /cmd/myapp )。

不要 在本目录下放很多的代码,如果代码可以被其他项目导入使用的,请放到 /pkg 目录下, 如果代码不可复用或者你不希望其他项目使用,请放到 /internal 目录下。

通常只包含一个简单的 main 函数,调用 /internal/pkg 中的代码。

查看 /cmd 目录范例:https://github.com/golang-standards/project-layout/blob/master/cmd/README.md

/internal

私有的应用和库代码。这些是是不希望被其他应用程序或者库导入的代码。

注意,这种布局方式是 Go 编译器强制限制的,查看 Go 1.4 的 发布日志,而且不只是顶部的 internal 目录,所有子目录中的 internal 目录都受限制。

(也就是说,在 Go 编译器层面约束的 internal 目录是不可被导出的)

/pkg

外部应用可以使用的库代码(比如 /pkg/mypubliclib )。

当根目录中包含很多非 Go 的组件时,这也是将 Go 代码分组到一起的一个办法,也使得运行各种 Go 工具更加的容易。

查看哪些流程的项目使用 /pkg 目录。这是一种很常见的布局方式,但还没有被普遍接受,而且 Go 社区中的有些人不推荐这么做。

如果应用不大,额外嵌套一个目录没什么价值,就不需要使用了;在项目很大,根目录比较复杂的情况下,可以考虑一下(特别是包含了很多的非 Go 程序组件)。

/vendor

应用程序依赖包(手动管理或者使用包管理工具类似 dep 或者新版本中内置的,但仍旧在实验阶段的 modules 特性)。

如果要构建库的话, 不要 提交应用程序依赖。

注意 1.13 的 Go 允许打开模块代理特性(使用 https://proxy.golang.org/ 作为他们的模块代理服务器)。 从 这里 查看更多的信息,看他是否满足你的需求。如果满足的话,你可能都不需要 'vendor' 目录了。

服务应用程序目录

/api

OpenAPI/Swagger 规范,JSON 模式(schema)文件,协议定义文件。

查看 /api 范例。

Web 应用程序目录

/web

Web 应用程序特定组件:静态网站资源,服务端模板和单网页应用(SPAs)。

通用的应用程序目录

/configs

配置文件模板和默认的配置项。

confd 或者 consul-template 模板文件放到这儿。

/init

系统初始化(systemd, upstart, sysv)和进程管理(runit, supervisord)配置。

/scripts

用于构建、安装、分析等操作脚本。

这些脚本可以使根部的 Makefile 文件变的小且简单,比如:https://github.com/hashicorp/terraform/blob/master/Makefile

查看 /script 范例。

/build

打包和持续集成。

Put your cloud (AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the /build/package directory.

Put your CI (travis, circle, drone) configurations and scripts in the /build/ci directory. Note that some of the CI tools (e.g., Travis CI) are very picky about the location of their config files. Try putting the config files in the /build/ci directory linking them to the location where the CI tools expect them (when possible).

/deployment

IaaS, PaaS,系统和容器编排文件和模板(docker-compose, kubernetes/helm, mesos, terraform, bosh)。

/test

其他外部测试应用程序和测试数据。较大的项目需要一个数据目录,如果你想让 Go 忽略掉他的话,可以命名为 /test/data 或者 /test/testdata 。 Go 还会忽略以 . 或者 _ 开头的文件。

查看 /test 更多范例。

其他目录

/docs

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

查看 /docs 更多范例。

/tools

此项目的支持工具。注意,这些工具可以从 /pkg/internal 目录中导入代码。

查看 /tools 更多范例。

/examples

你的应用程序或者公共库的范例。

查看 /example 更多范例。

/third_party

外部帮助工具,交叉代码和其他第三方工具(比如:Swagger UI)。

/githooks

Git hooks.

/assets

与项目一起的其他资源文件(图片,logos 等等)。

/website

如果你不使用 github pages,就在这里放置项目的网站数据。

查看 /website 更多范例。

你不应该使用的目录

/src

一些 Go 项目包含 src 目录,通常是 Java 世界中的程序员干的。但是你如果想省点事的话,千万不要这么干(除非你想让你的 Go 项目看起来像是 Java)。

How to Write Go Code 中说过不要将项目中的 /src 目录和 Go 工作区间( GOPATH )中的 /src 目录混淆。

GOPATH 在顶级目录中包含了 /pkg /bin/src 目录。如果你把你的代码放在 /src 子目录下,你的包路径会类似这样 /some/path/to/workspace/src/your_project/src/your_code.go 。尽管 Go 1.11 之后,项目可以放在 GOPATH 之外,但并不意味这这种布局是一个好主意。


最后更新时间 2019-10-17 13:08:27。

Date: 2019-06-09 17:08:00

Author: JerryZhang