Go | Tony Bai - Part 47

标签 Go 下的文章

聊聊Go语言的向前兼容性和toolchain规则

九月 10, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/09/10/understand-go-forward-compatibility-and-toolchain-rule

Go语言在发展演进过程中一直十分注重向后兼容性(backward compatibility)，在Go 1.0版本发布之初就发布了Go1兼容性承诺，简单来说就是保证使用新版本Go(比如Go 1.21版本)可以正常编译和运行老版本的Go代码(比如使用Go 1.18版本语法编写的go代码)，不会出现breaking change(其实也不是绝对的不会出现)。

但是在Go 1.21版本之前，Go语言在向前兼容性方面却存在一定的不确定性问题。Go 1.21版本对此进行了改进，并引入了go toolchain规则。本文就和大家详细聊聊Go语言的向前兼容性以及Go 1.21中新引入的toolchain的使用规则。

1. Go 1.21版本之前的向前兼容性问题

在Go 1.21版本之前，Go module中的go directive用于声明建议的Go版本，但并不强制实施。例如:

// go.mod
module demo1

go 1.20

上面go.mod文件中的go directive表示建议使用Go 1.20及以上版本编译本module代码，但并不强制禁止使用低于1.20版本的Go对module进行编译。你也可以使用Go 1.19版本，甚至是Go 1.15版本编译这个module的代码。

但Go官方对于这种使用低版本(比如L)编译器编译go directive为高版本(比如H)的Go module的结果没有作出任何承诺和保证，其结果也是不确定的。

如果你比较幸运，在module中没有使用高版本(从L+1到H)引入go的新语法特性，那么编译是可以通过的。

如果你更加幸运，你module中的代码没有使用到任何从L+1到H版本中带有语法行为变更、bug或安全漏洞的代码，那么编译出的可执行程序运行起来也可以是正常的。

相反，你可能会遇到编译失败、运行失败甚至运行时行为出现breaking change的问题，而这些都是不确定的。

有gopher可能会说：我自己的代码可以控制，我可以保证避免掉这些问题。但如果你的module有外部依赖，你能保证你的依赖不存在这种向前兼容性的问题吗！

向前兼容性问题会导致Go开发者的体验不佳！因此，从Go 1.21版本开始，Go团队在向前兼容性方面对Go进行了改善，尽量以确定性代替上述的问题带来的不确定性。

下面我们就来看看Go 1.21版本在向前兼容性方面的策略调整。

2. Go 1.21版本后的向前兼容性策略

Go从Go 1.11版本引入go module，在go 1.16版本，go module构建模式正式成为默认构建模式，替代了原先的GOPATH构建模式。

注：《Go语言第一课》专栏的第6讲和第7讲对Go module构建模式与6类常规操作做了全面系统的讲解，感兴趣的童鞋可移步阅读。

通过go module，结合语义导入版本(semantic import versioning)、最小版本选择(Minimal version selection)等机制，go build可以实现精确的依赖管控。

Go 1.21版本后的向前兼容性策略的调整就是参考了go module对依赖的管理方法：即将go版本和go toolchain版本作为一个module的“依赖”来管理。如果你真正理解了这个，那理解后面那些具体的规则就容易多了！

如果Russ Cox当初设计Go module就想到了今天这个思路，估计就会直接使用go.mod文件中的require语法像管理依赖module那样来管理go version和go toolchain了：

// go.mod (假想的)

module demo1

require (
    go 1.20.5
    toolchain go1.21.1
)

require (
    github.com/gomodule/redigo v1.8.5
    github.com/google/gops v0.3.19
    github.com/panjf2000/ants v1.2.1
)

但时间无法倒流，历史不能重来，Russ Cox现在只能使用go directive和toolchain directive来提供对go版本和go工具链的依赖信息：

// go.mod

module demo1

go 1.20.5
toolchain 1.21.1

同时和使用go get可以改变go.mod的require块中的依赖的版本一样，通过go get也可以修改go.mod中go和toolchain指示的版本：

$go get go@1.21.1
$go get toolchain@go1.22.1

基于上述策略调整，为解决向前兼容不确定性的问题，Go从1.21版本开始，改变了go.mod中go directive的语义：它不再是建议，而是指定了module最小可用的Go版本。

这样在仅使用本地go工具链的情况下，如果Go编译器版本低于go.mod中的go版本，将无法编译代码：

// go.mod

module demo1

go 1.21.1 // 指定最小可用版本为Go 1.21.1

$GOTOOLCHAIN=local go build
go: go.mod requires go >= 1.21.1 (running go 1.21.0; GOTOOLCHAIN=local)

