阅读本文大概需要 10分钟。

大家好,我是站长 polarisxu。

在 Reddit 上看到一条消息:

go-chi is retracting all major versions with go1.16 new retract directive.

go.mod 的变更如下:

这利用了 Go 1.16 中 Module 的新特性。在这之前,先一起学习下该特性。

01 retract:撤回版本

也许不少人没有开发过自己的 Module(模块),但了解模块版本撤回还是有必要的,说不定哪天就能用到。因此建议你能够跟着本文操作一遍。

一般地,模块作者需要一种方法来指示不应该使用某个已发布的模块版本。可能出于以下几点原因

作者不能简单地删除版本标签(tag),因为它们很可能在模块代理上仍然可用。如果作者能够从所有代理中删除一个版本,那么依赖该版本的下游用户就会无法使用,出问题。

此外,作者在发布了 go.sum 文件之后也不能更改版本,校验和数据库会验证发布的版本从未更改。

那怎么办?作者应该能够撤回模块版本。撤回的模块版本是模块作者明确声明不应该使用的版本。(retract 这个词是从学术文献中借来的:一篇被撤回的研究论文仍然可用,但是它有问题,不应该成为未来工作的基础)。

撤回的版本应该在模块代理和原始代码库中保持可用。依赖已撤回版本的构建应可以继续工作。当用户依赖于一个已撤回的版本(直接或间接)时,应该通知用户。它也应该很难无意中升级到一个已撤回版本。

为了让大家更好的理解模块撤回功能,本文通过具体的例子来演示。我们会创建两个模块:

注意,请确保 Go 版本是 1.16+。

本文演示用的操作系统是 MacOS。

创建 foo 模块

$ mkdir -p ~/foo
cd ~/foo
$ git init -q
$ git remote add origin https://github.com/polaris1119/foo
$ go mod init github.com/polaris1119/foo
go: creating new go.mod: module github.com/polaris1119/foo

在模块目录中创建一个文件 foo.go,输入如下内容:

package foo

func Bar() string {
  return "这是初始版本"
}

注意:在把该模块代码提交之前,先在 GitHub 上创建好项目 foo。

将 foo 模块的改动提交 git 并 push。

go web 不用框架_go框架_go语言 web框架

$ git add -A
$ git commit -q -m "Initial commit"
$ git branch -M main
$ git push -u origin main

这是该模块的初始版本,我们用 v0 语言版本来标记它,表明它还不稳定。

$ git tag v0.1.0
$ git push -q origin v0.1.0

foo 的第一个版本已经发布,我们看看使用它的 gopher 模块。

创建 gopher 模块

该模块就放在本地,因此不用设置 git:

$ mkdir ~/gopher
cd ~/gopher
$ go mod init gopher

创建一个 main.go 文件,内容如下:

package main

import (
    "fmt"

    "github.com/polaris1119/foo"
)

func main() {
     fmt.Println(foo.Bar())
}

接下来,我们通过 go get 显示指定依赖 foo 的版本:

$ go get github.com/polaris1119/foo@v0.1.go
go: downloading github.com/polaris1119/foo v0.1.0
go get: added github.com/polaris1119/foo v0.1.0

注意:我本地配置了 GOPROXY=https://goproxy.cn,direct

然后运行:

$ go run .
这是初始版本

目前一切正常。

一个更好的版本

经过一段时间,foo 的功能有一些变化,这里假设 Bar 方法语句变了(一个兼容的变化)。

回到 foo 模块,修改代码如下:

package foo

func Bar() string {
  return "这是一个更好的版本"
}

提交并推送到 GitHub。

但现在 foo 模块还不是稳定版,因此不想标记为 v1。安全起见,我们发布 v0.2.0:

$ git tag v0.2.0
$ git push -q origin v0.2.0

现在 foo 发布了 v0.2.0 版本,我们在 gopher 项目尝试下。

cd ~/gopher
$ go get github.com/polaris1119/foo@v0.2.0
go: downloading github.com/polaris1119/foo v0.2.0
go get: upgraded github.com/polaris1119/foo v0.1.0 => v0.2.0

然后 go run 运行:

$ go run .
这是一个更好的版本

这时,你发现 “这是一个更好的版本” 不好,怎么办?你可以修改掉,然后再发布一个新版本。然而,gopher 项目已经依赖了 v0.2.0,怎么办?

