Golang如何用Example函数写文档示例

Go语言中的Example函数是一种独特而强大的文档编写方式，它通过可执行的代码示例直接嵌入API文档，既供`godoc`渲染展示，又由`go test`自动验证输出正确性；但其规则极为严格：必须以大写`Example`开头、无参数无返回值、定义在同包的`_test.go`文件中，末尾用顶格`// Output:`精确断言`fmt.Println`的每一处输出（包括空格与换行），且所有依赖需显式初始化——稍有偏差（如多一个空格、错用`*testing.T`、包名不一致或map打印顺序未控制）就会导致文档验证失败；掌握这些细节，你就能写出真正可靠、自验证、即文档即测试的高质量Go示例。

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

Go 的 Example 函数不是普通测试，而是被 go test -v 或 godoc 识别的特殊函数。它不跑在 Test 流程里，也不需要 *testing.T 参数——加了反而报错：example function ExampleXxx should have no arguments and no return values。

常见错误是照着 Test 写法抄：带 t *testing.T、带 error 返回、或者函数名拼错（比如 exampleFoo 小写开头、Example_Foo 带下划线）。

• Example 函数名必须严格匹配：首字母大写的 Example + 要文档化的对象名（如 ExampleMapMerge 对应 MapMerge 函数）
• 函数体里调用目标代码后，必须用 fmt.Println 输出可预期结果（否则 go test 不知道该比对什么）
• 如果示例涉及多行输出，fmt.Println 每行都要写清楚，空行也要显式 fmt.Println()

func ExampleMapMerge() {
	m1 := map[string]int{"a": 1}
	m2 := map[string]int{"b": 2}
	merged := MapMerge(m1, m2)
	fmt.Println(merged)
	// Output: map[a:1 b:2]
}

Output 注释必须和实际输出完全一致（含空格与换行）

Example 函数末尾的 // Output: 注释不是说明，是断言。运行时 go test 会捕获 fmt.Println 所有输出，并逐字符比对注释后的内容。哪怕多一个空格、少一个换行，都会失败：

FAIL: ExampleMapMerge (0.00s) example_test.go:12: mismatch in output

• 输出含 map、slice 等无序结构时，注意 Go 默认打印顺序不保证（如 map 迭代顺序随机），应改用 json.Marshal 或预排序再打印
• 避免直接打印指针地址或时间戳等不可控值；若需演示，用固定值替代（如 time.Unix(0, 0)）
• 注释里的 Output: 必须顶格写，后面紧接冒号和空格，不能缩进，也不能换行

Example 文件必须放在 _test.go 里，且包名和源码包一致

Go 要求 Example 函数定义在 *_test.go 文件中，但和普通测试不同：它不能放在 package xxx_test 下，否则 godoc 找不到对应符号。必须和被文档化的代码同包（如源码是 package util，Example 文件也得是 package util）。

• 文件命名建议统一为 example_test.go（单文件）或按功能分，如 map_example_test.go
• 如果源码包是 main，Example 函数无法被外部引用，此时仅对本地 go doc 有效
• 多个 Example 函数可以共存于同一文件，只要函数名不冲突、输出注释不重复

Example 不执行初始化逻辑，依赖的变量/函数必须显式声明或导入

Example 函数不会自动触发 init() 或包级变量初始化。如果示例依赖某个全局配置、缓存或已初始化的 client，必须在函数体内手动构造——别指望它和 Test 共享上下文。

• 不要假设 http.DefaultClient 已就绪；如需 HTTP 示例，显式创建 &http.Client{}
• 包级变量（如 var db *sql.DB）在 Example 中为 nil，需用 sql.Open("sqlite", ":memory:") 这类轻量方式模拟
• 第三方库的类型（如 gin.Context）不能直接 new，得用其提供的测试辅助函数（如 gin.CreateTestContext）

Example 的本质是「可运行的文档」，不是「集成测试」。它越轻、越独立，就越可靠。很多人卡在“为什么 Example 里调用函数 panic”，其实只是忘了补一行 cfg := Config{Timeout: time.Second}。

到这里，我们也就讲完了《Golang如何用Example函数写文档示例》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！