Go项目结构最佳实践与wangyoucao577/go-project-layout插件库讨论

Go项目布局

这是我对于如何构建Go项目结构的理解。最重要的部分是如何将Go代码组织成包。

动机

一个好的项目结构将使你的源代码易于理解、易于测试和易于维护。Kat Zien对此有一个很好的总结，我直接引用如下：

问题与决策

• 我应该把所有内容都放在main包中吗？
• 我应该从一个包开始，然后随着时间的推移提取其他包吗？
• 如何决定某些东西是否应该放在自己的包中？
• 我应该直接使用框架吗？
• Go的编程范式是什么？
• 微服务还是单体架构？
• 包之间应该共享多少内容？

为什么我们应该关心？

因为如果Go将成为公司长期投资的语言，那么Go程序的维护和修改的便利性将是他们决策的关键因素。 - Dave Cheney, Golang UK 2016 keynote

良好结构的目标

• 一致
• 易于理解、导航和推理（“有意义”），易于更改，松耦合
• 易于测试
• “尽可能简单，但不要过于简单”
• 设计准确反映软件的工作方式
• 结构准确反映设计

演示

# shell 1
$ go version
go version go1.13.1 linux/amd64

$ cd $GOPATH

# 应用1: 反向回显
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/echor
$ ./bin/echor "hello world"
dlrow olleh

# 应用2: 简单的诊断服务
$ go get -u github.com/wangyoucao577/go-project-layout/cmd/diagnosis
$ ./bin/diagnosis -alsologtostderr
I1007 18:50:05.550952    3769 main.go:33] Listen on :8000

# shell 2
$ curl "http://localhost:8000/diagnosis?diagnosis=ping"
{
  "Hostname":"server",
  "IP Addresses":[
    "192.168.29.201/24",
    "fe80::1c20:479:9094:4327/64",
    "192.168.141.1/24",
    "fe80::8002:2d87:c4f3:4aab/64",
    "192.168.128.1/24",
    "fe80::eca9:cfa0:9443:b8ff/64",
    "192.168.44.209/28",
    "fe80::8551:306e:7e7:6faf/64"
  ],
  "CPUs":8,
  "Remote Endpoint":"127.0.0.1:64717"
}

注意事项

这个主题属于最佳实践范畴。我想讨论其中的一些内容以及我的观点，未来可能会深入探讨更多最佳实践。

顶级目录/cmd

[我的观点：强烈推荐] 当需要多个应用程序二进制文件时，cmd布局模式非常有用。

• 每个二进制文件获得一个子目录（例如your_project/cmd/your_app）
  • 子目录是应用程序的main包
  • 不要在main包中放入大量代码。它应该只用于初始化和将所有内容连接在一起
• 这种模式也有助于保持项目/包可go get
  • 意味着你可以使用go get命令获取（和安装）你的项目、其应用程序和库
• 官方Go工具是cmd布局模式的一个例子。许多其他知名项目也使用相同的模式：Kubernetes、Docker、Prometheus、Influxdb

顶级目录/pkg

[我的观点：不够好，如果对你有用可以使用]

• 人们还建议在Go项目中设置一个/pkg顶级目录来放置公共库
  • 这些库可以被你的应用程序内部使用
  • 也可以被外部项目使用。这是你和其他外部代码用户之间的非正式合同
• 但我认为这不是一个足够好的想法，因为：
  • 它带来了混淆，因为Go工作区有一个同名的目录，目的不同
  • "公共库"的含义不够明确
  • 即使许多知名项目使用这种模式（Kubernetes、Docker、Grafana、Influxdb、Etcd），Docker和Etcd都再次注释了"公共库"的含义。两者都将其限制为实用程序包，这些实用程序包未来可能会移出到自己的仓库中

按依赖关系分组包

[我的观点：强烈推荐]

• 领域类型
  • 领域类型是建模你的业务功能和对象的类型
  • Ben Johnson - Standard Package Layout建议将它们放入根包中。这个包只包含简单的数据类型，因此会非常简单
  • 在我看来，将它们放入根包或单独的子包都可以。最重要的是这个包应该非常简单，并且不依赖于应用程序中的任何其他包！
• 每个包应该只有一个目的
• 包名描述它们的目的
• 必要时，使用描述性的父包和几个实现功能的子包
  • 就像encoding包
• main包连接依赖关系

更多最佳实践

• 遵循约定
  • 与标准库和其他流行包相似
  • 不要让人惊讶
  • 明显而不是聪明
• 使用Go模块
• 避免全局范围和init()

示例项目结构

以下是一个基于wangyoucao577/go-project-layout的示例项目结构：

my-go-project/
├── cmd/
│   ├── app1/        # 第一个应用程序
│   │   └── main.go
│   └── app2/        # 第二个应用程序
│       └── main.go
├── internal/        # 私有应用程序和库代码
│   ├── pkg1/        # 私有包1
│   └── pkg2/        # 私有包2
├── pkg/             # 公共库代码（可选）
│   ├── lib1/        # 公共库1
│   └── lib2/        # 公共库2
├── api/             # API定义
├── configs/         # 配置文件
├── scripts/         # 脚本
├── build/           # 打包和持续集成
├── deployments/     # 部署配置
├── test/            # 测试
├── docs/            # 文档
├── tools/           # 支持工具
├── go.mod           # Go模块定义
└── README.md        # 项目说明

示例代码

以下是一个简单的示例，展示如何使用wangyoucao577/go-project-layout中的结构：

// cmd/echor/main.go
package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/wangyoucao577/go-project-layout/internal/stringutil"
)

func main() {
	if len(os.Args) < 2 {
		fmt.Println("Usage: echor <string>")
		os.Exit(1)
	}

	input := strings.Join(os.Args[1:], " ")
	reversed := stringutil.Reverse(input)
	fmt.Println(reversed)
}

// internal/stringutil/stringutil.go
package stringutil

// Reverse returns its argument string reversed rune-wise left to right.
func Reverse(s string) string {
	r := []rune(s)
	for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
		r[i], r[j] = r[j], r[i]
	}
	return string(r)
}

这个示例展示了如何组织一个简单的Go项目，其中：

1. cmd/echor包含应用程序入口
2. internal/stringutil包含可重用的内部工具函数
3. 主程序只负责参数处理和结果输出，业务逻辑放在单独的包中

结论

Go项目结构的最佳实践应该关注：

1. 清晰的组织和分离关注点
2. 可维护性和可扩展性
3. 易于测试
4. 遵循社区约定

wangyoucao577/go-project-layout提供了一个实用的参考实现，展示了如何组织包含多个应用程序的Go项目。虽然它不是官方标准，但借鉴了Kubernetes、Docker等大型项目的经验，可以作为你项目结构的良好起点。