Github | Tony Bai

标签 github 下的文章

Go项目组织：在单一repo中管理多个Go module指南

五月 10, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/05/10/a-guide-of-managing-multiple-go-modules-in-mono-repo

0. 单repo单module管理回顾

众所周知，Go在1.11版本中引入了go module，随着近几年Go module机制的逐渐成熟，它已经被Go团队确定为Go标准的依赖管理与构建方案，原先的GOPATH mode已经被彻底废弃。

在Go module模式下，最常见的Go项目组织方式就是一个repo(代码仓库)对应一个Go module。repo的根路径中放置go.mod文件，repo的根路径也是module root directory。该Go module下的package的导入路径则由go.mod中的module path以及该package相对于module root directory的路径共同构成。

以“example.com/go”这一module path为例，如果某个package存放在foo/bar下，那么bar下的package的导入路径就是“example.com/go/foo/bar”；如果是v2版本，那么导入路径为“example.com/go/v2/foo/bar”。

在一个repo对应一个Go module的策略下，Go module的版本管理和发布也相对容易，通常我们采用分支方式来进行major号升级(如下图)，通过tag来进行版本发布。

上图是单repo单module的分支管理方案，两种方案均可。

左侧的方案中：master分支承载v0-v1，每升级一个major号，建立一个vN分支，default分支指向最高major号的分支，方便开发者clone repo时直接拿到最新的代码。

注：左侧方案有一个问题，那就是一旦default分支执行最高major号分支vN，那么你如果要go get master分支的最近更新，需要显式指定master分支，比如: go get example.com/go/foo/bar@master。使用latest或不加任何分支名都无法获取到master上的最新更新。

右侧的方案也是建立vN分支，但不同的是，该方案会将master分支作为active开发分支，也是默认分支并定期将稳定后的feature同步到最高major号分支，这也是我个人比较喜欢的方式。前不久刚刚被官宣为redis官方Go客户端的go-redis采用的就是这个方案(下面是go-redis的vN分支情况)：

注：在单一repo中管理一个go module的方法十分成熟了。我在专栏《Go语言第一课》的06和07讲对此做了系统的讲解，感兴趣的小伙伴可以去阅读一下。

有了单repo单module的项目组织方式，就会有单repo多module的组织方式，比如著名的etcd项目，就是在一个repo中管理多个go module的典型例子。

那么为什么要在一个repo中管理多个go module呢？我们继续往下看。

1. 为什么要在一个repo中管理多个Go module

其实这个问题的本质是monorepo与multiple repo之间的“战争”。那么上述问题也就变成了一个monorepo与multiple repo的优劣对比。我个人从未真正使用过monorepo这种所有项目代码都放在一个单一仓库中的组织形式，不过从网上的公开资料来看，monorepo有如下的一些优点：

容易看到

如果你正在做一个调用其他微服务的微服务，你可以看一下代码，了解它是如何工作的，并确定bug是来自你自己的代码还是其他团队的微服务。

代码共享

团队为微服务重复编写代码会产生额外的工作开销。有了monorepo，团队可以更容易地分享代码。

改进协作

有了monorepo，就更容易在各团队之间实现代码和工具的标准化。

标准化

单一代码仓库使得跨团队的代码和工具的标准化更加容易。

可发现性

有了monorepo，更容易找到你需要的代码。

发布管理

单一版本使我们更容易地管理跨多个服务的发布。

更容易重构

重构代码在单版本中更容易，因为所有的代码都在一个地方。

当然，使用单一代码仓库也有一些缺点，这些缺点也足以让很多组织和开发团队对其望而却步：

增加仓库的大小

一个单库通常会比只包含一个项目的版本库大。这可能会导致更长的构建时间和更多的磁盘空间使用。

增加复杂性

单一代码仓库的管理比只包含一个项目的版本库更复杂。这是因为有更多的代码需要跟踪和管理。

增加冲突的风险

当多个开发者在单一仓库中处理相同的代码时，会有更大的冲突风险。这是因为开发人员可能在同一个代码的不同版本上工作。

不能限制访问

monorepo不允许有选择的分享。

陡峭的学习曲线

当新的开发者开始与已经有monorepo的组织合作时，他们通常需要足够长的时间来适应所有紧密耦合的依赖关系。

总的来说，使用monorepo既有优点也有缺点，是否使用monorepo最终还是要取决于项目和团队的具体需求。

不过，monorepo下的多module是实际存在的，并且Google内部就是如此，显然go module也一定要对此做很好的支持的，下面我们就来看看go是如何支持mono repo下的多个go module的。

