example函数必须以example开头且无参数：命名须为func examplexxx()，放于_test.go中同包，用fmt.println打印输出，运行用go test -run ^example，文档通过go doc或pkg.go.dev查看。
Example函数必须以Example开头且无参数
Go 的 Example 函数不是普通测试，它被 go test 和 godoc 特殊识别，命名和签名错一个字母就完全失效。常见错误是写成 ExampleXxx_test 或带参数如 func ExampleFoo(t *testing.T) —— 这会被当成普通函数忽略，既不运行也不出现在文档里。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
Example函数名必须严格以大写Example开头，后接可选的、首字母大写的标识符（如ExamplePrint、ExampleSliceFilter），不能有下划线 - 函数签名必须是
func ExampleXXX()，零参数、零返回值 - 必须放在
_test.go文件中，且与待示例的代码在同一个包（不能是xxx_test包） - 如果想为某个函数生成示例，推荐命名成
ExampleFuncName，比如为TrimSpace写ExampleTrimSpace
输出必须通过fmt.Println或fmt.Printf显式打印
godoc 生成文档时，只抓取函数体内调用 fmt.Println 或 fmt.Printf 的输出结果，作为示例的「期望输出」。任何其他方式（比如 log.Print、变量赋值、注释里的伪代码）都不会被识别。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 最后一行必须是
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语言免费学习笔记（深入）”；
- 用正则精准匹配：执行
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语言免费学习笔记（深入）”；
- 本地预览：运行
go doc <package>.<name></name></package>，例如go doc strings.TrimSpace，确认 Example 块是否出现 - 在线发布前，先去
pkg.go.dev搜索你的模块，看 Example 是否渲染正常（有时缓存延迟，需等几分钟） - 如果 Example 没显示，优先检查：函数名是否拼错、是否在
_test.go中、是否用了fmt打印、// Output:注释是否与实际输出一字不差（包括末尾换行） - 别忘了导出：被示例的标识符（如函数、类型）本身必须首字母大写，否则
go doc不会把它和 Example 关联起来
