Go 示例测试怎么让文档输出成为可执行回归用例

Go 的示例测试不只是给读者看的代码片段。只要函数名和结尾注释符合约定，go test 就会把它编译、执行，并把标准输出和注释中的期望结果进行比较。这样一来，包文档里的用法说明也能随着 API 一起回归。

要让文档输出成为可执行回归用例，关键是把示例放在 _test.go 中，用 Example... 命名，并用 // Output: 明确写出稳定结果；输出顺序确实无关时才使用 // Unordered output:。

先把示例命名和输出契约写对

示例函数通常放在 example_test.go 或其他 _test.go 文件中，不接收参数，也不返回值。Example() 说明整个包，ExampleJoin() 关联 Join，ExampleConfig_Load() 则可以关联类型 Config 的 Load 方法。需要给同一个对象写多个示例时，后缀应从小写字母开始，例如 ExampleJoin_csv。

下面的示例把结果直接写在代码旁边。注释既是读者看到的预期，也是一条测试契约：

package textutil_test

import (
    "fmt"
    "strings"
)

func ExampleJoin() {
    // 用固定输入展示 Join 的分隔符语义，避免示例结果依赖环境。
    words := []string{"Go", "test", "docs"}
    fmt.Println(strings.Join(words, " / "))
    // Output: Go / test / docs
}

Output 注释怎样把文档变成回归检查

测试框架会捕获示例写到标准输出的内容，再与 Output: 后面的文本比较。单行可以写在同一行，多行则把期望结果逐行写在后续注释中。比较时，开头和结尾的空白不会成为无意义的噪声，但正文内容仍然必须一致。

如果实现后来输出了 Go / docs / test，而注释仍是 Go / test / docs，示例就会失败，报告会同时给出 got 和 want。这正是文档回归的价值：API 行为改变、示例输入被改坏，或者输出格式被无意调整时，维护者不用等用户发现页面已经过时。

没有 Output: 的示例仍然会参与编译，但不会执行输出验证。它适合展示网络访问、随机值或需要外部环境的调用方式，不过这类代码只能保证“写法能编译”，不能保证文档描述的结果仍然成立。

顺序不稳定时只放宽必要部分

如果输出来自 map、并发任务或其他不保证遍历顺序的结构，不要为了让测试通过而随意排序业务结果。确认读者只关心“有哪些行”而不关心“行的顺序”后，可以使用 Unordered output:：

func ExampleTags() {
    // 这里演示集合内容，测试不把遍历顺序当成业务承诺。
    for _, tag := range []string{"go", "testing", "docs"} {
        fmt.Println(tag)
    }
    // Unordered output:
    // go
    // testing
    // docs
}

这个写法只改变比较规则，不会替你修复真正的顺序问题。如果产品需要固定展示顺序，就应该在正文代码中显式排序，并继续使用普通的 Output:。判断标准很简单：顺序是 API 语义的一部分，就锁定顺序；顺序只是实现细节，才考虑无序比较。

用同一条命令把示例接入 CI

日常开发可以先精确运行一个示例，改动完成后再运行整个模块：

# 先只回归当前示例，缩短本地反馈时间
go test -run '^ExampleJoin$' ./path/to/textutil

# 提交前同时编译并执行所有包的示例与普通测试
go test ./...

# 需要查看每个示例名称时打开详细输出
go test -v ./...

-run 使用正则匹配测试名，精确锚定可以避免误跑同名变体。CI 中通常保留 go test ./... 作为门禁；它会把示例和 TestXxx、基准相关的编译检查放在同一轮，文档回归不会变成一条被遗忘的独立脚本。

常见问题

为什么示例写了 fmt.Println 却没有失败提示？

先检查是否存在精确的 Output: 或 Unordered output: 注释。没有输出注释时，示例只编译不执行。

Output 注释能验证标准错误吗？

它针对示例的标准输出。错误路径应转换成稳定的可读结果，或者用普通测试检查错误值，不要把随机堆栈写进输出契约。

所有示例都必须绑定一个函数吗？

不必。Example() 可以作为包级示例；只有需要在文档中靠近某个函数、类型或方法展示时，才使用对应的命名形式。

把示例当作“可编译的文档 + 明确的输出契约”，维护成本通常比单独维护一份 README 代码更低。真正需要锁定的是读者依赖的结果，其他实现细节则不要过早写成测试承诺。