首页 > Golang > Go教程

Go go doc 怎样用 -ex 查看可执行示例源码

来源：17golang原创

时间：2026-10-24 10:23:15 116浏览收藏

想快速查看 Go 包或符号旁边的可执行示例，可以在原来的 go doc 命令前加上 -ex，例如 go doc -ex fmt。它会把符合 Go 示例约定的示例源码一起纳入文档输出，方便从 API 说明直接跳到用法；但它只负责展示文档，不会替你执行示例。

官方文档：https://pkg.go.dev/cmd/go

-ex 解决的是“我想在文档里看到可执行示例源码”，不是“我想得到一次运行结果”。阅读时先用 go doc -ex 包名 或 go doc -ex 包名.符号 定位示例，需要确认输出时再交给 go test。

先分清 go doc 默认查找什么

go doc 的基本作用是打印包、常量、函数、类型、方法或结构体字段的文档注释。无参数时，它查看当前目录的包；给出包名时，它展示这个包的文档；给出符号时，它按 Go 语法形式匹配目标。常见写法如下：

# 查看当前目录的包文档
go doc

# 查看标准库 fmt 包的文档
go doc fmt

# 查看 fmt.Println 的说明和方法摘要
go doc fmt.Println

这里的关键是先把“查询对象”写对。go doc 的参数不是任意文件名，也不是支持 ... 的包模式；如果只想看某个符号，优先写成 包名.符号名，减少同名符号带来的歧义。

go doc 的当前包、包路径、符号和包加符号四种查询对象边界静态说明图 — 图1：结构说明图，展示 go doc 查询对象与文档输出边界；这不是终端截图，也不表示命令已在本机运行。

用 -ex 把可执行示例带进文档

在同一个查询目标前加 -ex，就能要求 go doc 同时纳入可执行示例。按包查看时，适合先浏览一个标准库包有哪些示例；按符号查看时，适合把注意力收缩到某个函数、类型或方法。

# 查看 fmt 包文档，并包含包级可执行示例
go doc -ex fmt

# 查看 strings.Builder 相关文档，并尝试包含对应示例
go doc -ex strings.Builder

# 查看某个方法的文档与示例
go doc -ex fmt.Println

“可执行”描述的是示例的组织方式，不等于命令输出中已经给出了运行结果。Go 的示例通常写在测试文件中，函数名遵循 Example、Example类型 或 Example类型_方法 等约定；是否能够被测试框架执行，还取决于示例代码本身和可选的 Output: 注释。

go doc -ex 将包或符号连接到 Example 示例源码而不直接产生运行结果的静态关系图 — 图2：结构说明图，展示 -ex、文档目标、Example 示例源码和 go test 执行职责之间的关系。

为什么 -ex、-src 和 -cmd 不能互相替代

这三个选项都像是在“查看更多内容”，但解决的问题不同：

-ex：把可执行示例纳入文档展示，重点是读用法。
-src：展示目标声明或定义的完整 Go 源码，重点是读实现细节，内容可能包含未导出部分。
-cmd：把 package main 命令包按普通包处理，重点是查看命令包的导出符号。

如果问题是“这个 API 怎么用”，先从 -ex 开始；如果问题是“这个函数内部怎么实现”，才考虑 -src；如果目标是命令包而默认输出隐藏了顶层导出符号，再加 -cmd。不要把多个开关叠加成固定模板，按阅读目的选择更容易得到短而准确的输出。

# 只查看示例用法
go doc -ex net/http

# 需要阅读某个声明或定义的完整源码时使用 -src
go doc -src strings.Builder

# 命令包需要显示导出符号时使用 -cmd
go doc -cmd cmd/go

展示源码和执行示例是两件事

如果希望检查示例能否编译、运行并匹配输出，应该回到示例所在包执行测试，而不是把 go doc -ex 当成运行器。示例函数通常放在以 _test.go 结尾的文件中，带有正确 Output: 的示例才会由测试框架比较输出。

package stringsdemo

import (
	"fmt"
	"strings"
)

// ExampleBuilder 展示可被文档系统识别的最小示例形态。
func ExampleBuilder() {
	var builder strings.Builder
	builder.WriteString("Go")
	// Output 注释是测试框架判断示例输出的依据，不是 go doc 的执行结果。
	fmt.Println(builder.String())
	// Output: Go
}

在这个示例里，go doc -ex stringsdemo 负责帮助读者找到示例源码；go test 才负责编译示例并根据 Output: 检查输出。两者配合使用，既能快速读懂用法，也能在改动后获得可重复的反馈。