Go go/types.Config.IgnoreFuncBodies 怎样跳过函数体检查

在做 Go 源码索引、API 文档生成或包级依赖分析时，常见需求是“只看声明，不分析每个函数体”。这时可以把 types.Config.IgnoreFuncBodies 设为 true。它的作用很窄：函数体不会被类型检查，但函数名、参数、返回值、方法签名和包级声明仍然属于检查范围。

官方地址：https://pkg.go.dev/go/types#Config

因此，开启它不是让结果“更完整”，而是用较小的检查范围换取更适合包级扫描的结果。若后续要读取函数体内表达式的类型、引用或常量值，就必须关闭该选项，或者把这类需求拆成第二次完整检查。

先把“跳过函数体”说准确

Config 的零值就是可用的默认配置；只有显式设置 IgnoreFuncBodies 后，函数体才不会进入类型检查。官方文档的定义很直接：该字段为真时，函数体不做类型检查。

可以把影响范围分成三层：

这里的“跳过”也不等于从 AST 中删除函数体。解析阶段仍然可以得到完整 AST；变化发生在 go/types 的类型检查阶段。这个区别很重要：如果工具仍需要语法级统计，可以继续遍历 AST；但不要期待 types.Info 自动填充函数体内部的类型结果。

用最小流程接上 IgnoreFuncBodies

下面的示例只检查一段内存中的 Go 源码，并输出包级对象和函数签名。代码故意把 Info 中的 map 明确列出来，方便后续缩小采集范围。

package main

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

func main() {
    const src = `package sample

type User struct { ID int }

func Load(id int) User {
    // 函数体仍在 AST 中，但本次不参与类型检查。
    return User{ID: id}
}`

    fset := token.NewFileSet()
    file, err := parser.ParseFile(fset, "sample.go", src, 0)
    if err != nil {
        // 解析失败时没有可靠的 AST，立即停止后续类型检查。
        panic(err)
    }

    info := &types.Info{
        // 只收集声明和引用，避免误读未检查的函数体信息。
        Defs:  make(map[*ast.Ident]types.Object),
        Uses:  make(map[*ast.Ident]types.Object),
        Types: make(map[ast.Expr]types.TypeAndValue),
    }
    conf := types.Config{
        // 包级分析不需要函数体语义时，跳过函数体检查。
        IgnoreFuncBodies: true,
    }
    pkg, err := conf.Check("sample", fset, []*ast.File{file}, info)
    if err != nil {
        // 类型检查错误仍需按项目策略记录，不能当作 IgnoreFuncBodies 的成功信号。
        fmt.Println("check error:", err)
    }
    if pkg != nil {
        // Package.Scope 能看到包级声明和函数名，不代表函数体已被检查。
        fmt.Println("package:", pkg.Name(), "scope names:", pkg.Scope().Names())
    }
}

这个最小流程有三个关键点。第一，parser.ParseFile 仍然保留函数体；第二，Config.Check 决定是否深入函数体做类型检查；第三，Info 只会填充调用方提供的非空 map，所以不需要的结果可以不申请。

哪些信息会留下，哪些信息不要读取

打开该选项后，包级对象和函数签名仍可用于索引。例如 pkg.Scope().Names() 可以列出包级名字，types.Func.Type() 可以得到函数签名。与此同时，函数体内表达式对应的 info.Types、局部变量定义和引用不能被当作完整结果使用。

如果工具既要生成 API 清单，又要做函数体内的表达式分析，建议把任务拆成两种模式：

1. 包级快速扫描：设置 IgnoreFuncBodies: true，收集声明、签名和包级关系。
2. 局部深度分析：针对需要的包或文件关闭该选项，重新运行 Config.Check，再读取 Info.Types、Defs 和 Uses。

不要在两种模式之间复用同一个 types.Info 并假设它会自动补齐。更稳妥的方式是每次检查都创建新的 Info，并把“快速扫描结果”和“完整检查结果”标上不同状态。

不要把语法树、类型信息和错误状态混在一起

最容易出现的误判是：AST 中明明有一个函数体，但 info.Types 没有对应表达式，于是把它认为是类型检查器失效。实际情况可能只是主动跳过了函数体。

可以按下面的顺序排查：

1. 确认分析目标是 AST 结构，还是 go/types 计算出的类型语义。
2. 检查 Config.IgnoreFuncBodies 是否为真，以及本次调用是否真的执行了 Config.Check。
3. 确认需要的 Info map 已初始化；没有 map 的结果类别不会被收集。
4. 将函数签名和函数体内表达式分开处理，不要用包级对象的存在性推断局部语义完整。
5. 记录 Check 返回的 error。官方说明中，存在错误时返回的包可能是不完整的。

func checkMode(fset *token.FileSet, files []*ast.File, deep bool) (*types.Package, *types.Info, error) {
    // 每种检查模式独立创建 Info，避免快速扫描的缺口污染深度分析。
    info := &types.Info{
        Defs:  make(map[*ast.Ident]types.Object),
        Uses:  make(map[*ast.Ident]types.Object),
    }
    if deep {
        // 深度模式才收集表达式类型和值。
        info.Types = make(map[ast.Expr]types.TypeAndValue)
    }
    conf := types.Config{
        // 只有不需要函数体语义时才跳过函数体。
        IgnoreFuncBodies: !deep,
    }
    pkg, err := conf.Check("sample", fset, files, info)
    return pkg, info, err
}

这段代码没有把错误吞掉，也没有把“快速模式的 map 为空”解释成失败。调用方可以根据 deep 决定是否读取 info.Types，让数据契约和检查模式保持一致。

按任务决定是否开启

如果目标是包级导出 API、声明索引、接口签名整理或快速建立依赖目录，开启 IgnoreFuncBodies 通常更合适。它把分析边界写进配置，减少不必要的函数体语义工作。

如果目标是发现局部变量引用、推断表达式类型、读取常量值、检查函数体内调用关系，应该关闭它，并为 Info 分配对应的 map。若只是为了语法结构统计，直接使用 AST 遍历通常比期待 go/types 结果更清晰。

最后记住这三个边界

第一，IgnoreFuncBodies 是检查范围开关，不是 AST 删除开关。第二，types.Info 只填充调用方提供的 map，开启或关闭函数体检查都不能替代按需初始化。第三，快速检查得到的包级结果可以服务索引，但不应被当成完整的函数体语义结果。

只要把“声明分析”和“函数体分析”拆成两个明确模式，go/types.Config.IgnoreFuncBodies 就能成为可控的性能与准确性取舍，而不是一个让结果莫名变空的隐藏开关。

相关问题

• IgnoreFuncBodies 为 true 时还能拿到函数签名吗？ 可以，函数声明和签名仍属于可检查的包级信息。
• 为什么 AST 里有函数体，Info.Types 却没有结果？ 可能是跳过了函数体，或没有初始化对应的 Info map。
• 只想做语法级统计还需要 types.Config 吗？ 不一定，AST 遍历已经能完成节点、名称和位置统计。