示例函数类似于单元测试函数,但没有 *testing 类型的参数。编写示例函数也是很容易的:
以 json 格式校验工具 https://github.com/luduoxin/json-validator-go 为例,validator 包中的 scanner.go 文件中的关键函数 Valid 用于校验给定字符串是否 json 格式,对应的测试文件为 scanner_test.go,里面的示例函数为 ExampleValid,代码如下:
func ExampleValid() {
fmt.Println(Valid([]byte("{}")))
// output: true
}
运行看下效果:
=== RUN ExampleValid
--- PASS: ExampleValid (0.00s)
PASS
看一个有多条输出结果的示例:
func ExampleValid() {
fmt.Println(Valid([]byte("{}")))
fmt.Println(Valid([]byte(`a:b`)))
// output: true
// false
}
运行看下效果:
=== RUN ExampleValid
--- PASS: ExampleValid (0.00s)
PASS
看一个 “Unordered output:” 注释的示例:
func ExampleValid() {
fmt.Println(Valid([]byte("{}")))
fmt.Println(Valid([]byte(`{"a":"b"}`)))
// Unordered output: true
// true
}
运行看下效果:
=== RUN ExampleValid
--- PASS: ExampleValid (0.00s)
PASS
看一个测试不通过的示例:
func ExampleValid() {
fmt.Println(Valid([]byte("{}")))
fmt.Println(Valid([]byte(`{"a":"b"}`)))
// Unordered output: true
// false
}
运行看下效果:
=== RUN ExampleValid
--- FAIL: ExampleValid (0.00s)
got:
true
true
看一个没有 output 注释的示例:
func ExampleValid() {
fmt.Println(Valid([]byte("{}")))
}
运行 go test 命令,此函数不会被执行。
上面测试通过的示例(运行结果为 PASS 的示例)的通过是什么意思呢?就是在执行示例时,测试框架捕获写入到标准输出的数据,然后与 “output:” 注释中的结果进行比较,如果匹配,则测试通过,否则测试不通过(结果为 FAIL)。
示例函数会在 Godoc 中作为对应函数的示例,看 Golang 官方的一张截图:
Godoc 使用命名约定将示例函数与包级标的识符关联起来。约定规则如下:
func ExampleFoo() // documents the Foo function or type
func ExampleBar_Qux() // documents the Qux method of type Bar
func Example() // documents the package as a whole
按照这个约定,Godoc 将在 Reverse 函数的文档旁边显示 ExampleReverse 示例。通过使用以下划线开头、后跟小写字母的后缀,可以为指定函数(或者包、结构体、方法等)提供多个示例。如下:
func ExampleReverse()
func ExampleReverse_second()
func ExampleReverse_third()
本文详细讲解了 Golang 中的可测试示例函数, 可以很方便地转换为 Godoc 中可读性很强的文档,这也是 Golang 提倡的代码即文档的一个最佳实践,如果你还没有使用过,赶快使用起来吧。