我们先来看看mono repo下各个go module的导入路径的确定。

2. monorepo中各个go module下的package的导入路径

在前面回顾单repo单module的项目组织方式下，module下的package的导入路径为：module path+package在module root directory下的相对路径。那么monorepo中各个go module下的package的导入路径又是什么呢？

首先monorepo下的各个go module的module root路径并非monorepo的root路径，以下面的结构举例；

example.com
└── go/
    ├── mqtt/
    │   ├── bar/
    │   │   └── go.mod
    │   └── foo/
    │       └── go.mod
    └── vehicle/
        ├── baz/
        │   └── go.mod
        └── zoo/
            └── go.mod

我们看到在example.com这个顶层目录下并没有go module，go modules分布在example.com下的各个子目录中。以mqtt/bar下的go module为例，它的module path应该为repo根路径+bar的相对路径，即example.com/go/mqtt/bar，这样bar下面的package pkg1，它的导入路径就为example.com/go/mqtt/bar/pkg1，如果bar这个go module升级到v2版本，则pkg1的导入路径就会变为example.com/go/mqtt/bar/v2/pkg1。其余的go module下的packge的导入路径以此类推。

3. monorepo下各个go module的版本发布

在单repo单module下，我们通过打vx.y.z标签的方式发布module，但是在monorepo多module下，再在repo上针对repo打整体的、诸如v1.0.1这样的标签就没有太大意义了(当然为了整体管理的需要，依然可以打整体标签，比如像etcd那样打v3.5.8)，并且对于monorepo下的多个go module而言，go get也不会识别这种整体标签，那么我们该如何发布monorepo下的go module呢？

其实也很简单，我们为module单独打标签来发布。以上面的example.com/go/mqtt/bar这个module为例，如果我们要为其发布v1.0.0版本，我们需要为example.com这个repo打上tag：go/mqtt/bar/v1.0.0；如果它要发布v1.1.0版本了，我们则需为example.com这个repo打上tag：go/mqtt/bar/v1.1.0。也就是说要发布哪个module，就用module相对于monorepo根的相对路径+版本号作为tag号。

4. monorepo下各个go module的major版本变更

了解了上述monorepo下各个go module的版本发布方式后，我们就可以将monorepo下的每个go module像单repo单module那样单独对待了！以example.com/go/mqtt/bar为例，当major版本变更时，我们可以建立类似go/mqtt/bar/v1分支，然后将master分支的go.mod中的module path改为example.com/go/mqtt/bar/v2，这样我们就可以在go/mqtt/bar/v1分支继续维护v1版本的bar module，并打tag：go/mqtt/bar/v1.x.y；在master分支维护v2版本的bar module，并打tag：go/mqtt/bar/v2.x.y。

当然go还支持另外一种major版本的维护方式，那就是通过目录隔离。当major版本要升级为v2时，我们可以在go/mqtt/bar下面建立v2目录(像v2这类目录被称为major version subdirectories)，然后在v2目录下维护major为v2的版本，这种方式下你就无需建立vN分支了，可以在master上通过目录隔离的方式同时维护多个major版本。发布时，同样打go/mqtt/bar/v2.x.y标签。这种方式一个最大的好处就是与GOPATH mode可以“无缝衔接”，因为GOPATH mode下，go工具链就是通过路径查找package的。

不过这种major version subdirectories的方式并不常用，即便在开源项目中也是比较少见的。

5. 小结

本文介绍了go module的基础概念，回顾了单repo单module的包管理方法，包括版本发布、major号升级等。接下来，我们介绍了monorepo下管理多个go module的方案，除了在打tag时要注意带上相对路径外，monorepo下module的包管理方法与单repo单module本质上是一致的。

6. 参考资料

REPO STYLE WARS: MONO VS MULTI – https://gigamonkeys.com/mono-vs-multi/
Mono Repo vs Multi Repo: Deep Dive Into The Neverending Debate – https://speakerdeck.com/lemiorhan/mono-repo-vs-multi-repo-deep-dive-into-the-neverending-debate

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

理解unsafe-assume-no-moving-gc包

四月 16, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/04/16/understanding-unsafe-assume-no-moving-gc

1. 背景

在之前的《Go与神经网络：张量计算》一文中，不知道大家是否发现了，所有例子代码执行时，前面都加了一个环境变量ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH，就像下面这样：

$ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH=go1.20 go run tensor.go

这是怎么回事儿呢？如果不加上这个环境变量会发生什么呢？我们来试试：

