Example函数必须以Example开头且后跟大写字母或下划线，零参数无返回值，// Output:须紧贴末尾无空行和缩进，否则被静默忽略。
Example 函数必须以 Test 开头才能被 go test 发现
Go 的文档示例（Example 函数）本身不参与测试执行，但 go test 会检查它们是否能编译通过、输出是否匹配注释末尾的 // Output:。前提是函数名必须符合命名规则：以 Example 开头，且**后面紧跟大写字母或下划线**（比如 ExampleHello、Example_sort_Slice），否则会被忽略。
常见错误是写成 exampleHello（小写 e）或 Example_hello（下划线后接小写），这时 go test -v 根本不会列出它，也不会报错，悄无声息地跳过。
-
ExampleFoo✅ 可识别 -
Example_foo❌ 不识别（下划线后小写） -
exampleFoo❌ 不识别（首字母小写） -
ExampleFoo_test❌ 不识别（_test 后缀只用于 Test/ Benchmark 函数）
Output 注释必须紧贴函数末尾，且不能有空行
// Output: 是示例函数的“预期输出断言”，go test 会捕获函数实际 stdout 并与之逐行比对。但它对格式极其敏感：必须出现在函数体最后一行之后、紧接着一个空行之前；中间不能有空行，也不能缩进。
容易踩的坑是复制粘贴时带了空格，或在 // Output: 前多按了一次回车 —— 这会导致测试直接失败，报错类似 no example output found 或 output mismatch。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- ✅ 正确写法：
func ExampleGreet() { fmt.Println("hello") } // Output: // hello - ❌ 错误写法：
// Output: // hello
（// Output:后多了一个空行） - ❌ 错误写法：
// Output: // 缩进导致不识别
Example 函数不能接收参数，也不能返回值
Go 文档工具和测试框架只接受零参数、无返回值的 func ExampleXXX() 形式。哪怕加一个 int 参数或返回 error，go test 就会静默跳过，godoc 也无法渲染为示例。
如果你需要演示带输入的场景（比如传入不同字符串），只能靠变量赋值模拟，不能用函数签名传递：
- ✅ 正确：
func ExampleParseInt() { s := "42" i, _ := strconv.Atoi(s) fmt.Println(i) } // Output: // 42 - ❌ 错误：
func ExampleParseInt(s string) { ... }（编译失败，且不被识别） - ❌ 错误：
func ExampleParseInt() (int, error) { ... }（语法合法但不被识别为 Example）
生成 HTML 文档时，Example 只显示在包级或类型/函数页，不单独索引
godoc 或 go doc 生成的文档中，Example 函数内容会内嵌在它所归属的包、类型或函数说明下方，而不是作为独立条目出现。也就是说，ExampleSliceSort 会出现在 sort 包文档里，或紧挨着 sort.Slice 的说明之后 —— 但你搜不到 “ExampleSliceSort” 这个词条。
这意味着：想让示例被用户看到，它必须和目标 API 在同一个包里，且函数名要体现关联性（如 ExampleMapRange 对应 range 遍历 map）。另外，如果包里没有导出类型或函数，Example 也可能被忽略或无法归类。
- 包里只有
ExampleXXX没有导出项 → 文档可能为空或不展示示例 -
ExampleXXX在foo_test.go但未和foo.go同包 → 不会被关联到对应 API - 使用
go doc -html查看时，需点进具体函数/包页才见示例块
