本文介绍了如何在 Go 语言的 API 文档中添加可执行的示例代码。通过遵循 go test 命令的规则，在 *_test.go 文件中编写特殊的示例函数，并利用 Output: 注释进行输出验证，可以方便地为你的 Go 代码提供清晰、可运行的用例，从而提升 API 的易用性和可理解性。
Go 语言提供了一种便捷的方式来为 API 文档添加可执行的示例代码，这些示例代码不仅可以帮助用户更好地理解 API 的用法，还可以通过 go test 命令进行验证，确保示例的正确性。
编写示例函数
示例函数需要遵循一定的命名规则，并放置在与被测试包对应的 *_test.go 文件中。
- 命名规则： 示例函数必须以 Example 开头，后跟要演示的函数、常量或变量的名称。例如，要演示 Println 函数的用法，示例函数应命名为 ExamplePrintln。 如果要演示类型 T 的方法 M，则示例函数应命名为 ExampleT_M。
- 签名： 示例函数没有参数或返回值。
- 位置： 示例函数必须位于与被测试包对应的 *_test.go 文件中。
使用 Output: 注释进行输出验证
为了让 go test 命令能够验证示例的正确性，需要在示例函数的末尾添加 Output: 注释，并在注释中指定期望的输出结果。
func ExamplePrintln() {
fmt.Println("Hello, world!")
// Output: Hello, world!
}在上面的示例中，Output: Hello, world! 注释告诉 go test 命令，ExamplePrintln 函数的期望输出是 Hello, world!。 当运行 go test 命令时，它将执行 ExamplePrintln 函数，并将实际输出与 Output: 注释中的期望输出进行比较。 如果两者匹配，则测试通过；否则，测试失败。
示例代码
下面是一个更完整的示例，演示了如何为自定义函数添加示例代码：
假设我们有一个名为 stringutil 的包，其中包含一个名为 Reverse 的函数，用于反转字符串。
// stringutil/reverse.go
package stringutil
// Reverse returns its argument string reversed rune-wise left to right.
func Reverse(s string) string {
r := []rune(s)
for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
r[i], r[j] = r[j], r[i]
}
return string(r)
}现在，我们可以创建一个名为 stringutil_test.go 的文件，并在其中添加一个示例函数来演示 Reverse 函数的用法：
// stringutil/stringutil_test.go
package stringutil_test
import (
"fmt"
"github.com/yourusername/stringutil" // 替换为你的模块路径
)
func ExampleReverse() {
fmt.Println(stringutil.Reverse("hello"))
fmt.Println(stringutil.Reverse("你好世界"))
// Output:
// olleh
// 界世好你
}注意以下几点：
- package stringutil_test： 示例函数位于 stringutil_test 包中，而不是 stringutil 包中。 这是因为示例代码通常需要访问被测试包的内部状态，而 stringutil_test 包可以访问 stringutil 包的非导出成员。
- import "fmt"： 示例代码需要导入 fmt 包才能使用 Println 函数。
- import "github.com/yourusername/stringutil"： 示例代码需要导入 stringutil 包才能使用 Reverse 函数。请将 github.com/yourusername/stringutil 替换为你的模块路径。
- Output: 注释包含两行输出，分别对应于对 Reverse 函数的两次调用。
运行测试
要运行测试并验证示例的正确性，可以使用 go test 命令：
go test github.com/yourusername/stringutil
如果所有测试都通过，则表示示例代码正确无误。
注意事项
- Output: 注释必须是示例函数中的最后一个注释。
- Output: 注释中的期望输出必须与示例函数的实际输出完全匹配，包括空格和换行符。
- 可以为同一个函数、常量或变量添加多个示例函数，只需在示例函数名称后添加 _xxx 后缀即可，其中 xxx 是一个不以大写字母开头的后缀。例如，可以为 Println 函数添加 ExamplePrintln_newline 和 ExamplePrintln_space 两个示例函数，分别演示 Println 函数在输出换行符和空格时的行为。
- 如果整个测试文件只包含一个示例函数，并且至少包含一个其他函数、类型、变量或常量声明，并且没有测试或基准测试函数，则整个测试文件将作为示例呈现。
总结
通过遵循上述步骤，可以方便地为 Go API 文档添加可执行的示例代码，从而提升 API 的易用性和可理解性。 示例代码不仅可以帮助用户更好地理解 API 的用法，还可以通过 go test 命令进行验证，确保示例的正确性。