撤回模块版本

我们可以在 go.mod 中增加 retract 指令来撤回某个模块版本。

可以通过命令实现:(也可以直接修改 go.mod 文件)

$ go mod edit -retract=v0.2.0

这时 go.mod 内容如下:

module github.com/polaris1119/foo

go 1.16

retract v0.2.0

一般建议在 retract 上加上撤回的原因。go get、go list 等会显示这个原因。

module github.com/polaris1119/foo

go 1.16

// Bar 方法返回值不友好
retract v0.2.0

修改下 Bar 的返回内容,提交 GitHub 并发布 v0.3.0:

func Bar() string {
  return "这是v0.3.0版本"
}

v0.3.0 发布后,回到 gopher 模块,使用这个新版本。

cd ~/gopher
$ go get github.com/polaris1119/foo@v0.3.0
go: downloading github.com/polaris1119/foo v0.3.0
go get: upgraded github.com/polaris1119/foo v0.2.0 => v0.3.0

这一步确保 这个代理知晓了 v0.3.0 版本,这是一种手动让代理拉取你模块的方法。

$ go run .
这是v0.3.0版本

已经正常了。

go web 不用框架_go语言 web框架_go框架

经过这个步骤到底发生了什么?我们通过以下命令看一下:

$ go list -m -versions github.com/polaris1119/foo
github.com/polaris1119/foo v0.1.0 v0.3.0

v0.2.0 不见了。通过增加 -retracted 选项可以查看撤回的版本:

$ go list -m -versions -retracted github.com/polaris1119/foo
github.com/polaris1119/foo v0.1.0 v0.2.0 v0.3.0

如果我们依赖回收的 v0.2.0 版本会怎么样了?

$ go get github.com/polaris1119/foo@v0.2.0
go: warning: github.com/polaris1119/foo@v0.2.0: retracted by module author: Bar 方法返回值不友好
go: to switch to the latest unretracted version, run:
 go get github.com/polaris1119/foo@latest go get: downgraded github.com/polaris1119/foo v0.3.0 => v0.2.0

提示信息还是挺友好的,告知你 v0.2.0 是一个撤回的版本。

虽然警告,但 v0.2.0 可以正常使用吗?

$ go run .
这是一个更好的版本

发现一切正常。

有了这个功能,有一些模块可能会使用它。那怎么知晓我们的项目有没有依赖撤回的版本呢?使用 go list 命令即可:

$ go list -m -u all
gopher
github.com/polaris1119/foo v0.2.0 (retracted) [v0.3.0]

我们现在回到最新版本:

$ go get github.com/polaris1119/foo@latest
go get: upgraded github.com/polaris1119/foo v0.2.0 => v0.3.0

为 foo 模块增加功能

又过了一段时间,我们为 foo 模块增加了新的功能:

func Quz() string {
    return "This is Quz function"
}

提交到 GitHub,并发布 v0.4.0,依然是不稳定版本。

$ git tag v1.0.0
$ git push -q origin v1.0.0

但很糟糕的是,我不小心发布了 v1.0.0,这样会让用户以为你的模块已经是稳定版本,但实际上并不是这样。所以,我们想撤回 v1.0.0。

在撤回这个版本之前,我们应该先发布 v0.4.0 版本:

go语言 web框架_go web 不用框架_go框架

$ git tag v0.4.0
$ git push -q origin v0.4.0

要撤回 v1.0.0,我们需要发布 v1.0.1(为什么?因为我们要写入撤回的信息)。不过这样一来,我们还得撤回 v1.0.1,死循环了。。。go module 允许我们指定一个撤回的版本范围,这次手动编辑 go.mod 文件。

module github.com/polaris1119/foo

go 1.16

retract (
    // Bar 方法返回值不友好
    v0.2.0

    // v1 提前发布了
    [v1.0.0, v1.0.1]
)

提交这次改动到 GitHub,然后再创建 v1.0.1 版本。

$ git tag v1.0.1
$ git push -q origin v1.0.1

接着切到 gopher 模块。

为了让 知晓 v1.0.0 等版本,我们先获取它。

$ go get github.com/polaris1119/foo@v1.0.0
$ go get github.com/polaris1119/foo@v1.0.1
$ go get github.com/polaris1119/foo@v0.4.0

