Go语言Example函数详解与使用方法

Go语言的Example函数是一种专为生成可执行文档而设计的特殊机制，它要求严格遵循命名规范（func ExampleXXX()）、零参数签名、置于同包的_test.go文件中，并通过fmt.Println显式输出示例结果；其核心价值在于既能被go test -run ^Example验证正确性，又能自动集成到go doc和pkg.go.dev的官方文档中，成为兼具测试性与说明性的活文档——但任何细微偏差（如大小写错误、多余参数、非fmt输出或错误包路径）都会导致其彻底失效，因此精准实践是解锁Go生态优质文档体验的关键。

Example函数必须以Example开头且无参数

Go 的 Example 函数不是普通测试，它被 go test 和 godoc 特殊识别，命名和签名错一个字母就完全失效。常见错误是写成 ExampleXxx_test 或带参数如 func ExampleFoo(t *testing.T) —— 这会被当成普通函数忽略，既不运行也不出现在文档里。

实操建议：

• Example 函数名必须严格以大写 Example 开头，后接可选的、首字母大写的标识符（如 ExamplePrint、ExampleSliceFilter），不能有下划线
• 函数签名必须是 func ExampleXXX()，零参数、零返回值
• 必须放在 _test.go 文件中，且与待示例的代码在同一个包（不能是 xxx_test 包）
• 如果想为某个函数生成示例，推荐命名成 ExampleFuncName，比如为 TrimSpace 写 ExampleTrimSpace

输出必须通过fmt.Println或fmt.Printf显式打印

godoc 生成文档时，只抓取函数体内调用 fmt.Println 或 fmt.Printf 的输出结果，作为示例的「期望输出」。任何其他方式（比如 log.Print、变量赋值、注释里的伪代码）都不会被识别。

实操建议：

• 最后一行必须是 fmt.Println（或 fmt.Printf），且内容要能清晰体现输入→输出逻辑
• 避免多余空行或调试输出，否则文档里会照搬显示，影响可读性
• 如果示例涉及多行输出，用多次 fmt.Println；不要用 \n 拼接——godoc 会把换行转成空格
• 示例：

  func ExampleTrimSpace() {
  	s := "  hello  "
  	fmt.Println(strings.TrimSpace(s))
  	// Output: hello
  }

  注意注释 // Output: 是可选的，但加上能防止输出意外变更导致测试失败

运行和验证：用go test -run ^Example而不是go test

go test 默认不运行 Example 函数，它们不属于 Test 函数族。不加筛选直接跑，你会看到「no tests to run」，误以为写错了。

实操建议：

• 用正则精准匹配：执行 go test -run ^Example（^ 确保只匹配开头为 Example 的函数）
• 加 -v 查看详细输出：go test -v -run ^Example，能看到每个 Example 是否通过、实际输出 vs 期望输出是否一致
• 如果写了 // Output: 注释但实际输出不符，会报类似 example_test.go:12: unexpected output 的错误，此时要检查打印内容是否含空格、换行或类型隐式转换（比如 fmt.Println([]int{1}) 输出是 [1]，不是 1）
• 注意：Windows 下 PowerShell 可能需改用 go test -run "Example$" 避免 ^ 被解释为转义

生成文档时godoc已弃用，改用go doc或pkg.go.dev

本地 godoc 命令自 Go 1.13 起不再随安装包提供，强行用旧版或第三方 godoc 工具容易不显示 Example 块。现在标准路径是 go doc CLI 或在线 pkg.go.dev —— 它们原生支持 Example，但依赖函数签名和输出格式完全合规。

实操建议：

• 本地预览：运行 go doc .，例如 go doc strings.TrimSpace，确认 Example 块是否出现
• 在线发布前，先去 pkg.go.dev 搜索你的模块，看 Example 是否渲染正常（有时缓存延迟，需等几分钟）
• 如果 Example 没显示，优先检查：函数名是否拼错、是否在 _test.go 中、是否用了 fmt 打印、// Output: 注释是否与实际输出一字不差（包括末尾换行）
• 别忘了导出：被示例的标识符（如函数、类型）本身必须首字母大写，否则 go doc 不会把它和 Example 关联起来

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Go语言Example函数详解与使用方法》文章吧，也可关注golang学习网公众号了解相关技术文章。