Go项目的目录结构基本布局

本文介绍: 随着项目的代码量在不断地增长，不同的开发人员按自己意愿随意布局和创建目录结构，项目维护性就很差，代码也非常凌乱。良好的目录与文件结构十分重要，尤其是团队合作的时候，良好的目录与文件结构可以减少很多不必要的麻烦。项目目录结构规范的的本质是提高了代码的可读性，最终目的是提高团队协作效率，降低工程维护成本。

前言

随着项目的代码量在不断地增长，不同的开发人员按自己意愿随意布局和创建目录结构，项目维护性就很差，代码也非常凌乱。良好的目录与文件结构十分重要，尤其是团队合作的时候，良好的目录与文件结构可以减少很多不必要的麻烦。项目目录结构规范的的本质是提高了代码的可读性，最终目的是提高团队协作效率，降低工程维护成本。

我们知道 java 项目结构是请求达到路由层控制器 controller，然后 controller 会去调用 service 层逻辑代码，然后 service 层会去调用 d a o 层的接口方法，其实 dao 层都是以接口的形式提供，然后这些接口里头的都是操作数据库的方法，然后与 dao 层对应着的有一个 mapper，mapper 是以 xml 形式提供的，与 dao 层中的接口相对应，xml 中实际就是实现了 dao 接口中的这些具体方法，xml 中会与指定的 dao 接口中指定的方法进行绑定，xml 中会去写 sql 逻辑。具体请看架构师技能1：Java工程规范、浅析领域模型VO、DTO、DO、PO、优秀命名

一、Go 语言自身项目的基本结构

首先我们先看Go 语言自身项目的基本结构。

Go项目的项目结构自1.0版本发布以来一直十分稳定，直到现在Go项目的顶层结构基本没有大的改变。go项目大致结构如下，GitHub – golang/go: The Go programming language

$ tree -LF 1 ~/go/src/github.com/golang/go
./go
├── api/
├── doc/
├── lib/
├── misc/
├── src/

├── test

├── PATENTS
├── LICENSE
├── CONTRIBUTING.md
└── README.md

作为Go语言的“创世项目”，其项目结构的布局对后续的其他Go语言项目具有重要的参考意义，尤其是早期Go项目中src目录下面的结构，更是在后续被Go社区作为Go应用项目结构的模板被广泛使用。我们以早期的Go 1.3版本的src目录下的结构为例：

$ tree -LF 1 ./src
./src
├── all.bash*
├── all.bat
├── all.rc*
├── clean.bash*
├── clean.bat
├── clean.r c*
├── cmd/
├── lib9/
├── lib bio/
├── li blink/
├── make.bash*
├── make.bat
├── Mak e.dist
├── make.r c*
├── nacl test.bash*
├── pkg/
├── r ace.bash*
├── r ace.bat
├── run.bash*
├── run.bat
├── run.rc*
└── sudo.bash*

src目录下面的结构三个特点：

1）代码构建的脚本源文件放在src下面的顶层目录下；

2）s rc下的二级目录cmd下面存放着go 工具链相关的可执行文件（比如：go、go fmt等）的主目录以及它们的main包源文件；

3）s rc下的二级目录pkg下面存放着上面cm d下各工具链程序依赖的包、go 运行时以及go 标准库的源文件

在Go 1.3版本以后至今，Go项目下的src目录中发生了几次结构上的变动：

Go 1.4版本中删除了Go源码树中src/pkg/xxx中pkg这一层级目录而直接使用src/xxx；

Go 1.4版本在src下面增加internal目录，用于存放无法被外部导入仅Go项目自用的包；

Go 1.6版本在src下面增加v endor目录，但Go项目自身真正启用vendor机制是在Go 1.7版本中。ve ndor目录中存放了go项目自身对外部项目的依赖，主要是golang.org/x下的各个包，包括：net、text、crypto等。该目录下的包会在每次Go版本发布时做更新；

Go 1.13版本在src下面增加了go.mod和go.num，实现了go项目自身的go module 迁移，go项目内所有包被放入名为std的module下面，其依赖的包依然是golang.org/x下的各个包

// Go 1.13版本go项目src下面的go.mod
mod ul e std

go 1.12

require (
    golang.org/x/cry p to v0.0.0-20200124225646-8b5121b e2f68
    golang.org/x/net v0.0.0-20190813141303-74dc4d7220e7
    golang.org/x/sys v0.0.0-20190529130038-5219a1e1c5f8 // in direct
    golang.org/x/t ext v0.3.2 // in direct
)
下面是最新的Go 1.16版本src目录下的完整布局：

├── Mak e.dist
├── README.ve ndor
├── all.bash*
├── all.bat
├── all.rc*
├── bootstrap.bash*
├── buildall.bash*
├── clean.bash*
├── clean.bat
├── clean.rc*
├── cm d/
├── cmp.bash
├── go.mod
├── go.sum
├── internal/
├── make.bash*
├── make.bat
├── make.rc*
├── race.bash*
├── race.bat
├── run.bash*
├── run.bat
├── run.rc*
├── test data/
…
└── vendor/

Go 1.14 Go Modules 投入使用后，就无需担心 $GOPATH 以及项目放置的位置。所以项目的 vendor 可以忽略了，建议直接使用 module 来管理依赖

二、优秀开源的go项目结构样例

1、Doc ker

https://github.com/mob y/mob y

├── api // 存放对外公开的 API 规则

├── builder // 存放构建脚本等

├── cli // 命令行的主要逻辑

├── cm d // 存放可执行程序，main 包放这个目录中

├── contrib // 存放一些有用的脚本或文件，但不是项目的核心部分

├── docs // 存放文档

├── internal // 只在本项目使用的包（私有）

├── pkg // 本项目以及其他项目可以使用的包（公有）

