Go ast.Inspect 返回 false 和 nil 时如何控制子树遍历

用 go/ast 做源码扫描时，最容易误解的是 ast.Inspect 回调的返回值。记住一个顺序就够了：先访问当前节点；返回 true 才进入非空子节点，子节点处理完后再收到一次 f(nil)；返回 false 只裁剪当前节点的子树，不会把整个 AST 遍历停掉。

ast.Inspect 的 true、false 和 nil 分别代表什么

官方定义是深度优先遍历。调用回调时，参数是当前节点；如果回调返回 true，Inspect 会递归访问当前节点的非 nil 子节点，随后再调用一次 f(nil)。因此，nil 更像“这一层已经退出”的标记，不代表 AST 里真的存在一个 nil 节点。

用 false 跳过指定函数体

例如扫描包级声明时只关心函数名，不希望继续分析名为 generated 的函数体，可以在命中函数声明后直接返回 false。这个返回值作用在当前 *ast.FuncDecl 节点上，所以它的参数、代码块和表达式都不会再进入回调；同一层后面的兄弟声明仍会继续。

package main

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

func main() {
    src := `package demo
func generated() { println("skip") }
func visible() { println("visit") }`

    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "demo.go", src, 0)
    if err != nil {
        panic(err) // 解析失败时没有可遍历的 AST，直接终止示例。
    }

    depth := 0
    ast.Inspect(file, func(n ast.Node) bool {
        if n == nil {
            depth-- // nil 是退出通知，和进入节点时的 depth++ 配对。
            return true
        }

        fmt.Printf("%s%s\n", strings.Repeat("  ", depth), nodeName(n))
        if fn, ok := n.(*ast.FuncDecl); ok && fn.Name.Name == "generated" {
            return false // 只跳过 generated 的后代，不影响后续兄弟节点。
        }

        depth++ // 只有允许下钻时才增加深度，避免裁剪分支留下脏状态。
        return true
    })
}

func nodeName(n ast.Node) string {
    switch x := n.(type) {
    case *ast.File:
        return "File"
    case *ast.FuncDecl:
        return "FuncDecl: " + x.Name.Name
    default:
        return fmt.Sprintf("%T", n)
    }
}

这里的关键不是把 false 当成全局 break，而是把它当成“当前节点不再下钻”。如果要跳过的是函数体而仍需读取函数签名，可以对 *ast.BlockStmt 做同样判断；裁剪点越具体，后续统计越不容易丢信息。

nil 分支怎样维护深度和栈

需要输出层级、收集父节点或做进入/退出配对时，通常在普通节点分支压栈，在 n == nil 分支弹栈。注意一个边界：回调返回 false 时不会继续子节点，也不会产生对应的 nil 退出通知，所以不要在返回 false 前先把必须恢复的状态改成“已进入”。上面的示例先判断裁剪条件，再增加 depth，就是为了保持这个配对关系。

生产代码的检查清单

• 进入回调后先处理 n == nil，再做类型断言或访问字段。
• 明确裁剪粒度：返回 false 作用于当前节点的整棵后代树，不是只忽略一个字段。
• 需要退出通知的状态只在允许下钻后创建，避免 false 分支无法回收。
• 若只需要纯前序节点序列，可比较 ast.Preorder；若需要控制下钻，继续使用 Inspect。

常见问题

返回 false 会停止整个 ast.Inspect 吗？

不会。它只跳过当前节点的后代，遍历器仍会回到父层并处理其他兄弟节点。

为什么回调会收到 nil？

这是当前节点的子节点处理完成后的退出通知，便于实现深度计数和栈弹出；它不是一个可继续访问的 AST 节点。

能在 nil 上调用 Pos 或做类型断言吗？

不能。先判断 n == nil 并完成退出逻辑，再对非 nil 节点做类型断言。