Go doc 怎样在模块缓存中定位未导出的示例

要在模块缓存里查到某个版本的未导出示例，关键是先固定版本，再让 `go doc` 进入这个版本的实际包目录。最小组合是：`go mod download -json module@version` 取得缓存目录，进入目标包子目录后使用 `go doc -u -ex -all`。其中 `-u` 负责放开未导出符号，`-ex` 负责显示可执行示例，`-all` 负责展开包内完整文档。

官方地址：https://go.dev/

下面的命令是可复制的操作示例，路径中的模块名、版本和包子目录需要替换成自己的目标；本文不把示例输出当作本机运行结果。

先分清模块、包和符号三个对象

go doc 展示的是包或符号的文档，不是“扫描整个缓存目录”。模块缓存保存的是某个模块版本的源码树，真正交给 go doc 的仍然是模块中的包目录或包路径。

用 go mod download 固定模块版本

不要直接手拼 $GOPATH/pkg/mod 下的目录名。官方规则允许通过 GOMODCACHE 改变缓存位置，而且模块路径中的大写字母可能会被转义。让 Go 工具返回 Dir，比猜路径可靠。

# 取得指定版本的模块缓存元数据，JSON 中的 Dir 是源码根目录
go mod download -json example.com/telemetry@v1.4.0

# 只查看当前工具链实际使用的模块缓存根目录
go env GOMODCACHE

把返回对象里的 Dir 记下来。例如模块路径是 example.com/telemetry，目标包是 trace，就把 Dir 与 /trace 拼成包目录；如果目标包在模块根目录，则直接使用 Dir。不要把 cache/download 下的 .zip、.mod 文件当作可供 go doc 阅读的包目录。

# 进入指定版本的目标包目录；这里的路径来自上一条命令的 Dir
cd /由-go-mod-download-json-返回的模块根目录/trace

# 在这个确定版本的包目录中查看包文档与完整符号说明
go doc -u -ex -all .

模块缓存中的源码通常由 Go 工具以只读方式保存。查看文档只需要读取它，不要为了编辑缓存源码而解除只读属性；如果要改代码，应复制到自己的工作区。

组合 -u、-ex 和 -all 找到未导出的示例

三个选项解决的是不同问题，不能把它们当成一个“隐藏开关”。-u 让未导出的名称、方法和字段也进入文档范围；-ex 把可执行示例纳入输出；-all 则要求显示包的全部文档，而不是只给出概览和第一层条目。

# 在已固定版本的包目录中，展开未导出文档和可执行示例
go doc -u -ex -all .

# 已知符号名称时缩小范围；-u 仍让未导出符号可被匹配
go doc -u -ex internalDecoder

# 只查看示例相关输出时保留 -ex，避免把完整源码误当成文档
go doc -u -ex -short .

如果示例函数写在测试文件中，-ex 是判断它是否进入文档输出的关键；如果示例关联的是未导出类型或未导出方法，则还需要 -u。因此“看不到示例”至少要分成两种情况：示例没有被纳入输出，或示例所属的未导出对象被默认隐藏。

-src 是另一条路线，它会输出符号的完整源码，可能包含未导出实现细节。它适合需要回到定义处阅读时使用，不应拿来替代 -ex 查找示例。

版本和包目录错了时怎样排查

最常见的误区是“模块下载成功，就等于查到了目标包”。实际上，模块根目录可能包含多个包；另一个误区是直接在主模块中运行包路径，结果查到的是当前构建列表中的版本，而不是刚刚下载的指定版本。

# 显示指定模块版本的缓存信息，先确认版本和源码目录
go mod download -json example.com/telemetry@v1.4.0

# 在目标包目录读取包名和文档，避免把模块根目录当作 package
go doc -u -ex -short ./trace

# 需要更细时再锁定具体符号；大小写和包内名称要与源码一致
go doc -u -ex ./trace Decoder.parse

还要记住两个边界：第一，go doc 的包路径形式不是通用的 go 包模式，不能把 ... 当成递归搜索语法；第二，默认输出偏向导出 API，未导出内容需要明确加 -u。当输出为空或找不到对象时，先回到 Dir 和包子目录，再检查符号名，不要立刻判断缓存损坏。

常见问题

只加 -u 就能看到所有示例吗？不能。-u 解决的是未导出对象的可见性，示例是否纳入输出还要看 -ex。

为什么不建议手写模块缓存路径？缓存根目录可能由 GOMODCACHE 改变，模块路径中的大小写也可能被转义；用 go mod download -json 返回的 Dir 更准确。

go doc -all 会递归扫描整个模块吗？不会。它针对当前指定的包展开完整文档，想查另一个包仍需进入那个包目录或传入对应包路径。

模块缓存里的源码能直接修改吗？不建议。缓存用于复用下载的版本，源码通常是只读的；要修改或调试，应复制到工作区并使用自己的模块替换规则。

实际操作可以按一句话记忆：先用 go mod download -json module@version 锁定版本和 Dir，再进入包目录，最后用 go doc -u -ex -all 区分未导出对象、可执行示例和完整文档范围。