如何在Golang中编写示例函数作为文档 Go语言Example测试代码规范

go example函数必须以example开头、无参数无返回值、定义在_test.go中，末尾需有顶格// output:注释并精确匹配fmt.println输出。

Go Example函数必须以 Example 开头且无参数无返回值

Go 的 Example 函数不是普通测试，而是文档示例——它会被 go doc 和 godoc（或 pkg.go.dev）直接渲染成可读代码块，同时被 go test 自动执行验证输出。不满足命名和签名规则，就不会出现在文档里，也不会被运行。

常见错误现象：go test 不报错但没输出；go doc 查不到示例；pkg.go.dev 页面空白。

• 函数名必须是 Example + 驼峰标识符（如 ExampleMapMerge、ExamplehttpHandler），不能带下划线
• 必须定义在 _test.go 文件中（和 *_test.go 同包）
• 签名严格为 func ExampleXXX()：无参数、无返回值
• 若想演示某个函数，推荐用 ExampleFuncName；若演示类型用法，用 ExampleTypeName_MethodName（如 ExampleSlice_Append）

Example函数末尾必须加 // Output: 注释并匹配真实输出

// Output: 不是注释，是 Go 测试框架的硬性标记——它告诉 go test 从这一行开始，下面的内容是**期望的标准输出**，运行时会捕获 fmt.Println 等实际输出，并逐行比对（含空格、换行）。不写、写错位置、或输出不一致，测试就失败。

使用场景：展示 API 典型调用链、结构体初始化后打印、错误处理分支输出等。

立即学习“go语言免费学习笔记（深入）”；

• // Output: 必须顶格写，前面不能有空格或其他字符
• 其后每一行输出必须完全一致（包括末尾换行），fmt.Print 少个 n 就失败
• 避免在示例中用 log.Println 或自定义 writer，只用 fmt.Println/fmt.printf
• 如果不想输出（比如只做 setup），写 // Output: 后空一行即可

func ExampleParseDuration() {     d, _ := time.ParseDuration("2h30m")     fmt.Println(d)     // Output:     // 2h30m0s }

Example函数默认不访问外部依赖，但可手动启用 -test.v 查看实际输出

Go 的 Example 测试默认静默运行，失败才报错。你改了代码但示例输出没更新？或者不确定 // Output: 写得对不对？这时候需要主动“看一眼”真实输出。

性能 / 兼容性影响：无额外开销，-test.v 只影响本地调试，不影响 CI 或文档生成。

• 运行 go test -v -run ^Example.*$（正则匹配所有 Example）
• 输出中会显示 “got” 和 “want”，帮你快速定位哪一行不一致
• 注意：如果示例里用了 os.Exit、panic、或并发未同步（如 goroutine 未 wait），会导致输出不可控甚至挂起
• 不要在 Example 中读写文件、发起 HTTP 请求——它们不属于文档契约，也难保证环境一致性

跨包 Example 要用 ExamplePackageFunc 并确保导出符号可见

想给 json.Marshal 写示例？不能直接写 ExampleMarshal 在自己的 main 包里——go test 只扫描当前包的 _test.go，且只会绑定到同包导出符号。

正确做法：把 Example 放在目标包的源码目录下（即你维护该包时），或用 Example + 包名前缀来模拟（仅限文档意图，不触发测试）。

• 真正生效的跨包示例，必须放在被文档化包的 xxx_test.go 中（例如 encoding/json/json_test.go）
• 如果你只是使用者，想写说明性片段，可用 ExampleMyApp_UsesJSON，但它不会绑定到 json 包，也不参与其测试
• 确保被调用的函数/类型是导出的（首字母大写），否则编译失败：cannot refer to unexported name xxx.yyy

文档示例不是玩具代码，它既是测试用例，也是用户第一眼看到的接口说明书。最容易被忽略的是 // Output: 的换行敏感性和 Example 函数的包归属——写错位置，就等于没写。