注意,切换到 v1.0.x 版本时,很可能看不到版本撤回的信息,因为 proxy 可能还没自动定期更新。一般需要等待一段时间,比如 1 分钟。如果没有看到警告信息,等待 1 分钟后再试,应该能看到。

现在列出所有的版本:

$ go list -m -versions -retracted github.com/polaris1119/foo
github.com/polaris1119/foo v0.1.0 v0.2.0 v0.3.0 v0.4.0 v1.0.0 v1.0.1

或只列出未撤回版本:

$ go list -m -versions github.com/polaris1119/foo
github.com/polaris1119/foo v0.1.0 v0.3.0 v0.4.0

赞!v0.4.0 是该模块的新版本。

这时可以更新下 gopher,来使用 foo 的新功能:(加上对 foo.Quz 函数的调用)

$ go run .
这是v0.3.0版本
This is Quz function

提示:如果你将来要发布 v1 稳定版,应该从 v1.0.2 开始,因为 v1.0.0 和 v1.0.1 被占用了。

02 关于 incompatible

讲解完 retract 指令后,先看本文开头截图中的另外一个东西:incompatible。

在 go-chi 框架中,v2.x.x、v3.x.x 和 v4.x.x 都加上了 incompatible,这是什么意思?

Go 模块的版本号需要遵循 v..

go框架_go语言 web框架_go web 不用框架

的格式,当 major 大于 1 时,版本号需要体现在模块名中,比如 Echo 框架:github.com/labstack/echo/v4。

然而,由于 Go 模块功能出现较晚(Go1.11 才出现),在它出现之前,很多项目的版本号已经大于 1 了,比如 Echo 框架,这些版本连 go.mod 文件都没有,更别提模块名加上版本号。于是,这些版本就会有 incompatible 标记。

因为模块名没有版本信息,导致无法判断版本的兼容性问题,比如 v2.x.x 和 v3.x.x 都是 incompatible 的,使用 v2.x.x 的项目,更新依赖时,会直接升级到 v3.x.x,这显然是不行的,因此才标记它们为 incompatible(不兼容)。

你可以在上面做这个试验:新增版本 v2.0.0,但不修改 go.mod 文件中的 module 名,看看最新版本是否会带 incompatible。

一般不建议项目使用 incompatible,毕竟稳定性没法保证,它是不符合 Go Module 规范的。

03 go-chi 撤回所有主版本

先介绍下 chi 这个框架:

lightweight, idiomatic and composable router for building Go HTTP services

它主要强调自己是一个路由,方便构建 HTTP 服务。它兼容 net/http,没有任何第三方依赖。

简单使用示例:

package main

import (
 "net/http"

 "github.com/go-chi/chi"
 "github.com/go-chi/chi/middleware"
)

func main() {
 r := chi.NewRouter()
 r.Use(middleware.Logger)
 r.Get("/"func(w http.ResponseWriter, r *http.Request) {
  w.Write([]byte("welcome"))
 })
 http.ListenAndServe(":3000", r)
}

有兴趣的自己去了解。这里主要说下它撤回主版本的事情。

chi 保证自己有很好的兼容性,而作者特别厌烦模块名带版本号,即 github.com/go-chi/chi/v4 这样的(有强迫症),但 chi 项目 tag 已经到 4.x.x 了,怎么办?

从上面截图看,它一直使用的 incompatible。没想过到 Go1.16 除了 retract 的功能,于是 chi 作者做了一个决定:在已经发布的版本中,只保留 v1.5.x 系列,其他的全部撤回。

$ go list -m -versions github.com/go-chi/chi
github.com/go-chi/chi v1.5.0 v1.5.1 v1.5.2 v1.5.3

没有了一大堆带 incompatible 的版本,世界瞬间清静了。

不过它的这个决定,有不少人反对,reddit 上也是激烈讨论。

作者表示:

对于给您带来的不便,我再次表示歉意,但是我为此项目投入了数年甚至数千小时的时间,对此我非常感兴趣,SIV 是我坚决反对的事情,因此我不会采纳它。尽管许多人不同意,但请记住go框架,这是 OSSgo框架,不是以任何方式赞助或付费的,您始终可以选择 fork 它并维护自己的版本。

作者很强硬。(谁知道 SIV 是什么意思?)

实际上使用 retract,之前的版本依然可以正常使用。我个人比较支持 chi 作者的做法。你呢?欢迎交流你的看法。

往期推荐

欢迎关注我