GoastInspect怎样在遍历语法树时提前停止

我在写 Go 源码扫描器时，最先遇到的不是“怎么找到节点”，而是“找到以后怎么少走一截”。例如只想看函数声明，却不想继续深入函数体；或者已经命中目标函数，后面的文件节点就没有必要再扫。go/ast.Inspect 的回调返回值正好提供了局部剪枝能力，但它不会替你自动停止整个遍历。

ast.Inspect 按深度优先访问节点：回调返回 true 才会继续进入当前节点的非空子节点，返回 false 只跳过当前子树。回调收到 nil 表示该节点的子树已经访问完；要停止全树扫描，需要自己维护停止状态。

先把三种返回语义分开

官方定义可以压缩成一张小表。这里的“当前节点”是回调正在处理的节点，不是整个 AST 根节点。

因此，回调返回 false 不是“终止 Inspect”。假设当前节点是 *ast.FuncDecl，返回 false 会连它的参数、结果和函数体都不再访问；但同一层后面的声明仍然可能被访问。这个差异决定了剪枝条件应该写在什么节点上。

返回 false 怎样跳过当前子树

下面的示例解析一段源码，只收集顶层函数名。命中 FuncDecl 后返回 false，意味着这个示例不继续检查函数体内部的调用、字面量和嵌套表达式。图中的节点和连线是静态关系说明，代码本身仍需要在你的工程中按输入文件执行。

package main

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

func main() {
    src := `package demo
func Load() { println("body") }
var Version = 1`

    // FileSet 保存 AST 位置；ParseComments 让后续扫描也能看到注释节点。
    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
    if err != nil {
        panic(err)
    }

    ast.Inspect(file, func(node ast.Node) bool {
        decl, ok := node.(*ast.FuncDecl)
        if !ok {
            // 非函数声明继续向下走，避免漏掉更深层的目标节点。
            return true
        }
        fmt.Println("函数:", decl.Name.Name)
        // 当前函数已经完成收集；false 只剪掉它的函数体子树。
        return false
    })
}

这个写法适合“看到声明就够了”的扫描任务。如果你还要识别函数体内是否调用了某个 API，就不能在 FuncDecl 直接返回 false；可以改为继续进入 Body，再对特定的 CallExpr 做判断。

怎样停止整个遍历

全局停止需要一个明确的状态变量。回调命中目标后，把 stop 设为 true；之后每次回调先检查它并返回 false。这样做会停止从当前节点继续向下，也会让后续节点都不再深入，但要注意：Inspect 的实现仍可能完成当前层已经进入的回调边界，所以不要把它当成可中断的并发任务控制器。

func findExportedFunction(file *ast.File, name string) bool {
    found := false
    stop := false

    ast.Inspect(file, func(node ast.Node) bool {
        if stop {
            // 已经找到目标，不再进入后续节点的子树。
            return false
        }

        decl, ok := node.(*ast.FuncDecl)
        if !ok || decl.Name == nil {
            // 继续遍历，直到遇到函数声明。
            return true
        }
        if decl.Name.Name == name && decl.Name.IsExported() {
            found = true
            stop = true
            // 当前函数的内部节点也不再需要检查。
            return false
        }
        return true
    })

    return found
}

如果任务需要“找到第一个匹配项就结束”，上面这种写法足够直观；如果任务需要记录父节点路径、区分同名方法所在的类型或函数，就应考虑 ast.PreorderStack。官方文档说明它会把外层节点栈传给回调，而且回调返回 false 时同样跳过当前子树，但不会像 Inspect 那样额外调用一次回调来表示离开节点。

回调里的 nil 和深度优先顺序别忽略

Inspect 在一个节点的子树访问完成后，会再次以 nil 调用回调。这个行为常被用来维护进入/离开栈，但它也意味着类型断言前不能直接访问节点字段。安全的回调通常先处理停止状态，再判断 node == nil，最后才做类型断言。

func countCalls(file *ast.File) int {
    depth := 0
    calls := 0

    ast.Inspect(file, func(node ast.Node) bool {
        if node == nil {
            // nil 表示当前子树结束；这里把进入层级退回一层。
            if depth > 0 {
                depth--
            }
            return true
        }
        depth++
        if _, ok := node.(*ast.CallExpr); ok {
            calls++
        }
        // 返回 true 才能继续查看调用表达式的参数子树。
        return true
    })
    return calls
}

这个计数示例只是帮助理解回调生命周期。实际工具中不要把自维护的深度变量误当作类型检查结果；AST 只描述语法结构，变量是否存在、调用是否可解析、接口方法是否满足约束，仍然需要 go/types 等类型信息。

源码扫描上线前的边界清单

1. 先决定是“跳过当前子树”还是“停止整个扫描”，不要用一个 false 混淆两种意图。
2. 类型断言前处理 nil，并确认代码确实需要离开节点回调。
3. 如果要查父节点路径，优先评估 PreorderStack，不要用脆弱的全局栈模拟。
4. 解析失败、错误 AST 节点和带构建标签的文件要单独处理，不能把一次遍历当成完整项目分析。
5. 涉及注释时使用 parser.ParseComments，否则扫描器可能根本看不到注释节点。
6. 不要把图中的静态关系、示例输出或节点顺序描述成已经在生产代码中验证过的运行证据。

小结

ast.Inspect 的控制点只有一个，但语义有三层：返回 true 继续下钻，返回 false 剪掉当前子树，回调收到 nil 表示子树结束。要停止全树扫描，维护一个明确的停止状态；要获得父节点路径，再考虑 PreorderStack。把这几个边界分清，源码扫描器就不会因为“提前停止”而漏掉真正需要处理的节点。

相关问题

返回 false 会跳过当前节点本身吗？

不会。当前节点已经先被回调访问，false 控制的是是否继续访问它的非空子节点。

为什么已经命中后还要维护 stop 变量？

因为单次返回 false 只表达当前节点的局部剪枝。用状态变量让后续回调也知道全局扫描已经满足条件，意图更清楚。