├── plugin // 提供插件功能

2、Kubernet es

https://github.com/kubernetes/kubernetes

├── api

├── build // 存放构建脚本等

├── cmd

├── docs

├── pkg

├── plugin

├── test // 单元测试之外的测试程序、测试数据

├── t hird_part y // 经过修改的第三方的代码

3、Gogs

https://github.com/gogs/gogs

├── cmd

├── conf // 对配置进行解析

├── docker // 存放 docker 脚本

├── models // MVC 中的 model

├── pkg

├── public // 静态公共资源，实际项目会将其存入 CDN

├── routes // 路由

├── scripts // 脚本文件

├── templates // 存放模板文件

总体上这些优秀开源项目，没有统一一致的目录结构方式，但大体上，有一些通用的地方，这就有

project-layout/README_zh.md at master · golang-standards/project-layout · GitHub做参考。

三、通用项目目录结构参考

参考：

project-layout/README_zh.md at master · golang-standards/project-layout · GitHub

1、web 服务 应用程序目录

`/api`

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

`/web`

特定于 Web 应用程序的组件:静态 Web 资产、服务器端模板和 SPAs。

2、通用应用目录

`/configs`

配置文件模板或默认配置。

将你的 confd 或 consul-template 模板文件放在这里。

`/init`

Sy stem ini t（systemd，up start，sysv）和 process manager/supervisor（runit，supervisor）配置。

`/scripts`

执行各种构建、安装、分析等操作的脚本。

这些脚本保持了根级别的 Makefile 变得小而简单(例如， terraform/Makefile at main · hashicorp/terraform · GitHub )。

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

`/build`

打包和持续集成。

将你的云( AMI )、容器( Doc ker )、操作系统( deb、rpm、pkg )包配置和脚本放在 /build/package 目录下。

将你的 CI (travis、circle、drone)配置和脚本放在 /build/ci 目录中。请注意，有些 CI 工具(例如 Travis CI)对配置文件的位置非常挑剔。尝试将配置文件放在 /build/ci 目录中，将它们链接到 CI 工具期望它们的位置(如果可能的话)。

`/deployments`

IaaS、PaaS、系统和容器编排部署配置和模板(docker–compose、kubernetes/helm、mes os、t erraform、bos h)。注意，在一些存储库中(特别是使用 kubernetes 部署的应用程序)，这个目录被称为 /deploy。

`/test`

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

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

我们可以参考 project-layout/README_zh.md at master · golang-standards/project-layout · GitHub

3、其他目录

`/docs`

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

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

`/tools`

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

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

`/examples`

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

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

`/third_party`

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

`/githooks`

Git hooks。

`/assets`

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

`/website`

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

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

4、不应该拥有的目录

`/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 之外，但这并不意味着使用这种布局模式是一个好主意。

四、代码架构

我们在《架构设计1:谈谈架构》已经提到代码架构，主要定义内容：

一、代码单元:
1、配置设计
2、框架、类库。
二、代码单元组织：
1、编码规范，编码的惯例。
2、项目模块划分
3、顶层文件结构设计，比如 mvc 设计。
4、依赖关系

我们再次只提分层依赖和目录规范结构：

1、代码分层和依赖

代码分层，让不同层次的代码做不同的动作。层次清晰的代码，提高可读性，从代码结构就大概能了解到代码是如何分层，每层大概功能是什么。例如 java常用的Controller、Servi ce、Mapper/Dao三层代码结构，其各层的代码逻辑范围。

2、默认上层依赖于下层

依赖规则规定上层的代码可以依赖下层，但是下层的代码不可以依赖上层。也就是说下层逻辑不可以依赖任何上层定义的变量，函数，结构体，类，模块等等代码实体。

通过分层，一个庞大系统切分成不同部分，便于分工合作和维护。

应用层：主要负责具体的业务逻辑处理

服务层：提供可复用的服务

数据层：负责数据的存储和访问
 假如说，最上层应用层处使用了 go 语言的 gorm 三方库，并定义了 gorm 相关的数据库结构体及其 tag 等。那么下层数据层不可以引用任何外层中 gorm 相关的结构体或方法，甚至不应该感知到 gorm 的存在。

但是，分层架构也有一些挑战：①必须合理规划层次边界和接口；②禁止跨层次的调用及逆向用。《架构设计5:架构模式-分层模式》《架构设计5:架构模式-分层模式》《架构设计5:架构模式-分层模式》

3、参考的项目目录结构

可以参考，可以根据自己团队和实际项目来做改动，规范的最主要目的是统一认知。

├── app/application // App层，处理Adapter层适配过后与框架、协议等无关的业务逻辑
├   ├── api 处理OpenAPI 接口请求
├   ├── web  请求Web页面请求
├   ├── consumer  //（可选）处理外部消息
├   ├── scheduler/task  //处理定时任务，比如Cron格式的定时Job
├── domain // Domain层，最纯粹的业务实体及其规则的抽象定义
│   ├── interface/gateway // 领域网关，model的核心逻辑以Interface形式在此定义，交由biz层去实现
│   └── model // 领域模型实体
├── biz/module 业务/业务模块层
├   └──module1
├        ├──dao 数据库层
├        ├──model 业务模型
├        ├──entity 数据库模型
├        ├──service 业务逻辑
├        └──manager 复用逻辑
├── configs 配置
├── init    //系统初始化
├── pkg
├── public  // 静态公共资源，实际项目会将其存入 CDN
├── build  打包和持续集成
├── scripts // 脚本文件：执行各种构建、安装、分析等操作的脚本
├── test // 单元测试之外的测试程序、测试数据
├── plugin 各种插件
├── util/tools 工具包
├── main.go 项目运行入口
└── pkg // 各层可共享的公共组件代码