// https://github.com/bigwhite/experiments/blob/master/go-and-nn/tensor-operations/tensor.go

$go run tensor.go
panic: Something in this program imports go4.org/unsafe/assume-no-moving-gc to declare that it assumes a non-moving garbage collector, but your version of go4.org/unsafe/assume-no-moving-gc hasn't been updated to assert that it's safe against the go1.20 runtime. If you want to risk it, run with environment variable ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH=go1.20 set. Notably, if go1.20 adds a moving garbage collector, this program is unsafe to use.

goroutine 1 [running]:
go4.org/unsafe/assume-no-moving-gc.init.0()
    /Users/tonybai/Go/pkg/mod/go4.org/unsafe/assume-no-moving-gc@v0.0.0-20220617031537-928513b29760/untested.go:25 +0x1ba
exit status 2

我们看到，程序panic了！我们看到panic的错误信息提到了go4.org/unsafe/assume-no-moving-gc这个包，显然是这个包在“作祟”，那么assume-no-moving-gc这个包究竟是做什么的呢？究竟有何功用？为何gorgonia.org/tensor会依赖这个包？这超出了《Go与神经网络：张量计算》那篇文章的范畴，所以我并未提及。在这篇文章中，我就和大家一起来理解一下unsafe-assume-no-moving-gc这个包。

2. unsafe-assume-no-moving-gc究竟是什么包？

unsafe-assume-no-moving-gc这个包的canonical import path是go4.org/unsafe/assume-no-moving-gc，显然它是go4.org这个组织开源的包。我们看看go4.org的主页(如下图)：

这个站点主页非常“简陋”，最大的价值在于解释了go4的来历：gopher的谐音。go4.org开源了一些Go包，这个在其官方github站点可以看到：

项目不多，Star数也不多，但随便翻看一个项目的contributor，我们能看到前Googler、前Go核心团队成员、net/http包的设计者Brad Fitzpatrick(bradfitz)以及Go runtime的核心贡献者Josh Bleecher Snyder(josharian)。现在这两人似乎都在初创公司tailscale任职，做基于wireguard协议的远程安全控制平台(简单理解就是VPN平台)。tailscale汇集了一撮Go语言的原核心开发，go4.org就是他们开源的一些misc go包。而unsafe-assume-no-moving-gc这个包就是其中之一。

那么这个包究竟是做什么的呢？我们接着往下看。

3. unsafe-assume-no-moving-gc的工作原理

unsafe-assume-no-moving-gc是一个非常简单的包：

$tree unsafe-assume-no-moving-gc -F
unsafe-assume-no-moving-gc
├── LICENSE
├── README.md
├── assume-no-moving-gc.go
├── assume-no-moving-gc_test.go
├── go.mod
└── untested.go

0 directories, 6 files

除了test源文件外，它的源文件只有两个assume-no-moving-gc.go和untested.go。打开这两个源文件，你会发现这个包甚至都没有提供任何API。那这个包究竟是做什么用的呢？下面是这个包的README：

大致的理解就是如果你的代码中使用了Go中的unsafe tip，那么你的程序可以正常工作的前提是Go运行时垃圾回收器不是一个带迁移机制的回收器(collector)。

所谓带迁移机制的collector，即在GC回收时可能将某些heap object挪到其他内存地址上。你的程序如果导入unsafe-assume-no-moving-gc这个包，就可以在Go GC支持迁移机制时以“程序启动崩溃”的行为提醒你。

我们来看一个例子：

// main.go
package main

import (
    "fmt"

    _ "go4.org/unsafe/assume-no-moving-gc"
)

func main() {
    fmt.Println("unsafe-assume-no-moving-gc demo")
}

go mod tidy后，使用Go 1.20版本运行该源文件：

$go mod tidy
go: finding module for package go4.org/unsafe/assume-no-moving-gc
go: downloading go4.org/unsafe/assume-no-moving-gc v0.0.0-20230221090011-e4bae7ad2296
go: downloading go4.org v0.0.0-20230225012048-214862532bf5

$go run main.go
unsafe-assume-no-moving-gc demo

由于目前最新Go 1.20.x版本的GC并非带迁移机制的GC，因此使用Go 1.20跑上面程序不会导致panic。

我们将unsafe-assume-no-moving-gc包回退到以前的版本，比如：v0.0.0-20230221090011-e4bae7ad2296，然后再run一遍main.go：

$go get go4.org/unsafe/assume-no-moving-gc@v0.0.0-20201222180813-1025295fd063
go: downgraded go4.org/unsafe/assume-no-moving-gc v0.0.0-20230221090011-e4bae7ad2296 => v0.0.0-20201222180813-1025295fd063

