精选30+云产品,助力企业轻松上云!>>>

目录 项目布局(Project Layout)规范

注意,本文列举的目录为项目顶层子目录清单。

官方标准:https://github.com/golang-standards/project-layout

├── .gitignore
├── LICENSE.md
├── Makefile
├── README.md
├── go.mod
├── api
├── assets
├── build
├── cmd
├── configs
├── deployments
├── docs
├── examples
├── githooks
├── init
├── internal
├── pkg
├── scripts
├── test
├── third_party
├── tools
├── vendor
├── web
└── website

程序核心代码目录

/cmd(Command)

存放 Golang 项目的若干个程序的可执行文件(e.g. /cmd/app/main.go)。项目下每个程序目录的名字应该和程序可执行文件的名字保持一致。

参考:https://github.com/golang-standards/project-layout/blob/master/cmd/README.md

一般来说程序的 main() 函数不要编写太多代码。如果这些代码会被其他程序引用,那么应该编写在 /pkg 目录中;如果这些代码不能被重用,或者不希望别人重用,那么这些代码应该编写在 /internal 目录中。然后在 main() 函数中导入并执行即可。

/pkg(Package)

存放可以被其他项目引用的代码。通常是程序的核心逻辑代码或通用 lib 库。其他项目的程序可以通过 import 来引入这里的代码。

所以当我们将代码放入 pkg 时一定要慎重,考虑清楚这些代码是否应该被 “公开”。

/internal

存放当前项目内部(Internal)私有的程序和库的代码。这里的代码不希望被外部项目所引用。当我们在其他项目引入包含 internal 的依赖时,Golang 会在编译时报错:

An import of a path containing the element “internal” is disallowed
if the importing code is outside the tree rooted at the parent of the "internal" directory.

内部程序的代码应该存放在 /internal/app 子目录下,同时这些内部程序锁依赖的代码库应该在 /internal/pkg 子目录和 /pkg 中。e.g.

/vendor

存放程序的外部依赖。可以手工管理,也可以使用 Golang 提供的 dep 工具(https://github.com/golang/dep)。

常规目录

/configs

存放配置文件的模板(e.g. consul-template)或者默认配置文件(e.g. confd)

/init

存放系统初始化(e.g. systemd、upstart、sysv)以及进程管理或者进程监控(e.g. runit、supervisord)的配置

/scripts

存放执行各种构建、安装、分析等,或者其他操作的脚本文件

参考:https://github.com/golang-standards/project-layout/blob/master/scripts/README.md

/build

存放打包及持续集成所需要的的文件

  • 将 cloud(AMI)、container(Docker)、OS(deb、rpm、pkg)软件包的配置放在 /build/package 目录下。
  • 将 CI(travis、circle、drone)系统的配置和脚本放在 /build/ci 目录下。需要注意的是,有些 CI 工具(e.g. Travis CI)对它们的配置文件的位置非常敏感。此时,我们可以把配置文件放在 /build/ci 目录下,然后将它们软链接到 CI 工具希望它们出现的位置路径。

/deployments

存放 IaaS、PaaS、系统,以及容器编排的部署配置文件和模板文件。例如:docker-compose、kubernetes/helm、mesos、terraform、bosh 等。

/test

存放程序的单元测试程序,以及测试数据

对于大型的项目则有必要包含一个 /test/data 子目录,Golang 会忽略其中的某些内容。例如:/test/data 或者 /test/testdata 目录。

注意,Golang 还会忽略任何以 “.” 和 “_” 开头的文件和目录。

参考:https://github.com/golang-standards/project-layout/blob/master/test/README.md

Makefile

Makefile 定义了项目编译的细节,并且 /scripts 目录下的脚本文件通常由 Makefile 触发。

Service(服务端)应用目录

/api

存放项目对外提供的若干个北向 API 接口的定义文件。包括:OpenAPI/Swagger 的规范(Specs)文件、JSON schema 文件,以及协议定义文件。例如: /api/protobuf-spec、/api/thrift-spec 或者 /api/http-spec 目录,这些目录中包含了当前项目对外提供的和依赖的所有 API 文件:

$ tree ./api
api
└── protobuf-spec
    └── oceanbookpb
        ├── oceanbook.pb.go
        └── oceanbook.proto

其中,创建 oceanbookpb 二级目录的主要作用在于一个项目同时提供了多种不同的访问方式时,这样可以避免潜在的冲突问题,也更加清晰。

参考:https://github.com/golang-standards/project-layout/blob/master/api/README.md

Web 应用目录

/web

存放 Web 应用的标准组件

  • 静态 Web 资源
  • 服务端模板
  • 单页应用

其他目录

/docs

存放除了使用 godc 自动生成的程序文档文件之外的文档资料,例如:用户及设计文档

参考:https://github.com/golang-standards/project-layout/blob/master/docs/README.md

/tools

存放项目需要工具集。这些工具可以引入 /pkg 和 /internal 目录下的代码。

参考:https://github.com/golang-standards/project-layout/blob/master/tools/README.md

/examples

存放程序示例文件

参考:https://github.com/golang-standards/project-layout/blob/master/examples/README.md

/third_party

存放第三方辅助工具、forked 代码。例如:Swagger UI。

/githooks

存放 Git books 文件

/assets

存放其他资产(assets)文件,通常是图片、logo 等文件

website

如果你不用 Github pages 的话,可以在这里放置项目的站点文件。通常是用于项目宣传和展示的网站资料

参考:https://github.com/golang-standards/project-layout/blob/master/website/README.md

不建议使用的目录

/src

注意,这里所说的 /src 目录指的是 “项目顶层” 的 /src,而不是 “Go workspace” 的 /src 目录。

$GOPATH 环境变量指向当前环境中的 Go workspace,在 UNIX-like 操作系统中通常是 $HOME/go。笔者的配置为:

$ echo $GOPATH
/Users/mickeyfan/workspace/go

这个 workspace 的顶层包括了 /pkg、/bin 和 /src 目录,Golang 项目在默认情况下都会被放置到 $GOPATH/src 目录下,存储着我们开发和依赖的全部项目代码。

所以,如果我们在实际项目的顶层定义了 /src 目录,那么该项目的 $GOPATH 中就会出现两个 src,e.g.

/some/path/to/workspace/src/your_project/src/your_code.go。

所以,不建议在项目的顶层创建 /src 子目录,区别于 JAVA 的编程习惯。


这里给大家推荐一个在线软件复杂项交易平台:米鼠网 https://www.misuland.com

米鼠网自成立以来一直专注于从事软件项目、人才招聘、软件商城等,始终秉承“专业的服务,易用的产品”的经营理念,以“提供高品质的服务、满足客户的需求、携手共创双赢”为企业目标,为中国境内企业提供国际化、专业化、个性化、的软件项目解决方案,我司拥有一流的项目经理团队,具备过硬的软件项目设计和实施能力,为全国不同行业客户提供优质的产品和服务,得到了客户的广泛赞誉。