Go go doc -ex 怎样直接打印示例实现

想读一个 Go 包的用法时，单看 API 签名往往还不够。go doc 默认给出包、函数或类型的文档；在命令后增加 -ex，就会把与目标关联的可执行示例一起打印出来。关键命令是：

# 查看 strings 包的文档，并把关联的可执行示例一并输出
go doc -ex strings

这里的“打印示例实现”不是把整个包的源代码导出，而是按 Go 的 Example 命名约定找到示例函数，并把它作为文档内容展示。下面按“目标是否找对、示例是否绑定、输出是否可执行”三层说明。

直接结论：先用普通 go doc 确认包或符号目标，再加 -ex 获取示例；如果没有看到示例，优先检查示例函数是否位于 _test.go、名称是否符合 Example... 约定，以及目标是否指向了正确的包或符号。

先区分普通文档与可执行示例

可以把输出范围看成一个可复现的对照：基线命令只请求“目标的文档注释和符号摘要”，增加 -ex 后，目标不变，但输出范围多了“与目标绑定的可执行示例”。因此 -ex 不是包选择器，也不是源码导出开关。

先用不带 -ex 的命令确定目标，能减少“其实查到了另一个包”这种误判。go doc 支持包路径、符号名以及包和符号分开的两参数形式；目标定位成功后，-ex 只负责把示例纳入展示。

用 Example 命名把示例绑定到符号

可执行示例通常放在 _test.go 文件中，函数名以 Example 开头。名称中的后半段决定它和哪个文档对象关联：

package demo_test

import "fmt"

// Example 展示整个包的用法，包级示例不绑定到具体函数。
func Example() {
	fmt.Println("package demo")
	// Output: package demo
}

// ExampleFormat 绑定名为 Format 的函数或类型。
func ExampleFormat() {
	fmt.Println("formatted")
	// Output: formatted
}

// ExamplePrinter_Print 绑定 Printer 类型的 Print 方法。
func ExamplePrinter_Print() {
	fmt.Println("printed")
	// Output: printed
}

常见映射可以压缩成三类：Example() 对应包整体，ExampleFoo() 对应 Foo，ExampleFoo_Bar() 对应类型 Foo 的 Bar 方法。需要同一对象展示多个版本时，可以使用小写后缀，例如 ExampleFormat_json()。

用 go doc -ex 直接输出示例实现

目标确定后，按需要选择一参数或两参数命令。以下命令表达的是同一个阅读动作：先指定包，再让 -ex 扩展输出范围。

# 查看整个包的文档和包级、符号级示例
go doc -ex strings

# 只围绕一个符号查找文档和关联示例
go doc -ex strings.TrimSpace

# 用完整包路径和符号名避免短名称匹配到错误包
go doc -ex text/template Execute

如果你只是想看某个符号的完整声明或函数体，应使用 -src；如果想查看包内所有文档，应考虑 -all。这些选项解决的是不同问题，不要把“示例实现”“源码实现”和“全部文档”混为一谈。

按输出注释判断示例边界

“可执行示例”有一个重要边界：示例函数可以被测试框架编译和执行，但只有写了 Output: 注释时，测试才有可比较的标准输出。没有输出注释的示例仍可用于展示需要外部环境的代码，但不能把它当作已验证输出。

package demo_test

import "fmt"

// ExampleFetch 展示 API 调用结构；没有 Output，适合只要求编译的示例。
func ExampleFetch() {
	// 这里用固定文本代替网络请求，避免把外部服务当成示例前提。
	fmt.Println("request shape")
}

阅读 go doc -ex 输出时，可以用三个数字化检查点判断覆盖范围：目标是否是预期包或符号、是否出现对应的 Example 代码块、示例是否带有 Output 注释。三项分别对应“查找正确、绑定正确、可比较程度”，比只看命令是否返回文本更可靠。

常见问题

为什么加了 -ex 还是看不到示例？

先确认目标包中确实存在以 Example 开头的示例函数，再检查它是否放在 _test.go 文件中，以及函数名的大小写和下划线是否能对应目标符号。也要注意你查的是包还是具体方法。

go doc -ex 会打印整个测试文件吗？

不会。它展示的是与包或符号关联的示例内容，不等价于读取整个测试文件；需要看声明或函数源码时，应使用适合源码查看的 -src 选项。

没有 Output 注释的示例还能用吗？

可以用于展示需要人工观察或外部条件的代码，并可参与编译；但它没有可供测试框架比较的标准输出，不能据此宣称运行结果已自动校验。

总结

go doc -ex 的作用很单一也很实用：保留原来的包或符号定位，再把符合命名约定的可执行示例带到文档输出里。实际使用时记住三点：先确认目标，再检查 Example 绑定，最后根据 Output: 判断示例的可校验边界。

官方资料：https://go.dev/src/cmd/go/internal/doc/doc.go　https://go.dev/blog/examples