Go ast.Inspect 怎么查找指定语法节点

用 ast.Inspect 查找指定语法节点，核心写法是：先把源码解析成 *ast.File，再在回调中对 ast.Node 做具体类型断言，最后检查节点字段是否符合目标条件。回调返回 true 表示继续进入当前节点的子树，返回 false 表示跳过该子树；匹配后可用 token.FileSet 把 node.Pos() 转成文件、行和列。

例如要找 fmt.Println 调用，不能只匹配名称为 Println 的 *ast.Ident，而应依次确认 *ast.CallExpr、*ast.SelectorExpr、包标识符 fmt 和选择器名称 Println。这样才能把普通变量、函数声明和其他包的同名成员排除掉。

官方文档：https://pkg.go.dev/go/ast#Inspect

从文本搜索迁移到 AST 搜索，范围要先定清

直接在源码字符串里搜索 fmt.Println( 很方便，但它会受到空格、换行、别名导入、注释和字符串字面量影响。AST 搜索的升级点不是“搜索速度一定更快”，而是把判断对象从文本片段改成有类型、有字段、有源码位置的语法节点。

这类迁移适合查找函数声明、调用表达式、结构体字段、赋值语句、返回语句等语法事实。如果问题需要判断某个标识符究竟来自哪个包、变量是否遮蔽了导入名，单靠 go/ast 仍不够，还需要 go/types 做语义解析。本文只处理单文件中的语法节点查找。

Inspect 的回调契约决定了遍历结果

官方定义很精确：Inspect 以深度优先方式遍历，先对当前非空节点调用回调；回调返回 true 时才递归访问非空子节点；子节点访问结束后，还会再调用一次 f(nil)。这次 nil 调用可以用作离开子树的通知。

如果回调一开始就调用 n.Pos()，没有先判断 n == nil，遍历到离开通知时就会发生空指针错误。最稳妥的骨架如下：

ast.Inspect(file, func(n ast.Node) bool {
    if n == nil {
        // nil 表示当前子树已经访问完毕
        return false
    }

    // true 表示允许 Inspect 继续访问当前节点的子节点
    return true
})

只有在确实不需要当前节点内部信息时才返回 false。例如只统计顶层函数声明时，识别到 *ast.FuncDecl 后可以返回 false，避免继续进入函数体；但如果目标是函数内部的调用表达式，这里就必须返回 true。

新写法分两层：先认类型，再查字段

查找“指定节点”通常包含两层条件。第一层是节点类型，例如 *ast.FuncDecl、*ast.CallExpr；第二层是节点内部字段，例如函数名、选择器名称、接收者或参数数量。

下面先看最小例子：找到名称为 Handle 的函数声明，并记录它的位置。因为目标只是声明本身，匹配到 FuncDecl 后返回 false，不再扫描函数体。

package main

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

type DeclSite struct {
    Name string
    Pos  token.Position
}

func findFunction(fset *token.FileSet, file *ast.File, name string) []DeclSite {
    var found []DeclSite

    ast.Inspect(file, func(n ast.Node) bool {
        if n == nil {
            // 离开子树时不需要额外处理
            return false
        }

        fn, ok := n.(*ast.FuncDecl)
        if !ok {
            // 不是函数声明时继续深入其子节点
            return true
        }

        if fn.Name.Name == name {
            // FileSet 把紧凑的 token.Pos 转成文件、行和列
            found = append(found, DeclSite{
                Name: fn.Name.Name,
                Pos:  fset.Position(fn.Pos()),
            })
        }

        // 本任务只找声明，不需要扫描函数体
        return false
    })

    return found
}

如果只想找普通函数而排除方法，再增加 fn.Recv == nil；如果只想找方法，则检查 fn.Recv != nil。类型断言负责确定节点结构，字段判断负责表达业务条件，两者不要混成对所有 Ident 的模糊名称比较。

完整示例：查找指定包函数调用

函数调用节点是 *ast.CallExpr，但它的 Fun 字段可能是普通标识符、选择器表达式、函数值或其他表达式。要查找形如 fmt.Println(...) 的调用，需要确认 Fun 是 *ast.SelectorExpr，其 X 是名称为 fmt 的 *ast.Ident，并且 Sel.Name 为 Println。

package main

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

type CallSite struct {
    Package  string
    Function string
    Position token.Position
}

func findSelectorCalls(
    fset *token.FileSet,
    root ast.Node,
    packageName string,
    functionName string,
) []CallSite {
    var sites []CallSite

    ast.Inspect(root, func(n ast.Node) bool {
        if n == nil {
            // Inspect 会在子树结束后发送 nil 通知
            return false
        }

        call, ok := n.(*ast.CallExpr)
        if !ok {
            // 当前不是调用表达式，继续查找更深层节点
            return true
        }

        selector, ok := call.Fun.(*ast.SelectorExpr)
        if !ok {
            // 普通函数值调用不符合“包.函数”结构
            return true
        }

        pkg, ok := selector.X.(*ast.Ident)
        if !ok {
            // 链式选择器或其他表达式不按包名处理
            return true
        }

        if pkg.Name == packageName && selector.Sel.Name == functionName {
            sites = append(sites, CallSite{
                Package:  pkg.Name,
                Function: selector.Sel.Name,
                Position: fset.Position(call.Pos()),
            })
        }

        // 调用参数中可能还有嵌套调用，因此继续深入
        return true
    })

    return sites
}

func main() {
    const src = `package demo

import "fmt"

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

    fset := token.NewFileSet()
    file, err := parser.ParseFile(
        fset,
        "demo.go",
        src,
        parser.SkipObjectResolution,
    )
    if err != nil {
        // 语法错误时停止分析，避免使用不完整语法树
        panic(err)
    }

    sites := findSelectorCalls(fset, file, "fmt", "Println")
    for _, site := range sites {
        // Position.String 会输出文件名、行和列
        fmt.Printf("%s.%s at %s\n", site.Package, site.Function, site.Position)
    }
}

这里保留了同一个 FileSet：解析时产生的 token.Pos 只有放回对应文件集，才能换算出正确位置。parser.SkipObjectResolution 适用于只看语法结构的场景；它不会帮你确认 fmt 是否真的是标准库导入名。

旧写法最容易留下三类风险

只匹配 Ident.Name，误报会很多

一个名字可能同时出现在声明、参数、字段、选择器和普通引用里。查找调用时应从 CallExpr 的 Fun 结构向内判断，而不是在全树搜所有 Ident。

在错误层级返回 false，目标子树被剪掉

如果遇到非目标 FuncDecl 就返回 false，那么它的函数体不会再被访问，函数内部的调用节点自然找不到。返回值表达的是“要不要进入当前节点”，不是“当前节点是否匹配”。

把词法名字当成语义对象

源码可能使用别名导入，例如 f "fmt"；局部变量也可能叫 fmt。AST 条件只能确认表面结构。需要无歧义地解析包、对象与类型时，应把结果交给 go/types，不要在语法遍历里补猜。

什么时候改用 Preorder 或 PreorderStack

如果只需要按深度优先前序读取全部节点，不需要剪枝，也不关心离开子树通知，ast.Preorder 的迭代器写法更直接。如果匹配条件依赖父函数、父语句或更完整的祖先路径，ast.PreorderStack 会直接提供包围节点栈。

ast.Inspect 仍然适合两类任务：一是根据节点类型跳过不相关子树，二是利用 nil 通知维护自己的进入/离开状态。选择 API 时先看项目最低 Go 版本，再看是否需要剪枝和祖先上下文，而不是把三种遍历方式混用。

回归检查与迁移清单

• 解析失败立即返回：不要在错误后继续使用可能不完整的语法树。
• 匹配具体节点类型：先确认 CallExpr、FuncDecl 等结构，再判断字段。
• 分开“是否匹配”和“是否深入”：回调返回值只控制当前子树遍历。
• 保留同一 FileSet：用解析时的文件集换算 node.Pos()。
• 测试嵌套节点：调用参数、匿名函数和复合表达式中都可能出现目标。
• 测试同名干扰：加入同名变量、方法和其他包选择器，确认不会误报。
• 语义判断交给 go/types：别名导入和名称遮蔽不能只靠 AST 文本解决。

常见问题

ast.Inspect 能直接只遍历某一种节点吗？

不能在调用参数里声明类型过滤。它会遍历语法树，回调中自行做类型断言。若项目使用 x/tools/go/ast/inspector，可以利用其类型过滤能力，但那属于另一套 API。

找到第一个节点后怎样完全停止？

Inspect 的 false 只跳过当前节点的子树，没有专门的全局停止返回值。可以记录已找到状态并让后续节点都返回 false；若对严格早停有强需求，可编写受控 Visitor 或调整遍历入口。

为什么 Inspect 收到了 nil 节点？

这是官方契约中的离开子树通知，不是解析错误。回调会先收到节点，访问其子节点后再收到 nil；不需要后序逻辑时直接判断并返回即可。

用 Inspect 能遍历 file.Comments 里的所有注释吗？

不能把它当作完整注释列表遍历器。ast.Walk 对文件不会单独遍历 File.Comments，以避免重复访问已经挂在节点上的注释。若目标是所有注释组，应直接遍历 file.Comments。

总结

ast.Inspect 查找指定节点的稳定套路是“类型断言、字段收窄、位置记录、谨慎剪枝”。从文本搜索迁移到 AST 后，最大的收益是判断依据变成真实语法结构；而需要包归属和对象身份时，再明确升级到 go/types。把语法事实与语义事实分开，源码分析工具才不会在同名和格式变化上反复误报。