Go doc 注释中的示例如何被测试工具识别

Go 的示例函数不是普通注释代码。只要文件名以 _test.go 结尾、函数名符合 Example... 约定，Go 工具链就能把它同时当作文档示例和测试入口。真正让示例参与断言的是函数末尾的 Output: 注释：go test 会捕获标准输出，并与注释中的期望文本比较。

先把示例放进正确的测试文件

示例应放在被测包目录的 example_test.go 或其他 _test.go 文件中。函数不接收参数，也不返回值，最小形态如下。代码中的中文注释只解释关键约束，不是运行日志。

package strings_test

import (
    "fmt"
    "strings"
)

// ExampleJoin 展示可执行示例的最小结构，输出注释会参与测试。
func ExampleJoin() {
    // 使用标准库 API 产生稳定、可重复的字符串结果。
    fmt.Println(strings.Join([]string{"Go", "doc"}, "-"))
    // Output: Go-doc
}

采用 package strings_test 的外部测试包时，示例只能通过公开 API 访问实现，更接近读者实际使用方式。若示例必须访问包内未导出的辅助对象，可以改用同包名，但要意识到它暴露的不是公共使用路径。

函数名决定示例显示在哪个 API 旁边

Go 文档工具根据函数名解析归属，而不是根据文件名猜测。常用映射可以记成下面这张表：

附加后缀要以下划线和小写字母开头，例如 ExampleJoin_csv。后缀是示例的区分名，不应把完整句子或大写单词塞进函数名，否则文档归属可能不符合预期。

Output 注释会把文档示例变成可执行断言

Output: 后面可以直接写一行，也可以换成多行注释。测试框架会捕获示例写入标准输出的内容，比较时会忽略首尾空白；中间换行和文本内容仍然必须一致。

func ExampleSalutation() {
    // 先固定打印顺序，避免示例输出随着 map 遍历顺序变化。
    fmt.Println("hello, and")
    fmt.Println("goodbye")
    // Output:
    // hello, and
    // goodbye
}

如果把输出注释改成错误文本，测试会显示 got 和 want，这正是示例维护的价值：API 行为变化或示例代码过期时，文档不会悄悄失真。示例没有 Output: 时仍可编译，但不会被执行，适合网络访问、随机结果或需要外部环境的片段。

不稳定输出要选择正确的断言边界

对输出行顺序不固定、但每一行内容都重要的场景，可以使用 Unordered output:。它表达的是“允许行重排”，不是“忽略所有差异”。例如遍历集合时，先确保每行都完整输出，再把顺序交给示例框架处理。

func ExamplePerm() {
    values := []int{2, 1, 3}
    for _, value := range values {
        // 每行仍然是可比较的事实，只是不把行顺序当作契约。
        fmt.Println(value)
    }
    // Unordered output: 1
    // 2
    // 3
}

对于网络响应、当前时间或随机数，不要为了“让测试通过”写一份偶然输出。可以只留下能编译的示例，或者把不稳定部分改造成显式输入，让输出重新变得确定。

常见问题

为什么 Example 函数写好了却没有运行？

先检查文件名是否以 _test.go 结尾、函数是否以大写 Example 开头，以及是否确实运行了 go test。如果没有 Output: 或 Unordered output:，它通常只编译不执行。

ExampleFoo 和 ExampleFoo_bar 有什么区别？

两者都关联 Foo，后者通过小写后缀表示同一对象的另一个示例，适合分别展示不同输入或使用场景。

输出顺序不稳定时能不能直接删掉断言？

如果每行内容仍然应该被验证，优先使用 Unordered output:；只有示例本身无法在测试环境稳定执行时，才省略输出注释并退回到编译检查。

可以把判断简化成一句话：示例名负责“挂到哪份文档”，输出注释负责“是否执行并验证结果”。把这两个约定一起写进 _test.go，文档和测试就会共享同一份可维护代码。