细心的读者可能会注意到了，这里我用了一个前提：“在仅使用本地go工具链的情况下(即设置了GOTOOLCHAIN=local)”，在Go 1.21版本之前，我们遇到的都属于这种情况。遇到这种情况后，我们一般的作法是手动下载对应版本的Go工具链(比如这里的go 1.21.1)，然后用新版工具链重新编译。

Go团队考虑到手动管理go工具链带来的体验不佳问题，在Go 1.21版本及以后，go还提供了自动Go工具链管理，如果go发现本地工具链版本低于go module要求的最低go版本，那么go会自动下载高版本的go工具链，缓存到go module cache中(不会覆盖本地安装的go工具链)，并用新下载的go工具链对module进行编译构建：

// go.mod

module demo1

go 1.21.1 // 指定最小可用版本为Go 1.21.1

$go build
go: downloading go1.21.1 (darwin/amd64)

注：从兼容性方面考虑，如果go.mod中没有显式的用go指示go版本，那么默认go版本为1.16。

对应module有依赖的情况，比如下图：

这里要正确编译图中的main module，我们至少需要go 1.21.0版本，这个版本是main所有依赖中version最大的那个。

当然最终选择哪个版本的go工具链对module进行编译，则有一个选择决策的过程。

go module构建模式下，go工具链选择依赖module的版本时有一套机制，比如最小版本选择等，Go 1.21以后，go工具链版本的选择，也有一套类似的逻辑。接下来我们就来简单看一下。

3. module依赖的Go toolchain版本的选择过程

我们先来回顾一下go module中依赖module的版本选择机制：最小版本选择(mvs)，下面的图是讲解这个机制时经常引用的图：

上图来自https://go.dev/ref/mod

以module C的版本选择为例，A依赖C 1.3，B依赖C 1.4，那么满足应用依赖需求的最小版本就是1.4。如果选择1.3，则不满足B对依赖的要求。

对Go toolchain的选择过程也遵循mvs方法，我们把前面的那个例子拿过来：

现在我们帮这个例子选择go toolchain版本。

注：如果go.mod中没有显式用toolchain指示工具链版本，那我们可以认为go.mod中有一个隐含的toolchain指示版本，该版本与go directive指示的版本一致。

上面的例子中对toolchain version的最高要求为module D的go 1.21.0，当startup toolchain(执行的那个go命令的版本)得到这个信息后，就会在当前可用的toolchain版本列表中选出满足go 1.21.0的最小版本的go toolchain，然后会有一个叫Go toolchain switches(Go工具链切换)的过程，切换后，选出的新版go toolchain会继续后面的工作(编译和链接)。例如，如果可用的toolchain版本有如下三个：

go 1.22.7
go 1.21.3
go 1.21.5

那么startup toolchain会根据mvs原则选出满足go 1.21.0的最小版本，即go 1.21.3。

这里大家可能会马上问：什么是可用的toolchain版本？别急！接下来我们就来回答这个问题。

4. GOTOOLCHAIN环境变量与toolchain版本选择

是否执行自动工具链下载和缓存、Go toolchain switches(Go工具链切换)以及切换的工具链的版本取决于GOTOOLCHAIN环境变量的设置、go.mod中go和toolchain指示的版本。

当go命令捆绑的工具链与module的go.mod的go或工具链版本一样时或更新时，go命令会使用自己的捆绑工具链。例如，当在main module的go.mod包含有go 1.21.0时，如果go命令绑定的工具链是Go 1.21.3版本，那么将继续使用初始toolchain的版本，即Go 1.21.3。

而如果go.mod中的go版本写着go 1.21.9，那么go命令捆绑的工具链版本1.21.3显然不能满足要求，那此时就要看GOTOOLCHAIN环境变量的配置。

GOTOOLCHAIN的设置以及对结果的影响略复杂，下面是GOTOOLCHAIN的多种设置形式以及对toolchain选择的影响说明(以下示例中本地go命令捆绑的工具链版本为Go 1.21.0)：

\<name>

例如，GOTOOLCHAIN=go1.21.0。go命令将始终运行该特定版本的go工具链。如果本地存在该版本工具链，就使用本地的。如果不存在，会下载、缓存起来并使用。如果go.mod中的工具链版本高于name版本，则停止编译：

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=go1.21.0 go build
go: go.mod requires go >= 1.23.1 (running go 1.21.0; GOTOOLCHAIN=go1.21.0)

\<name>+auto

当GOTOOLCHAIN设置为\<name>+auto时，go命令会根据需要选择并运行较新的Go版本。具体来说，它会查询go.mod文件中的工具链版本和go version。如果go.mod 文件中有toolchain行，且toolchain指示的版本比默认的Go工具链(name)新，那么系统就会调用toolchain指示的工具链版本；反之会使用默认工具链。

