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 函数的包归属——写错位置，就等于没写。 
