go.mod - Tony Bai

标签 go.mod 下的文章

Go项目初始化不再困扰你：gonew全方位解析

八月 11, 2023
0 条评论

本文永久链接 – https://tonybai.com/2023/08/11/introduction-to-the-gonew-tool

近日，Go官博介绍了一个名为gonew的新工具。该工具支持基于go project template clone并创建一个属于你的Go项目。gonew工具的引入大幅简化了Go项目的创建，同时由于对自定义项目模板的支持，也可以提高Go项目的标准化水平。gonew工具刚刚被放入Go工具项目代码仓库，目前还处于实验阶段，后续可能会增加新特性，但当前的核心特性(core functionality)会持续保留。

本文将针对gonew目前的特性做简要说明，以供大家参考。

1. 起源

Go team为何要引入gonew这个工具呢？按照Russ Cox的说法，Go team经常收到一些Go用户关于使用某种”go new”功能的要求，即以某种基本的项目模板来创建一个新Go module。于是Russ Cox私下里编写了一个实现了这类核心功能特性的小工具：rsc.io/tmp/gonew。该工具的逻辑非常简单，主要就是下载一个模板module，更改其module path，并将其放到本地的一个新目录中。Russ在google内部宣传该工具后，Google内部的一些团队便定制了一些模板(template)，尤其是ServiceWeaver团队的响应尤为积极。这一切最终让Russ决定引入golang.org/x/tools/cmd/gonew。

我们接下来看看gonew究竟长什么样子，能做什么！

2. 安装和使用gonew

2.1 安装gonew

我们执行下面命令便可以相当容易的将gonew安装到本地(如果设置了GOPATH，那么该工具会安装到GOPATH/bin下)：

$go install golang.org/x/tools/cmd/gonew@latest
go: downloading golang.org/x/tools v0.12.0
go: downloading golang.org/x/mod v0.12.0

执行一下gonew：

$gonew
usage: gonew srcmod[@version] [dstmod [dir]]
See https://pkg.go.dev/golang.org/x/tools/cmd/gonew.

2.2 使用gonew创建新项目

下面是用gonew创建新项目的两个典型场景：

基于模板创建“同名module”项目

以golang.org/x/example/helloserver模板为例，我们基于该模板通过gonew创建一个新项目：

$gonew golang.org/x/example/helloserver
gonew: initialized golang.org/x/example/helloserver in ./helloserver

探索一下该项目：

$ cd helloserver/
$ ls
LICENSE  go.mod  server.go
$ git status
fatal: Not a git repository (or any of the parent directories): .git
$ cat go.mod
module golang.org/x/example/helloserver

go 1.19

我们发现gonew仅是将helloserver模板项目下载到本地（显然不会包含原模板项目的git仓库目录(.git)），且go module的名字也未被改变。

很多人会问：这样的gonew用法用在什么场景中呢？Russ Cox给出了应用场景：

$ gonew book.com/mybook-examples

这个用法适用于在本地创建某图书作者的样例代码项目。

基于模板创建新module项目

这里我们基于helloserver项目模板创建我们自己的github.com/bigwhite/myhelloserver module项目：

$ gonew golang.org/x/example/helloserver github.com/bigwhite/myhelloserver
gonew: initialized github.com/bigwhite/myhelloserver in ./myhelloserver

同样探索一下新创建的项目：

$ cd myhelloserver/
$ ls
LICENSE  go.mod  server.go
$ cat go.mod
module github.com/bigwhite/myhelloserver

go 1.19

我们看到：和第一种用法不同的是，这次go.mod中的module path被改为我们期望的module path。

这种用法应该是gonew最常用的场景。

根据gonew的命令说明，它还支持基于模板项目的特定版本来创建新项目，并支持指定本地存放新项目的路径，这里就不演示了。

3. gonew的项目模板

gonew中提到的项目模板并不神秘，它就是一个go module，这个module具有一些脚手架代码，其存在的目的就是被复用。

google提供了一些模板示例，比如：go team的hello、hellserver和outyet；ServiceWeaver提供的template等。

在gonew出现前，可能很多组织就是这么做的，会定义一些Go脚手架项目作为模板，供大家创建go新项目时参考。Go社区也有很多相似gonew的开源工具，在gonew的讨论帖中，很多人晒了自己的类gonew项目。

有了gonew以后，建立组织级Go项目模板库将会成为提升组织内go项目初始化效率的重要手段，这样做后，组织级go项目标准化程度会得到大幅提升。

4. gonew与Go项目标准布局

可能很多Gopher和我一样，在第一眼看到Go官博关于gonew的文章标题时，以为Go team终于官宣了Go项目的标准布局，并基于gonew工具来创建采用标准布局的新项目。可但我深入读下去后，发现并非如此。

gonew并没有规定Go项目标准布局。gonew是开放性，只要是合法的go module项目都可以作为template在创建新项目时使用。这体现了gonew工具的灵活性和可扩展性，至于将来go team是否会定义一系列的“标准布局”模板还是未知数。

关于Go项目标准布局的思考，请参考我的极客时间专栏《Go语言第一课》的第5讲“标准先行：Go项目的布局标准是什么？”。

5. 小结

gonew工具简化了Go项目初始创建的复杂度，并且基于一些符合Go最佳实践的项目模板，Go初学者可以分分钟得到符合Go最佳实践的目录布局的Go项目。公司和组织层面也可以通过定义专属Go模板来满足组织和公司的内部需要，提高go新项目的创建效率以及提升Go项目布局的标准化程度。新的Go项目的布局的标准化程度提高后，对组织内CI/CD流水线也会更加友好。

gonew的推出得到了社区的欢迎，社区也反馈gonew对快速启动项目很有帮助并提出了一些扩展建议。Russ Cox也说了：不排除在Go后续版本中将gonew升级为go new的可能性。

让我们一起拭目以待吧！

“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

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

理解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来提醒。

img{512x368}

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

我的联系方式：