当本地不存在决策后的工具链版本时，会自动下载、缓存，并使用该缓存工具链进行后续编译。

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=go1.24.1+auto go build
go: downloading go1.24.1 (darwin/amd64) // 使用name指定工具链，但该工具链本地不存在，于是下载。

$GOTOOLCHAIN=go1.20.1+auto go build
go: downloading go1.23.1 (darwin/amd64) // 使用go.mod中的版本的工具链

\<name>+path

当GOTOOLCHAIN设置为\<name>+path时，go命令会根据需要选择并运行较新的Go版本。具体来说，它会查询go.mod文件中的工具链版本和go version。如果go.mod 文件中有toolchain行，且toolchain指示的版本比默认的Go工具链(name)新，那么系统就会调用toolchain指示的工具链版本；反之会使用默认工具链。当使用\<name>+path时，如果决策得到的工具链版本在PATH路径下没有找到，那么go命令执行过程将终止。

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=go1.24.1+path go build // 使用name指定工具链，但该工具链本地不存在，于是编译停止
go: cannot find "go1.24.1" in PATH

$GOTOOLCHAIN=go1.20.1+path go build // 使用go.mod中的版本的工具链，但该工具链本地不存在，于是编译停止
go: cannot find "go1.23.1" in PATH

auto (等价于 local+auto，这也是默认值)

auto的语义是当go.mod中工具链版本低于go命令捆绑的工具链版本，则使用go命令运行捆绑的工具链；反之，自动下载对应的工具链版本，缓存起来并使用。

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=auto go build
go: downloading go1.23.1 (darwin/amd64)

path (等价于 local+path)

path的语义是当go.mod中工具链版本低于go命令捆绑的工具链版本，则使用go命令运行捆绑的工具链；反之，在PATH中找到满足go.mod中工具链版本的go版本。如果没找到，则会停止编译过程：

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=path go build
go: cannot find "go1.23.1" in PATH

local

当GOTOOLCHAIN设置为local时，go命令总是运行捆绑的 Go 工具链。如果go.mod中工具链版本高于local的版本，则会停止编译过程。

$cat go.mod
module demo1

go 1.23.1
toolchain go1.23.1 

$GOTOOLCHAIN=local go build
go: go.mod requires go >= 1.23.1 (running go 1.21.0; GOTOOLCHAIN=local)

就像之前说的，当Go工具在编译module依赖项时发现当前go toolchain版本无法满足要求时，会进行go toolchain switches(切换)，切换的过程就是从可用的go toolchain列表中取出一个最适合的。

那么“可用的go toolchain列表”究竟是如何组成的呢？ go命令有三个候选版本(以当前发布的最新版Go 1.21.1为例，这些版本也是Go当前承诺提供support的版本)：

尚未发布的Go语言版本的最新候选版本（1.22rc1）
最近发布的 Go 语言版本的最新补丁 (1.21.1)
上一个Go语言版本的最新补丁版本(1.20.8)。

当GOTOOLCHAIN设置为带auto形式的值的时候，Go会下载这些版本；当GOTOOLCHAIN设置为代path形式的值的时候，Go会在PATH路径搜索适合的go工具链列表。

接下来，go会用mvs(最小版本选择)来确定究竟使用哪个toolchain版本。Go toolchain reference中就有这样一个例子。

假设example.com/widget@v1.2.3需要Go 1.24rc1或更高版本。go命令会获取可用工具链列表，并发现两个最新Go工具链的最新补丁版本是Go 1.28.3和Go 1.27.9，候选版本Go 1.29rc2也可用。在这种情况下，go 命令会选择Go 1.27.9。

如果 widget 需要 Go 1.28或更高版本，go命令会选择 Go 1.28.3，因为 Go 1.27.9 太旧了。如果widget需要Go 1.29或更高版本，go命令会选择Go 1.29rc2，因为Go 1.27.9和Go 1.28.3都太老了。

5. 小结

Go 1.21通过增强go语句语义和添加工具链管理，大幅改进了Go语言的向前兼容性。开发者可以放心使用新语言特性，无需担心旧版本编译器带来的问题。go命令会自动处理不同module使用不同go版本和不同工具链版本的情况，使用Go语言变得更简单。

总之，要理解本文内容，重要的是要把握住一点：Go 1.21版本对Go向前兼容性的改进是参考了go module对依赖的管理方法：即将go版本和go toolchain版本作为一个module的“依赖”来管理。

6. 参考资料