$go run main.go
panic: Something in this program imports go4.org/unsafe/assume-no-moving-gc to declare that it assumes a non-moving garbage collector, but your version of go4.org/unsafe/assume-no-moving-gc hasn't been updated to assert that it's safe against the go1.20 runtime. If you want to risk it, run with environment variable ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH=go1.20 set. Notably, if go1.20 adds a moving garbage collector, this program is unsafe to use.

goroutine 1 [running]:
go4.org/unsafe/assume-no-moving-gc.init.0()
    /Users/tonybai/Go/pkg/mod/go4.org/unsafe/assume-no-moving-gc@v0.0.0-20201222180813-1025295fd063/untested.go:24 +0x1ba
exit status 2

从输出的panic error信息中，我们看到go4.org/unsafe/assume-no-moving-gc尚未被升级到可以信任go 1.20版本的版本，因此以Go 1.20运行该程序可能有风险。如果你能确认不会存在问题，可以用ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH=go1.20这个环境变量来避免panic，比如下面这个输出：

$ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH=go1.20 go run main.go
unsafe-assume-no-moving-gc demo

那么unsafe-assume-no-moving-gc包是怎么做到上述“检测”的呢？其诀窍就在untested.go这个源文件中。我们下载go4.org/unsafe/assume-no-moving-gc源码，并将其“回退”到1025295fd063这个commit时刻：

$git checkout 1025295fd063
Note: checking out '1025295fd063'.

... ...

HEAD is now at 1025295 flesh out package doc

查看untested.go：

// Copyright 2020 Brad Fitzpatrick. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// +build go1.18

package assume_no_moving_gc

import (
    "os"
    "runtime"
    "strings"
)

func init() {
    dots := strings.SplitN(runtime.Version(), ".", 3)
    v := runtime.Version()
    if len(dots) >= 2 {
        v = dots[0] + "." + dots[1]
    }
    if os.Getenv(env) == v {
        return
    }
    panic("Something in this program imports go4.org/unsafe/assume-no-moving-gc to declare that it assumes a non-moving garbage collector, but your version of go4.org/unsafe/assume-no-moving-gc hasn't been updated to assert that it's safe against the " + v + " runtime. If you want to risk it, run with environment variable " + env + "=" + v + " set. Notably, if " + v + " adds a moving garbage collector, this program is unsafe to use.")
}

这个文件有两个特点：

使用了build constraint：// +build go1.18，这意味着在你使用Go 1.18及更高版本时，该源文件才会参与编译。
包含了init函数，你的代码在导入assume_no_moving_gc包时，该init函数会执行，产生“副作用”。

注：关于build constraint的用法，参见go help buildconstraint。

这样，我们使用go 1.20版本运行上面main.go时，由于go 1.20版本大于go 1.18版本，untested.go将被编译且其中的init函数将被执行，如果env这个常量(“ASSUME_NO_MOVING_GC_UNSAFE_RISK_IT_WITH”)所对应的环境变量没有设置，那么init函数将走到panic，从而导致程序退出并输出panic信息。

现在我们将assume_no_moving_gc包的版本切换回最新版本，最新版本的untested.go中的build constraint如下：

  //go:build go1.21
  // +build go1.21

这意味着你使用Go 1.21或以上版本时，untested.go文件才会被编译，如果我们使用go 1.20版本运行main.go，我们便不会“触发”untested.go中init函数的副作用，于是main.go得以正常运行。

注：截至go 1.20版本，Go GC依然不会挪动heap object。

在理解unsafe-assume-no-moving-gc包之前，我就该包的功用“咨询”了ChatGPT，ChatGPT的回答如下：

可以看出，ChatGPT基本上是一本正经地“胡说八道”。

4. 小结

unsafe-assume-no-moving-gc只针对GC对heap object的迁移，而不会保证栈地址的迁移，我们知道，Go中栈地址是会变的，因为goroutine的初始栈才2KB，一旦超出这个范围，Go runtime就会对栈进行扩展，即分配一个更大的地址范围作为goroutine的栈，然后将原栈上的变量迁移到新栈中，这样原先栈上变量的地址就都会发生变化。

不过，如果你的Go源码中采用了unsafe tips，依赖了heap object的地址，那么这里建议你导入unsafe-assume-no-moving-gc包。但要注意，随着go最新版本的发布，你要及时更新依赖的unsafe-assume-no-moving-gc的版本。否则当用户使用最新版本go时，依赖你的包的程序就会以panic来提醒。