Go inspector.WithStack 怎样读取 AST 节点的祖先链

我第一次用 Go 做 AST 检查时，最容易混淆的不是怎么找到目标节点，而是找到以后怎样知道它位于哪个函数、代码块和控制结构中。inspector.WithStack 正好解决这个问题：它把当前遍历路径作为 []ast.Node 传给回调。

官方文档：https://pkg.go.dev/golang.org/x/tools/go/ast/inspector#Inspector.WithStack

读取 AST 祖先链时，在 push == true 的回调中使用 stack 即可。stack[0] 是最外层的 *ast.File，最后一个元素是当前节点 n。需要长期保存时，先复制切片，不要直接保存回调参数。

WithStack 传入的 stack 到底表示什么

假设一个函数调用表达式嵌套在函数体中，遍历路径可以抽象成：

*ast.File -> *ast.FuncDecl -> *ast.BlockStmt -> *ast.IfStmt -> *ast.CallExpr

当回调处理这个 *ast.CallExpr 时，stack 就按这个顺序保存从根到当前节点的节点对象。它不是“只匹配筛选类型的列表”：即使 types 只筛选 *ast.CallExpr，栈中仍然会包含中间的 *ast.FuncDecl、*ast.BlockStmt 等祖先。

先准备一棵可以遍历的 AST

WithStack 接收的是已经构造好的 Inspector。下面的示例解析一段内存中的 Go 源码，并只关注函数调用表达式：

package main

import (
    "fmt"
    "go/ast"
    "go/parser"
    "go/token"
    "golang.org/x/tools/go/ast/inspector"
    "strings"
)

func main() {
    const source = `package demo

func run(ok bool) {
    if ok {
        fmt.Println("ready")
    }
}`

    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", source, 0)
    if err != nil {
        // 解析失败时没有可用的 AST，立即返回并保留原始错误。
        panic(err)
    }

    in := inspector.New([]*ast.File{file})
    in.WithStack([]ast.Node{(*ast.CallExpr)(nil)}, func(
        n ast.Node, push bool, stack []ast.Node,
    ) bool {
        // 只在进入节点时读取祖先路径，避免同一个节点处理两次。
        if !push {
            return true
        }

        names := make([]string, 0, len(stack))
        for _, ancestor := range stack {
            // %T 便于先观察 AST 类型，实际工具可改成位置或自定义标签。
            names = append(names, fmt.Sprintf("%T", ancestor))
        }
        fmt.Println(strings.Join(names, " -> "))
        return true
    })
}

这个例子里的 types 只放了 (*ast.CallExpr)(nil)。这是类型筛选标记，不是要传入一个真实节点；inspector 会据此判断哪些事件需要回调，而完整祖先关系仍然由 stack 提供。

用 push=true 读取当前节点的祖先链

WithStack 的回调签名是 func(n ast.Node, push bool, stack []ast.Node) bool。进入节点时 push 为 true，离开节点时为 false。最常见的“找出调用发生在哪个函数里”场景，只需要处理进入事件：

in.WithStack([]ast.Node{(*ast.CallExpr)(nil)}, func(
    n ast.Node, push bool, stack []ast.Node,
) bool {
    if !push {
        // 离开事件用于收尾；本例没有需要收尾的状态。
        return true
    }

    var function *ast.FuncDecl
    for i := len(stack) - 1; i >= 0; i-- {
        // 从当前节点向外找，最近的函数声明就是所属函数。
        if candidate, ok := stack[i].(*ast.FuncDecl); ok {
            function = candidate
            break
        }
    }
    if function != nil {
        fmt.Printf("调用位于函数 %s 中\n", function.Name.Name)
    }
    return true
})

这里从栈尾反向查找，是因为越靠近当前节点的祖先越先满足“最近所属函数”。如果工具需要的是完整路径，就按正序遍历；如果只需要最近的块、函数或声明，反向遍历可以少做无用判断。

为什么要区分 push 和 pop

进入事件适合建立上下文，离开事件适合提交结果或清理状态。官方实现会在进入节点时把节点压入内部栈，在离开节点后再移除它，因此回调期间的 stack 仍然表达当前遍历位置。

如果要统计一个函数体中出现了多少次调用，可以在进入时增加计数，在离开函数声明时提交结果：