Forward Compatibility and Toolchain Management in Go 1.21 – https://go.dev/blog/toolchain
Go Toolchains reference – https://go.dev/doc/toolchain

“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://gopherdaily.tonybai.com

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite
Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

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

slog实战：文件日志、轮转与kafka集成

九月 4, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/09/04/slog-in-action-file-logging-rotation-and-kafka-integration

《slog正式版来了：Go日志记录新选择！》一文发布后，收到了很多读者的反馈，意见集中在以下几点：

基于slog如何将日志写入文件
slog是否支持log轮转(rotation)，如果slog不支持，是否有好的log轮转插件推荐？
如何与kafka集成
日志输出有哪些最佳实践

这篇文章就是对上述问题进行补充说明的，供大家参考，希望能给大家带去帮助。

1. 输出日志到文件

之所以《slog正式版来了：Go日志记录新选择！》一文中使用的例子都以os.Stdout(标准输出)为log输出目的地，主要是因为基于云原生微服务架构模式下，应用都跑在容器中(k8s的pod中)，基本都是将log输出到Stdout，而不会写入某个具体的本地文件。但如果应用是基于虚拟机或裸机部署，那么将日志写入文件仍然是第一选项。

其实，使用slog内置的TextHandler和JSONHandler可以非常方便的将结构化的日志写入文件，因为slog.NewXXXHandler函数的第一个参数是一个io.Writer，这样通过将一个文件的描述符传递给NewXXXHandler，即可创建一个向文件写入日志的Logger。我们看下面示例代码：

//slog-in-action/log2file/main.go

package main

import (
    "log/slog"
    "os"
)

func main() {
    f, err := os.Create("foo.log")
    if err != nil {
        panic(err)
    }
    defer f.Close()
    logger := slog.New(slog.NewJSONHandler(f, nil))
    slog.SetDefault(logger)
    slog.Info("greeting", "say", "hello")
}

在这个示例中，我们创建了目标日志文件foo.log，并将其描述符(*os.File)传给了NewJSONHandler函数，通过这种方式创建出来的Logger输出的日志内容将会被写入foo.log文件中：

$go run main.go
$cat foo.log
{"time":"2023-09-02T19:38:45.441782+08:00","level":"INFO","msg":"greeting","say":"hello"}

这种方式应该可以满足大多数gopher的需求了。

2. 日志文件的管理

一旦将日志写入文件，后续就要对日志文件进行管理，比如：日志文件的轮转、压缩、归档以及定期清理(腾出磁盘空间)等。

关于如何对日志文件管理的方案大致有这么几种。

第一种是借助外部工具，比如在主流的Linux发行版上都有一个logrotate工具程序，应用程序可以借助该工具对应用输出的日志进行rotate、压缩、归档和删除历史归档日志，这样可大幅简化应用的日志输出逻辑，应用仅需要将日志输出到一个具名文件中即可，其余都交给logrotate处理。关于如何使用logrotate，我在《写Go代码时遇到的那些问题[第1期]》中有详细说明，感兴趣的朋友可以移步阅读一下，这里就不赘述了。

第二种就是log包自身支持。大多数log包都没有将日志文件管理作为自己的功能feature，slog包也是如此，没有原生提供此功能。

第三种就是通过支持log包相关插件接口的一些扩展包来支持。lumberjack就是这样的一个插件包，它支持与很多知名的log包集成在一起实现对log文件的管理，比如logrus、zap等。我曾在《写Go代码时遇到的那些问题[第3期] 》和《一文告诉你如何用好uber开源的zap日志库》两篇文章中分别讲解了logrus和zap与lumberjack集成在一起对日志文件进行管理的方法。如果你对lumberjack不是很熟悉，建议你在继续阅读下面内容之前，温习一下这两篇文章。

在这一篇文章中，我们用示例来简单说说如何将slog与lumberjack集成以实现对log文件的管理功能。看下面示例：

//slog-in-action/lumberjack/main.go

package main

import (
    "log/slog"

    "gopkg.in/natefinch/lumberjack.v2"
)

func main() {
    r := &lumberjack.Logger{
        Filename:   "./foo.log",
        LocalTime:  true,
        MaxSize:    1,
        MaxAge:     3,
        MaxBackups: 5,
        Compress:   true,
    }
    logger := slog.New(slog.NewJSONHandler(r, nil))
    slog.SetDefault(logger)

    for i := 0; i < 100000; i++ {
        slog.Info("greeting", "say", "hello")
    }
}

