如何在 Go API 文档中添加示例-Golang-PHP中文网

如何在 Go API 文档中添加示例

DDD

发布： 2025-09-24 19:47:01

原创

273人浏览过

如何在 go api 文档中添加示例

本文介绍了如何在 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 的函数，用于反转字符串。

在Android

本文档主要讲述的是在Android-Studio中导入Vitamio框架；介绍了如何将Vitamio框架以Module的形式添加到自己的项目中使用,这个方法也适合导入其他模块实现步骤。希望本文档会给有需要的朋友带来帮助；感兴趣的朋友可以过来看看

查看详情

// 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 函数在输出换行符和空格时的行为。
如果整个测试文件只包含一个示例函数，并且至少包含一个其他函数、类型、变量或常量声明，并且没有测试或基准测试函数，则整个测试文件将作为示例呈现。