Go语言示例测试怎么写_示例测试规则说明
示例测试函数名必须以Example开头且无参数无返回值，用于生成文档代码片段并校验输出；需严格匹配// Output:注释内容，不支持testing.T操作，运行需显式指定-run标志。
示例测试函数名必须以 Example 开头
Go 的示例测试（Example test）不是用来验证逻辑正确性的，而是为文档提供可运行的、带输出的代码片段。它会被 go doc 和 godoc 工具自动提取展示，同时也能被 go test 执行并比对输出是否匹配注释末尾的 // Output: 行。
函数名必须严格满足： Example + 可选的驼峰命名（如 Ex），且不能带参数、不能有返回值。否则 
go test 会直接忽略它。
-
func Example() {}✅ 合法，但无意义（没说明是哪个 API 的示例） -
func ExampleSortKeys() {}✅ 推荐：清晰对应某个导出函数或类型 -
func exampleSortKeys() {}❌ 小写开头，不会被识别 -
func ExampleSortKeys(t *testing.T) {}❌ 有参数，会被跳过 -
func ExampleSortKeys() int { return 0 }❌ 有返回值，不合法
// Output: 必须紧贴函数体末尾，且内容要完全匹配
示例测试的输出校验非常严格：Go 运行时会捕获 fmt.Println 等标准输出，并与函数体最后一段以 // Output: 开头的注释逐行比对（包括空行和尾部空格）。
常见失败原因不是代码错，而是输出格式没对齐。比如：
func ExampleJoinStrings() {
fmt.Println(strings.Join([]string{"a", "b", "c"}, "-"))
}
// Output:
// a-b-c
- 注释中
// Output:和实际输出之间**不能有空行**（上面例子是合法的） - 如果代码里是
fmt.Print("a-b-c")（无换行），而注释写的是// a-b-c（隐含换行），就会失败 —— 因为fmt.Print不输出换行，但// Output:默认期望每行末尾有换行符 - 多行输出时，
// Output:后面的每一行都必须精确对应，包括缩进和空格。例如fmt.Printf("%q", "hello")输出"hello"，若注释写成// "hello"（末尾多一个空格），测试即失败
示例测试不能调用 t.Log 或 t.Error
示例函数签名不含 *testing.T，所以无法使用测试断言或日志。它只允许纯演示：构造输入 → 调用目标 API → 输出结果。
如果你需要验证中间状态、处理错误分支、或做条件判断，就不是示例测试该干的事 —— 那属于 TestXXX 函数的范畴。
- ✅ 允许：
fmt.Println(json.Marshal(myStruct)) - ❌ 不允许：
if err != nil { t.Fatal(err) }（编译不过） - ❌ 不推荐：在示例里写
fmt.Println("error case:", err)来“演示错误”，因为这会让// Output:变得脆弱且偏离文档初衷
真正想展示错误处理？单独写一个 ExampleXXXWithError，并在 // Output: 中明确写出错误字符串，前提是那确实是公开 API 合法且稳定的输出形式。
运行和调试示例测试要用 -run 和 -v
默认 go test 不运行示例测试；必须显式启用：
go test -run ^Example
加上 -v 可看到每个示例是否通过、实际输出是什么、预期输出是什么：
go test -v -run ^Example
-
-run ^Example是正则匹配，确保只跑示例函数（^表示开头，避免匹配到TestExampleHelper这类名字） - 如果只想跑某一个，比如
ExampleSortKeys，写成go test -v -run ExampleSortKeys - 调试时输出不匹配？先手动运行示例函数（把内容复制到临时
main.go），看真实输出长什么样，再调整// Output:注释
别忘了：示例测试文件必须放在和被测代码同一包下，且文件名以 _test.go 结尾，否则 go test 根本不会加载它。
