罕见的 Go CLI 命令 (5/5)：查看文档与依赖

不敢说文档是代码的灵魂，但也至少可以算是发肤。本文主要看一下如何使用 Go 提供的 CLI 命令查看项目文档以及检查依赖关系。

1. 查看文档

一般我们习惯打开 pkg.go.dev 查看文档，但其实 Go 也提供了 go doc 命令在终端查看文档。可以使用以下格式：

go doc <pkg>
go doc <sym>[.<methodOrField>]
go doc [<pkg>.]<sym>[.<methodOrField>]
go doc [<pkg>.][<sym>.]<methodOrField>

以上来自 go help doc 命令的说明。

go doc 不仅支持查找标准库文档，也支持自定义包。可以通过 . 连接包名、结构体或接口以访问其字段或方法，以 gin 为例：

# 准备
git clone git@github.com:gin-gonic/gin.git && cd gin

# 查看当前项目文档
go doc
# 输出的第一行为：package gin // import "github.com/gin-gonic/gin"
# 来自 Gin 目录内的 doc.go 文件，对于大型项目，这是一个约定

如果第三方包中包含的 func 或 type 和标准库中的没有冲突，那么可以直接使用 go doc <func/type/struct> 命令：

go doc Param # 查看 Gin 的 Param type

单如果和标准库有冲突，需要添加路径，一般来说为避免歧义，在第三方包使用 go doc 命令时建议总是包含路径：

go doc Context # 来自标准库的 Context
go doc . Context # 来自 Gin 的 Context

# 支持点号访问子集
go doc . Context.Param

Go 官方对文档有一个比较详细的介绍 Go Doc Comments，另外提供了 pkg.go.dev/go/doc 包供相关使用。

2. 查看依赖

go list 是 Go CLI 工具集中的一个命令，可以获取有关包的各种信息，如导入路径、目录位置、依赖关系等。基本用法如下：

go list [flags] [packages]

其中，[flags] 是一些选项，[packages] 是要列出信息的包的导入路径。通过不同的选项，可以获取不同格式的输出信息，如 JSON 格式、指定字段等。

常见用法包括：

# 同样以 Gin 为例
git clone git@github.com:gin-gonic/gin.git && cd gin

# 展示当前 package path，多用于工具或自动化脚本的命令
go list

# 查看包的所有依赖
go list -deps

# 查看所有依赖的包名，使用 Go 的模版语法
go list -deps -f {{.Name}}

go list 命令默认是 package 模式，可以切换到 module 模式：

go list -m

# 查看主 module 及其所有依赖的导入路径
go list -m all

# 查看依赖的版本
go list -m -versions github.com/golang/protobuf

通过 go help list 命令可以查看更多关于 go list 的详细信息和用法说明。go list 在 Go 开发中还是比较有用的，可以帮助我们更好地管理和了解项目中的包信息。

有时候我们为了一个并不太复杂的功能而想要轻易引入一个包的时候，可以看一下这个包又依赖了多少别的包，有没有风险，值不值得这样做。

总结

之前在使用 Go 的过程中，常用的也就是 build，run，test 以及 get 等基本命令，本系列文章通过对 Go 提供的 CLI 命令从构建、插件、运行时、项目管理、文档五个方面进行了全面的总结，虽然稍微流于表面，并未深入，但重在入门。

每一门语言都有其独到之处，也有无尽的精彩等待探索。