2015年5月7日 Go生态洞察：可测试示例在Go中的应用

猫头虎

发布于 2024-04-09 14:09:34

1010

发布于 2024-04-09 14:09:34

文章被收录于专栏：用户11053981的专栏用户11053981的专栏

2015年5月7日 Go生态洞察：可测试示例在Go中的应用

摘要

🐯 猫头虎博主来啦！今天我们将探索Go语言中一个非常酷炫的特性 —— 可测试示例。这篇文章不仅是对Go的技术深度探讨，还将带你了解如何使文档保持最新。搜索词条：Go语言，可测试示例，技术文档。

引言

📘 Go语言的文档中经常包含可执行的代码片段，这些不仅用于展示包的用法，还能作为测试运行。本文将深入探讨如何编写这些示例函数，并保持文档随API变化而更新。

正文

🧪 示例即测试

Go中的示例函数被编译并可选择执行，作为包测试套件的一部分。这些位于_test.go文件中的函数，与普通测试函数不同，不接受参数并以Example开头。

下面是一个展示reverse包String函数的示例：

package reverse_test

import (
    "fmt"
    "golang.org/x/example/hello/reverse"
)

func ExampleString() {
    fmt.Println(reverse.String("hello"))
    // Output: olleh
}

📸 输出注释

ExampleString函数的“通过”意味着什么？测试框架会捕获标准输出的数据，然后将输出与示例的“Output:”注释进行比较。如果测试输出与注释匹配，则测试通过。

🔍 示例函数命名

Godoc使用命名约定将示例函数与包级标识符关联。例如：

func ExampleFoo()     // 文档中的Foo函数或类型
func ExampleBar_Qux() // 文档中Bar类型的Qux方法
func Example()        // 文档中整个包

🌍 更大的示例

有时我们需要不止一个函数来编写好的示例。例如，为了展示sort包，我们应该展示sort.Interface的实现。示例必须包括除示例函数外的一些上下文。

package sort_test

import (
    "fmt"
    "sort"
)

type Person struct {
    Name string
    Age  int
}

func (p Person) String() string {
    return fmt.Sprintf("%s: %d", p.Name, p.Age)
}

type ByAge []Person

func (a ByAge) Len() int           { return len(a) }
func (a ByAge) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
func (a ByAge) Less(i, j int) bool { return a[i].Age < a[j].Age }

func Example() {
    people := []Person{
        {"Bob", 31},
        {"John", 42},
        {"Michael", 17},
        {"Jenny", 26},
    }

    fmt.Println(people)
    sort.Sort(ByAge(people))
    fmt.Println(people)

    // Output:
    // [Bob: 31 John: 42 Michael: 17 Jenny: 26]
    // [Michael: 17 Jenny: 26 Bob: 31 John: 42]
}

📚 表格总结

关键点	描述
示例作为测试	示例函数作为包的测试套件的一部分
输出注释	用于验证示例输出的正确性
示例命名规则	与包级标识符关联的命名约定
大型示例	展示整个文件示例的用法