Go ast.Walk 怎样控制语法树节点的递归遍历

在 Go 的源码分析工具里，ast.Walk 最容易让人误解的地方不是“怎么遍历”，而是“怎么决定遍历到哪里”。它没有单独的 stop 参数，真正的控制点在 Visitor.Visit 的返回值：返回 nil 就裁剪当前节点的子树，返回一个非空 visitor 才会继续访问孩子；孩子处理完后，Walk 还会给这个 visitor 一次 Visit(nil) 退出通知。

因此，想只看函数签名、跳过函数体，思路不是在回调里手动维护一套递归，而是在遇到目标节点时返回合适的 visitor。下面按一个小型源码分析器的场景拆开说明。

先记住 Visit 返回值的三种语义

ast.Walk(v, node) 会先调用 v.Visit(node)。假设返回值叫 w，它的行为可以压缩成下面这张表：

这里的 nil 有两个不同位置：Visit 返回 nil 是“不要下钻”，传给 Visit 的 nil 则是“孩子已经遍历完”。把这两种 nil 混为一谈，是遍历状态错乱的常见原因。

准备解析源码并进入 AST

实际使用时，通常先用 go/parser.ParseFile 得到 *ast.File，再把它交给 ast.Walk。如果只是做结构分析，可以带上 parser.SkipObjectResolution，避免依赖已经废弃的对象解析字段。

package main

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

func main() {
    source := `package demo

func Add(a, b int) int {
    return a + b
}

var Version = "v1"
`

    // FileSet 保存 AST 的文件位置，后续可用它把 token.Pos 转成行列。
    fset := token.NewFileSet()
    // SkipObjectResolution 只保留语法结构，避免使用已废弃的对象解析字段。
    file, err := parser.ParseFile(fset, "demo.go", source, parser.SkipObjectResolution)
    if err != nil {
        // 解析失败时保留错误，调用方可以决定是否继续处理部分 AST。
        panic(err)
    }

    // Walk 会从根节点开始深度优先调用 visitor.Visit。
    ast.Walk(printVisitor{}, file)
    fmt.Println("AST root:", file.Name.Name)
}

这个入口只负责两件事：把源码变成树，以及把树交给 visitor。遍历范围和输出策略应该放进 visitor，而不是散落在解析入口里。

用 Visitor 选择性跳过函数体

假设工具只想收集函数名、参数和返回类型，不需要分析函数体里的表达式。遇到 *ast.FuncDecl 时继续下钻，让函数类型可以被访问；遇到它下面的 *ast.BlockStmt 时返回 nil，就能裁剪函数体。

type printVisitor struct {
    depth     int
    skipBlock bool
}

func (v printVisitor) Visit(node ast.Node) ast.Visitor {
    if node == nil {
        // 非 nil visitor 收到 nil，代表当前节点的孩子已经遍历完。
        return nil
    }

    switch node.(type) {
    case *ast.BlockStmt:
        if v.skipBlock {
            // 返回 nil 只裁剪当前 BlockStmt，不会终止整棵 AST 的兄弟节点。
            fmt.Println("skip function body")
            return nil
        }
    }

    fmt.Printf("%*s%T\n", v.depth*2, "", node)

    next := v
    next.depth++
    if _, ok := node.(*ast.FuncDecl); ok {
        // 让函数声明的子节点继承“跳过函数体”策略。
        next.skipBlock = true
    }
    // 返回新的 visitor，Walk 才会继续递归访问当前节点的孩子。
    return next
}

这个实现有两个细节值得保留。第一，FuncDecl 本身不能返回 nil，否则函数名、参数和函数体都会一起被跳过；第二，BlockStmt 返回 nil 只影响当前函数体，外层文件中的其它声明仍然会继续走。

处理 Visit(nil) 和遍历边界

如果 visitor 需要在进入和离开节点时维护状态，应该把“进入”写在 node != nil 分支，把“离开”写在 node == nil 分支。不要在 nil 分支里做类型断言，也不要把它当成一个真实的 AST 节点打印。

还要注意，ast.Walk 是底层的 Visitor 接口，控制力强但样板代码较多。只想用一个布尔返回值决定是否继续下钻时，ast.Inspect 更直接；只需要按深度优先顺序读取每个节点时，较新的 ast.Preorder 也更简洁。文章标题所讨论的“按节点切换 visitor 状态”，仍然适合用 ast.Walk。

最后用四句话检查遍历逻辑

• 先访问当前节点，再决定是否进入孩子。
• 返回 nil 只裁剪当前节点的子树，不等于停止整个 Walk。
• 返回非 nil visitor 后，孩子完成会收到一次 Visit(nil)。
• 需要保留上下文时返回带新状态的 visitor，避免用共享全局变量记录深度。

常见问题

返回 nil 会不会让后面的顶层声明也不再访问？

不会。nil 只让当前节点不再递归到孩子；父节点的其它孩子仍按 ast.Walk 的规则继续处理。

为什么 Visit(nil) 里不能直接读取节点类型？

因为它是遍历结束通知，不是一个具体 AST 节点。此时应该做状态收尾，例如减少深度或关闭当前上下文。

只想跳过函数体，为什么不在 FuncDecl 处直接返回 nil？

那样会连函数类型、参数和返回值一起裁剪。把判断放到 BlockStmt，才能保留签名、只跳过函数体。