Go ast.Inspect 遍历 AST 时怎样提前停止

Go ast.Inspect 的回调返回 false，只会跳过当前节点的子树，不能当作整棵 AST 的 break。找到目标后，可以用外部变量记住结果，让后续回调直接返回 false；如果需要真正结束迭代，Go 1.23 及以上可以用 ast.Preorder 配合 break。

官方地址：https://pkg.go.dev/go/ast

先分清 false 管的是哪一层

这个问题来自遍历接口的控制范围，并非一条新版本发布消息。Inspect 按深度优先访问节点：回调返回 true 时继续访问非空子节点，随后还有一次参数为 nil 的退出通知；返回 false 时不进入该节点的子树，也没有该节点对应的退出通知。祖先节点尚未处理的其他孩子并不会因此全部取消。

例如文件包含 Target 和 Other 两个函数声明。在 Target 的声明节点返回 false，可以避开 Target 的函数体，但不等于文件里的 Other 声明消失。对根节点直接返回 false 确实只访问根就结束，因为根的整棵子树被跳过；这也意味着根内部的目标根本不会被搜索。

快速尝试：只保留第一个函数声明

下面通过 parser.ParseFile 构造 AST，再查找名为 Target 的 FuncDecl。found 同时承担结果和业务停止标记。此例用于静态演示，未提供本机运行记录。

package main

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

// firstFunc 停止后续业务匹配，但不声称立即终止 Inspect 内部遍历。
func firstFunc(root ast.Node, name string) *ast.FuncDecl {
    if root == nil { // 空根节点在调用 Inspect 前处理。
        return nil
    }
    var found *ast.FuncDecl
    ast.Inspect(root, func(n ast.Node) bool {
        if found != nil || n == nil {
            return false // 已命中时，后续回调直接剪枝；nil 是退出通知。
        }
        fn, ok := n.(*ast.FuncDecl)
        if ok && fn.Name.Name == name {
            found = fn // 只保留第一个命中，避免后续覆盖。
            return false
        }
        return true // 非目标节点仍可能包含目标，允许继续下探。
    })
    return found
}

func main() {
    // 本次原创输入：第二个函数用于说明兄弟声明仍属于同一文件。
    src := "package sample\nfunc Target() {}\nfunc Other() {}\n"
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "sample.go", src, 0)
    if err != nil {
        fmt.Println("解析失败:", err)
        return
    }
    fn := firstFunc(file, "Target")
    if fn == nil {
        fmt.Println("未找到")
        return
    }
    fmt.Println("找到:", fn.Name.Name)
}

按代码语义，该输入应选中 Target，输出对应的函数名；若没有匹配则返回 nil。命中后不再做类型判断和名字比较，也不再展开新遇到的子树，但已进入的祖先仍可能处理它们剩余的子节点、发出退出通知。因此不要把这个方案写成“Inspect 立即全局终止”，也不要据此保证常数时间返回。

这里查的是函数声明名字，不是在识别某个库函数的调用；若问题变成“同名标识符是否属于同一个对象”，还需要类型信息，已经超出这段筛选代码的范围。

和迭代方案对比：需要 break 时换成 Preorder

ast.Preorder 从 Go 1.23 开始提供节点迭代序列，适合“遇到第一个满足条件的节点就停止”的需求。它仍是深度优先的前序节点序列，但循环体不会收到 Inspect 那样的 nil 退出通知。

// 需要 Go 1.23+；放在已经导入 go/ast 的文件中。
func firstFuncPreorder(root ast.Node, name string) *ast.FuncDecl {
    if root == nil {
        return nil // 不把空节点交给遍历器。
    }
    var found *ast.FuncDecl
    for n := range ast.Preorder(root) {
        fn, ok := n.(*ast.FuncDecl)
        if ok && fn.Name.Name == name {
            found = fn
            break // 退出迭代循环，后续节点不再交给循环体。
        }
    }
    return found
}

这个版本可以替换前例中的查找函数，调用方式保持一致。break 终止本次迭代；它不会撤销此前完成的处理，也不会自动结束外层多文件循环。Preorder 便于全局停止，而 Inspect 更便于按节点跳过某棵子树，两者适用点不同。

采用前留意这些边界

不要在没命中时一律返回 false，否则可能把目标所在的子树提前裁掉。不要先对 n 做强制类型断言再判断 nil；安全的类型断言与明确的 nil 分支更容易维护。若回调维护节点栈，只有返回 true 的节点才有配对的退出通知，不能把每次回调都当作一次入栈。

如果只是查找顶层函数声明，还可以直接遍历 file.Decls；不必为了一个列表筛选深入全部 AST。这是对本例任务范围的简化，不改变 Inspect 的返回值含义。本文两种写法都只读 AST，没有共享到其他 goroutine；需要并发处理时，应给各次遍历独立的查询状态。

为什么 return false 后计数还增加？

计数若放在回调最前面，兄弟节点或祖先的 nil 通知都可能计入。把“收到回调次数”和“完成有效匹配次数”分开统计，才能解释现象。

能否用 panic 快速退出？

不建议把普通查找命中包装成异常控制。能够使用 Preorder 时直接 break；需要剪枝或兼容工具链时保留 Inspect 的显式状态即可。

相关技术依据：Inspect 与 Preorder 官方文档、Go 官方遍历实现。