原创分享 如何查看历史版本的 Go 文档?嘘!答案我只告诉你!

bigwhite-github · 2020年12月21日 · 103 次阅读

img{512x368}

Go 语言自开源至今已经 11 个年头了!截至本文发稿时,目前最新的 Go 版本为 1.15,Go 核心开发团队正紧锣密鼓的进行着Go 1.16 版本的开发(现阶段主要是修复 bug),该版本将在 2021 年 2 月份正式发布。

Go 以 “自带电池 (battery included)” 而为人所知,除了 Go 标准库的全面和强大之外,Go 工具链的丰富和易用在主流编程语言中也是位列 “执牛耳者” 之列的,而 Go 文档查看工具就在 Go 工具链之列中。

查看文档是 Gopher 们日常必不可少的开发活动之一。Go 语言从诞生那天起就十分重视项目文档的建设,除了在 Go 官方网站 (https://golang.orgGo) 可以查看到最新稳定发布版(当前是 [ 1.15](https://mp.weixin.qq.com/s/B5onfyP7BPYCh_rMSBtfcQtip.golang.org** 上还可以查看到项目主线分支(master)上最新开发版本(非稳定版)的文档。))的文档之外,在 **

那么问题来了!如果想查看 Go 的某个历史版本(比如:Go 1.9)的文档,我应该如何做呢?别急!在这篇文章中,我将告诉你答案。

1. 利用 go doc,可行,但非最优

从 Go 发布 1.0 版本开始,Go 就将整个 Go 项目文档加入到 Go 发行版中,这样开发人员在本地安装 Go 的同时也拥有了一份完整的 Go 项目文档。

除了在发行版中集成所有文档,从1.5 版本开始,Go 还将文档查看工具集成到其工具链当中 (即go doc),使之成为 Go 工具链不可分割的一部分,这也再次体现了文档在 Go 语言中的重要性。自 go doc 在 1.5 版本加入 Go 工具链之后,它就和go getgo build一样成为了 Gopher 们每日必用的 go 命令,也成为了Go 包文档的 “百科全书”

不过利用 go doc,我们只能查看当前本地的 go 版本的文档。如果当前本地环境的 Go 版本为Go 1.14,那么所有 go doc 输出的文档内容均来自 Go 1.14 版本。如果我们要查看 Go 1.9 版本的文档,我们需要将本地环境的 Go 版本 “切换” 到 Go 1.9 才可以。

“切换” 的方法有很多,笔者习惯通过重新设置$GOROOT的方式在多个 Go 版本间切换:

$export GOROOT=~/.bin/go1.9.7            
$export PATH=$GOROOT/bin:$GOPATH
$go version
go version go1.9.7 darwin/amd64
$go doc http.Request

我们看到:“切换” 后再执行的 go doc 的输出结果均来自 Go 1.9 版本了。

不过这种方法比较繁琐,需要切换本地环境中的 go 版本,并且没法像官方站点那样通过图形化的方式查阅 go 文档,这显然不是最优方案,我们继续往下看。

2. 使用 godoc 建立历史版本的 Web 化文档中心

很多接触 Go 语言较早的 gopher 都知道,在 go doc 之前,还有一个像 gofmt 一样随着 Go 安装包一起发布的文档查看工具,它就是godoc,也就是说 godoc 在 Go 世界的存在历史比 go doc 还要悠久。在 Go 1.5 版本增加 go doc 工具后,godoc 与 go doc 就一直并存在 Go 中。这种情况一直持续到Go 1.13 版本。在 Go 1.13 版本中,godoc 就不再和 go、gofmt 一起内置在 Go 安装包中发布了。godoc 被挪到 Go 扩展工具链中,我们可以通过下面命令单独安装 godoc:

$go get golang.org/x/tools/cmd/godoc

和命令行 go doc 工具不同的是,godoc 实质上是一个 web 服务,它会在本地建立起一个 web 形式的 Go 文档中心,当我们执行下面命令时这个文档中心服务就启动了:

$godoc -http=localhost:6060

在浏览器地址栏输入http://localhost:6060,打开 Go 文档中心首页:

img{512x368}

我们看到 godoc 将\$GOROOT 下面的内容以 web 页面的形似呈现给开发者,同时我们看到首页顶部的菜单与 Go 官方主页的菜单也基本如出一辙。点击 “Packages” 可以打开 Go 包参考文档页面:

img{512x368}

Go 包参考文档页面将包分为几类:标准库包 (Standard library)、第三方包 (Third party) 和其它包 (Other packages),其中的第三方包就是本地\$GOPATH 下面的各个包。

不过,默认情况下 godoc 建立的 Go 文档中心对应的文档版本也是本地环境当前的 Go 版本,即如果当前本地安装的 Go 版本为 go 1.14,那么 godoc 所呈现的就是 go 1.14 稳定版对应的文档。 那么如果我想查看一下旧版本的文档,比如 Go 1.9.7 版本的文档,我该如何做呢?首先我们需要下载 go 1.9.7 版本的安装包(因为正如前面所说的,go 文档是随着安装包一起发布的),将其解压到本地目录下,比如是/Users/tonybai/.bin/go1.9.7,接下来我们执行如下命令:

$godoc -goroot /Users/tonybai/.bin/go1.9.7 -http=localhost:6060 

我们用-goroot命令行选项显式告诉 godoc 从哪个路径加载 Go 文档数据,这样 godoc 建立的文档中心中的文档版本就是 Go 1.9.7 的了。

我们看到,通过 godoc,我们不仅无需切换本地环境中的 go 版本,我们还建立起了像 golang.org 那样的图形化的历史 go 版本的文档中心。这也是截至目前为止查看 Go 历史版本版本文档的最佳方法了!

更多关于常用 Go 工具链的高级用法的内容请参看我在慕课网上出品的 Go 进阶技术专栏《改善 Go 语言编程质量的 50 个有效实践》。本专栏主要满足广大 gopher 关于 Go 语言进阶的需求,围绕如何写出地道且高质量 Go 代码给出 50 条有效实践建议,上线后收到一致好评!欢迎大家订阅!

img{512x368}


“Gopher 部落” 知识星球开球了!高品质首发 Go 技术文章,“三天” 首发阅读权,每年两期 Go 语言发展现状分析,每天提前 1 小时阅读到新鲜的 Gopher 日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于 Go 语言生态的所有需求!星球首开,福利自然是少不了的!2020 年年底之前,8.8 折 (很吉利吧^_^) 加入星球,下方图片扫起来吧!

我的网课 “Kubernetes 实战:高可用集群搭建、配置、运维与应用” 在慕课网热卖中,欢迎小伙伴们订阅学习!

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

我的联系方式:

更多原创文章干货分享,请关注公众号
  • 加微信实战群请加微信(注明:实战群):gocnio
暂无回复。
需要 登录 后方可回复, 如果你还没有账号请点击这里 注册