从 go-chi 框架撤回所有主版本聊 Go1.16 的新特性
共 7076字,需浏览 15分钟
·
2021-02-23 18:58
阅读本文大概需要 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(模块),但了解模块版本撤回还是有必要的,说不定哪天就能用到。因此建议你能够跟着本文操作一遍。
一般地,模块作者需要一种方法来指示不应该使用某个已发布的模块版本。可能出于以下几点原因:
发现了一个严重的安全漏洞; 发现了严重的不兼容性或 bug; 这个版本是偶然发布的,或是过早发布了;
作者不能简单地删除版本标签(tag),因为它们很可能在模块代理上仍然可用。如果作者能够从所有代理中删除一个版本,那么依赖该版本的下游用户就会无法使用,出问题。
此外,作者在发布了 go.sum
文件之后也不能更改版本,校验和数据库会验证发布的版本从未更改。
那怎么办?作者应该能够撤回模块版本。撤回的模块版本是模块作者明确声明不应该使用的版本。(retract 这个词是从学术文献中借来的:一篇被撤回的研究论文仍然可用,但是它有问题,不应该成为未来工作的基础)。
撤回的版本应该在模块代理和原始代码库中保持可用。依赖已撤回版本的构建应可以继续工作。当用户依赖于一个已撤回的版本(直接或间接)时,应该通知用户。它也应该很难无意中升级到一个已撤回版本。
为了让大家更好的理解模块撤回功能,本文通过具体的例子来演示。我们会创建两个模块:
foo,这是一个模块,本文将其 push 到 GitHub,完整路径:https://github.com/polaris1119/foo,你本地试验记得路径使用你的。本文将发布该模块的许多版本。 gopher,一个简单的 main 包,使用了上面的模块,该模块不会发布,只是作为本地模块;
注意,请确保 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。
$ 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
这一步确保 https://goproxy.cn 这个代理知晓了 v0.3.0 版本,这是一种手动让代理拉取你模块的方法。
$ go run .
这是v0.3.0版本
已经正常了。
经过这个步骤到底发生了什么?我们通过以下命令看一下:
$ 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 版本:
$ 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 模块。
为了让 https://goproxy.cn 知晓 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
的格式,当 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 上也是激烈讨论。
作者表示:https://github.com/go-chi/chi/issues/561
对于给您带来的不便,我再次表示歉意,但是我为此项目投入了数年甚至数千小时的时间,对此我非常感兴趣,SIV 是我坚决反对的事情,因此我不会采纳它。尽管许多人不同意,但请记住,这是 OSS,不是以任何方式赞助或付费的,您始终可以选择 fork 它并维护自己的版本。
作者很强硬。(谁知道 SIV 是什么意思?)
实际上使用 retract,之前的版本依然可以正常使用。我个人比较支持 chi 作者的做法。你呢?欢迎交流你的看法。
欢迎关注我