在这个示例中，我们看到：*lumberjack.Logger实现了io.Writer接口，因为只要将实例化后的*lumberjack.Logger以参数形式传入NewXXXHandler即可完成slog与lumberjack的集成。至于日志文件的管理行为则是通过lumberjack.Logger实例化过程的字段赋值来定制的。比如这里我们指定了目标日志文件名(Filename)为”./foo.log”，指定当文件达到1M字节时(MaxSize)进行rotate，对rotate后的文件进行压缩(Compress)，最多保留5个归档文件(MaxBackups)以及归档文件最多保存3天(MaxAge)等。

运行上述示例程序后，我们将在当前目录想得到如下文件：

$go run main.go
$ls
foo-2023-09-02T08-24-20.854.log.gz  foo-2023-09-02T08-24-20.979.log.gz  foo-2023-09-02T08-24-21.098.log.gz  go.mod  main.go
foo-2023-09-02T08-24-20.918.log.gz  foo-2023-09-02T08-24-21.041.log.gz  foo.log                 go.sum

foo.log是当前正在写入的日志文件，而其他带有时间戳、以gz为后缀的文件则是归档文件。由于有了lumberjack对日志文件的管理，我们就不用再担心日志文件size过大、归档文件过多没有清理而导致的磁盘被占满的问题了。

注：lumberjack.Logger的各个属性字段的配置要根据你的应用实际输出日志的情况、本地磁盘可用空间来确定。

3. 与kafka集成

在我们团队的一个生产项目中，日志是不落盘而直接写入kafka的，关于这个事情，我在《Go社区主流Kafka客户端简要对比》一文中也曾提到过，并给出了基于zap和不同kafka客户端实现向kafka写入日志的方案。

slog与kafka集成的思路也是类似的，不同的是定制KafkaHandler的方法，基于slog，我们要让KafkaHandler实现slog.Handler接口。在《slog正式版来了：Go日志记录新选择！》一文中，我们给出了一个向channel写入结构化日志的示例，KakfaHandler完全可以借鉴其中的ChanHandler，也是通过字节切片来承接JSONHandler写出的日志，不同的是将写入Channel改为通过kafka client写入Kafka! 在这里我就不给出KakfaHandler的实现了，这个作业留给大家，记得实现KafkaHandler后，使用slog/slogtest对其正确性做一个测试！

注：注意在实现KakfaHandler时，考虑goroutine并发使用同一个基于KafkaHandler创建的slog.Logger的情况，也就是字节切片的并发访问和共享的问题。

4. 日志输出的实践建议

在《聊聊Go应用输出日志的工程实践》一文中，我聊了一些在日常使用log时遇到的问题、解决方法以及Go团队对log支持上的问题。log/slog的正式发布，一定程度上解决或改善了那篇文章中提到的部分问题。

此外，在读者关心的日志输出内容方面有哪些实践建议，我也总结了以下几点：

1). 选择合适的日志级别。常见的日志级别包括 DEBUG、INFO、WARNING和ERROR。在生产环境中，我们通常将日志级别设置为WARNING或ERROR，最低是info，不能再低了，避免打印过多日志以影响应用性能。

2). 日志级别要支持热更新。在系统出现异常时，如果要做在线调试，支持热更新的日志级别就特别重要，我们可以在一个调试时间窗口将日志级别下调至info或debug，这样可以抓取到一段时间的详细日志，以供调试和诊断参考。

3). 优先选结构化日志。相对于文本日志更适合人类阅读，结构化日志更适于机器解析、索引和查询。大多数正常情况下，我们是不会去看日志的，日志都会被汇集到集中日志中心存储、管理并索引(比如常见的ELK方案、近来的grafana的PLG方案(Promtail, Loki and Grafana)等)，以便于后续做查询和展示。针对这样的情况，显然结构化日志更适合。

4). 无论使用结构化还是文本形式日志，日志格式都要清晰易读。每条日志至少要打印时间、日志级别、事件源、事件详情等信息，对于固定的字段，要用属性(attribute)来设置，以提高输出性能。

5). 考虑到排查和诊断业务问题，通常会为日志添加上下文信息。比如：在日志中增加关于当前用户、请求ID等上下文信息等。但不应该在日志中输出用户的隐私数据等敏感信息，要么移除，要么做打码处理。

6). 考虑到监控和告警的需要，有些时候我们会对错误日志进行监控，可能会在日志中放置一些具有监控意义的特征字段。

7). 对于日志写入文件的情况，就如本文前面提到的，要考虑日志文件的管理：设置合理的分割轮转日志文件策略以及日志文件的归档管理，避免日志文件的无限增长对磁盘带来的影响。

日志输出内容没有“固定标准”，需根据大家实际所处的业务环境以及相关要求确定。