depth := 0
calls := 0
in.WithStack([]ast.Node{
    (*ast.FuncDecl)(nil),
    (*ast.CallExpr)(nil),
}, func(n ast.Node, push bool, stack []ast.Node) bool {
    switch n.(type) {
    case *ast.FuncDecl:
        if push {
            // 进入函数时开启一个新的统计上下文。
            depth++
        } else {
            // 离开函数时输出结果，再关闭当前上下文。
            fmt.Printf("函数层级=%d，调用数=%d\n", depth, calls)
            depth--
            calls = 0
        }
    case *ast.CallExpr:
        if push {
            // 只统计进入事件，避免一次调用被算两次。
            calls++
        }
    }
    return true
})

上面的计数代码为了突出回调语义而保持简单。嵌套函数、多个文件或并行分析时，应把计数状态放入自己的上下文结构，并明确函数节点与调用节点的归属关系。

返回 false 会发生什么

回调的返回值控制是否继续进入当前节点的子树。返回 false 并不会把当前节点从结果中删除，它只会跳过当前节点下面的后代遍历。因此，如果某个函数已经被标记为无需检查，可以在它的进入事件直接剪枝：

in.WithStack([]ast.Node{(*ast.FuncDecl)(nil), (*ast.CallExpr)(nil)}, func(
    n ast.Node, push bool, stack []ast.Node,
) bool {
    if !push {
        return true
    }

    fn, ok := n.(*ast.FuncDecl)
    if ok && fn.Name != nil && fn.Name.Name == "generated" {
        // 生成函数不参与本次分析，返回 false 跳过它的整棵子树。
        return false
    }
    return true
})

一个常见误区是把返回值理解成“是否保留当前节点”。更准确的理解是“是否继续向当前节点的孩子深入”。剪枝后，后代节点不会再触发本次遍历的回调。

保存祖先链时不要直接留住 stack

stack 是遍历器为了当前回调维护的切片。回调结束后，内部会继续复用底层数组并调整长度。如果要把祖先链交给后续阶段，应该复制其中的元素：

var paths [][]ast.Node
in.WithStack([]ast.Node{(*ast.CallExpr)(nil)}, func(
    n ast.Node, push bool, stack []ast.Node,
) bool {
    if push {
        // 复制元素而不是保存 stack 本身，避免后续回溯改变已记录路径。
        path := append([]ast.Node(nil), stack...)
        paths = append(paths, path)
    }
    return true
})

如果只需要输出字符串、位置或自定义标签，也可以在回调中立即转换成自己的值，这样不必让 ast.Node 对象跨越遍历生命周期。

什么时候改用 Cursor.Enclosing

当前版本的 inspector 还提供了 Cursor API。官方文档把 Cursor.Enclosing 描述为从当前节点开始向外枚举包围它的节点；当你已经定位到一个具体 Cursor，需要在树中继续向父节点、兄弟节点或子节点导航时，它比全局的 WithStack 更顺手。

几个容易踩到的边界

• 不要把 stack 当成筛选结果。筛选只决定哪些节点触发回调，stack 仍包含完整祖先路径。
• 不要忽略 pop。需要维护进入/退出状态时，必须让两类事件成对处理。
• 不要在回调外直接复用 stack。保存路径前复制切片，或者当场转换成不可变的业务数据。
• 不要为了单次扫描盲目使用 Inspector。官方说明指出 Inspector 适合多次遍历摊薄构造成本，小任务可以直接使用 ast.Inspect。

结语

把 WithStack 记成“带路径的 Nodes”最容易。进入事件拿到从 *ast.File 到当前节点的祖先链，离开事件用于回收上下文，返回值负责决定是否继续向子树深入；这三点掌握后，函数归属、控制结构定位和 AST 规则诊断都可以在同一条路径上完成。

相关问题

WithStack 的 stack 顺序是怎样的？从最外层节点开始，到当前回调节点结束，通常首元素是 *ast.File。

筛选类型会不会让 stack 只剩筛选类型？不会。筛选影响回调触发，stack 仍保留中间祖先。

返回 false 会不会跳过当前节点？不会，它表示不再进入当前节点的子树。

只想找父节点时必须用 WithStack 吗？不必须。已经有 Cursor 时，可以考虑 Parent 或 Enclosing。