Go 1.27 的 go doc -ex 如何改变示例检索体验

查 Go API 时，最容易卡住的不是找不到包，而是找到函数签名后仍然不知道“这个 API 应该怎么用”。Go 1.27 给 go doc 增加了 -ex 选项，可以按包或符号列出关联的可执行示例，把文档检索从“看声明”推进到“找用法”。

官方地址：https://go.dev/doc/go1.27

为什么 go doc -ex 适合做示例入口

普通的 go doc 擅长告诉我们一个包有哪些类型、函数和方法，但它给出的重点是 API 形状。真正准备接入代码时，我们还要继续猜示例函数的名字，或者翻到包的 _test.go 文件里搜索。

Go 1.27 的变化是把这一步接到文档命令上：对包使用 -ex 时，可以看到包中的可执行示例；对包和符号一起使用时，可以把范围收窄到某个 API。这里的“可执行”指符合 Go 示例测试约定、能够被测试工具识别的 Example，并不表示命令会替你运行示例。

这对维护者和使用者都很实用：维护者可以用一个可测试的 Example 同时承担文档和回归检查，使用者则可以从 API 名称直接找到更接近真实调用的代码。

先用小包建立可被检索的示例

为了看清检索边界，先准备一个很小的模块。下面的命令只创建实验目录和模块，不依赖第三方包。

# 创建一个独立实验目录，避免修改已有项目
mkdir go-doc-ex-demo
cd go-doc-ex-demo

# 初始化模块，后续可以用模块路径查询包
go mod init example.com/go-doc-ex-demo

# 创建包目录和测试示例文件
mkdir docdemo
touch docdemo/normalize.go docdemo/normalize_test.go

在 docdemo/normalize.go 中放一个有明确用途的导出函数，在 docdemo/normalize_test.go 中用 ExampleNormalize 命名示例。示例里的注释解释关键动作，输出注释则描述预期结果。

package docdemo

import "strings"

// Normalize 把连续空白收敛成一个空格，便于展示文本清洗场景。
func Normalize(s string) string {
	return strings.Join(strings.Fields(s), " ")
}

package docdemo_test

import (
	"fmt"

	"example.com/go-doc-ex-demo/docdemo"
)

// ExampleNormalize 展示 Normalize 的输入与可观察结果。
func ExampleNormalize() {
	// 使用带有多余空白的输入，突出函数的清洗职责。
	input := "  go   doc   -ex  "
	fmt.Println(docdemo.Normalize(input))
	// Output: go doc -ex
}

这里的 ExampleNormalize 同时满足两个目的：名称中的 Normalize 把示例关联到导出函数，Output: 让 go test 能够按示例测试约定检查输出。若只写成普通的 TestNormalize，它仍可能是测试，但不会成为这个文档示例入口。

用 go doc -ex 按包或符号找示例

包文件准备好后，先从包级查询开始。命令的结果重点是“有哪些 Example”，适合刚接触一个新包时建立索引。

# 列出当前模块中 docdemo 包可发现的可执行示例
go doc -ex example.com/go-doc-ex-demo/docdemo

# 只关注 Normalize 这个导出符号关联的示例
go doc -ex example.com/go-doc-ex-demo/docdemo.Normalize

如果包里有 ExampleNormalize、ExampleNormalize_trimmed 等示例，符号级查询的价值在于缩小阅读范围。它适合“我已经知道要用哪个 API，但不记得示例叫什么”的场景。

对标准库包也可以使用同样的思路，例如下面的命令把查询目标放在 bytes.Buffer：

# 查询标准库 bytes.Buffer 相关的可执行示例
go doc -ex bytes.Buffer

命令显示的是文档信息和示例索引，不是运行结果。想验证示例能否编译、输出是否匹配，仍然回到项目目录执行 go test。

三种查询方式怎么分工

实际使用时可以把命令分成三档。不要把 -ex 当成普通文档的替代开关，它解决的是“从声明继续找到示例”这一段路径。

Go 1.27 还支持把版本写进包查询，例如 go doc example.com/pkg@v1.2.3。当项目需要对照不同模块版本的文档时，这个能力和 -ex 结合起来，可以先定位版本，再找该版本暴露的示例；但版本是否可解析、模块是否能下载，仍取决于本机的模块环境。

指定示例名时，为什么能看到更多源码

当列表已经把候选示例列出来，下一步可以直接查询示例名。Go 1.27 的发布说明特别提到，传入示例名时，go doc 会连同示例源码和注释一起打印。

# 查看标准库中一个具体示例的源码与注释
go doc bytes.ExampleBuffer

# 查看本地实验包中的具体示例
go doc example.com/go-doc-ex-demo/docdemo.ExampleNormalize

这一步很适合阅读“为什么这样调用”。普通 API 文档负责说明函数契约，Example 源码负责补充输入准备、错误处理和输出预期。若示例包含完整文件上下文，输出也可能比一段孤立代码更长，这不是 -ex 失效，而是示例本身承担了更多上下文。

迁移旧有文档查找习惯时记住三个边界

1. -ex 不等于执行。它负责查找和展示符合 Example 约定的文档代码；要执行并检查输出，用 go test。
2. 命名决定关联关系。优先使用 Example、ExampleType、ExampleType_Method 这类约定命名，示例才能自然地挂到包、类型或方法上。
3. 包级和符号级要分开用。第一次了解包时用包级查询，已经确定 API 后改用符号级查询，结果更短也更容易筛选。

# 先检查示例是否能通过测试；-run 只筛选 Example 函数
go test ./docdemo -run '^ExampleNormalize$'

# 再回到文档侧查看同一示例的完整源码
go doc example.com/go-doc-ex-demo/docdemo.ExampleNormalize

这套顺序把“发现”和“验证”分开：go doc -ex 负责降低搜索成本，go test 负责给出编译和输出检查结果。对团队文档来说，示例既然可被测试，就应该把它当作代码的一部分维护，而不是只在文章里复制一份可能过期的片段。

常见问题

go doc -ex 为什么没有列出我的函数示例？

先检查文件是否位于包的测试文件中，函数是否使用 Example 命名规则，以及后缀是否符合小写约定。还要确认查询的包路径和符号名称没有写错。

go doc -ex 会自动运行示例吗？

不会。它负责查找和展示可执行示例；示例是否能编译、输出是否匹配，需要使用 go test 检查。

普通 go doc 和 go doc -ex 应该先用哪个？

不熟悉包时先用普通 go doc 看 API 结构，再用 -ex 找调用样例；已经明确符号时可以直接使用符号级的 -ex 查询。

Go 1.27 的这项改动不大，却把“读 API”与“找用法”接得更近。把 Example 函数按约定写好，再用 go doc -ex 做发现、用 go test 做验证，文档和代码就能形成一条更短的学习路径。