Go go/doc.Examples 的排序怎样按示例名称稳定输出

用 go/doc.Examples 收集示例时，稳定展示应以返回值的 Name 为准，而不是依赖测试文件里函数的书写顺序。这个函数本身已经按 Example.Name 排序；Order 只表示它在输入 AST 中被发现的先后，适合做来源追踪，不适合拿来当展示顺序。

先分清 Name 排序和 Order 来源位置

go/doc.Examples(testFiles ...*ast.File) 会从 AST 中识别合法的 Example 函数，并将结果按 Name 排序。函数名中的 Example 前缀会被去掉，例如 ExampleBuffer 的名称是 Buffer。因此，调用方不需要再按源文件位置排序。

但 Order 仍然有用。它记录示例被扫描时的原始顺序，可以用来解释“这个示例来自文件的哪个位置”。当项目把多个 AST 文件合并后，展示列表仍按名称排序，调试信息则可以保留 Order。

用 AST 构造示例并稳定输出

下面的示例构造一个最小测试文件，调用 doc.Examples 后按返回顺序打印名称。代码中的注释说明了输入、结果和边界，输出顺序不会随着函数在源文件中的排列变化。

package main

import (
    "fmt"
    "go/ast"
    "go/doc"
    "go/parser"
    "go/token"
)

func main() {
    const src = `package demo_test

func ExampleZebra() {}
func ExampleAlpha() {}
func ExampleAlpha_extra() {}
`

    fset := token.NewFileSet()
    // 解析测试包源码，保留声明顺序供 go/doc 记录 Order。
    file, err := parser.ParseFile(fset, "example_test.go", src, parser.ParseComments)
    if err != nil {
        panic(err) // 输入源码不合法时直接终止这个演示程序。
    }

    examples := doc.Examples([]*ast.File{file})
    for _, example := range examples {
        // Name 是稳定展示键；Order 只是扫描时的来源位置。
        fmt.Printf("name=%s order=%d\n", example.Name, example.Order)
    }
}

预期的名称顺序是 Alpha、Alpha_extra、Zebra。这里的 Order 依旧反映扫描先后；如果把函数声明换位，名称排序仍然不变，但 Order 会随输入变化。

后缀、可运行示例和空结果的处理方式

示例函数需要满足无参数、无返回值等约束，否则不会被识别。直接调用 doc.Examples 时，Suffix 不会填充；如果需要从 _test.go 的命名规则得到后缀，应通过 doc.NewFromFiles 让文档包完成关联。

如果输入文件没有合法的 Example 函数，结果是空切片。生产代码可以把“没有示例”当正常状态处理，不要用 examples[0] 直接取值。需要判断是否能在 Go Playground 中运行时，再检查 Play != nil；名称排序与可运行性是两个独立问题。

常见问题

为什么不能按 Order 展示？

Order 依赖输入文件和扫描顺序，文件合并或声明调整后就会变化。需要稳定目录或网页列表时使用 Name。

ExampleAlpha_extra 的 Name 是什么？

直接调用 Examples 时，名称会保留为 Alpha_extra；它仍参与按名称排序，不应把后缀误当成独立排序字段。