从 go-chi 框架撤回所有主版本聊 Go1.16 的新特性
大家好，我是站长 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>.<minor>.<patch> 的格式，当 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 作者的做法。你呢？欢迎交流你的看法。
