Go types.Check 怎样处理多文件包顺序

types.Config.Check 把传入的 []*ast.File 当成一个 Go 包来检查：只要这些文件属于同一个 package，声明就会放在同一个包级作用域里解析，不能靠调整切片顺序改变名称可见性。真正需要稳定处理的是 token.FileSet 里的源位置，因为诊断位置、包级对象的源顺序以及没有依赖关系时的初始化顺序都要依赖 token.Pos。

官方文档：https://pkg.go.dev/go/types#Config.Check

如果你的工具从“检查一个文件”扩展到“检查一个目录”，建议把流程固定成：筛选同包文件、稳定排列文件名、共用一个 FileSet 解析，再一次调用 Config.Check。下面按迁移清单拆开文件列表、源位置和 types.Info 的关系。

先把多文件当成一个包检查

单文件示例里，调用方通常只需要准备一个 ast.File。多文件场景不能对每个文件分别调用 Check，否则每次检查都会得到一个独立的包作用域，文件之间的类型、函数和变量也就无法互相解析。

Check 的输入契约可以先记成三点：

文件传入顺序不是 Go 语言中“先声明才能使用”的开关。包内的声明会一起参与解析；但文件必须是同一个包名，混入另一个 package 的文件会产生包名不匹配错误。目录筛选、构建标签和测试包的选择属于上游加载策略，不能交给一段简单的 sort.Strings 自动解决。

用同一个 FileSet 解析多文件

如果只想让普通类型检查稳定工作，最重要的不是把 files 切片排序到某个“神奇顺序”，而是从一开始就让所有文件共用同一个 token.FileSet，并让文件名遍历顺序可复现。下面的接入骨架假设调用方已经选出了同一个 package 的 Go 文件，没有在这里展开构建标签规则。

package checker

import (
    "go/ast"
    "go/parser"
    "go/token"
    "go/types"
    "go/importer"
    "os"
    "path/filepath"
    "sort"
    "strings"
)

// parsePackageFiles 为同一 package 建立共享的 FileSet 和 AST 文件集合。
func parsePackageFiles(dir string) (*token.FileSet, []*ast.File, error) {
    entries, err := os.ReadDir(dir)
    if err != nil {
        return nil, nil, err
    }

    names := make([]string, 0, len(entries))
    for _, entry := range entries {
        // 这里只收集普通 Go 文件；测试包和构建标签应由上游策略先筛选。
        if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") {
            continue
        }
        names = append(names, entry.Name())
    }
    // 文件系统返回顺序不应直接决定工具的输出顺序。
    sort.Strings(names)

    fset := token.NewFileSet()
    files := make([]*ast.File, 0, len(names))
    for _, name := range names {
        path := filepath.Join(dir, name)
        // 所有文件都注册到同一个 FileSet，位置才能放在同一坐标系里。
        file, err := parser.ParseFile(fset, path, nil, parser.ParseComments)
        if err != nil {
            return nil, nil, err
        }
        files = append(files, file)
    }
    return fset, files, nil
}

// checkPackage 把整组 AST 当成一个 package 交给 go/types。
func checkPackage(fset *token.FileSet, files []*ast.File) (*types.Package, *types.Info, error) {
    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{
        // 标准库导入器负责解析示例中引用的已安装标准包。
        Importer: importer.Default(),
    }
    pkg, err := conf.Check("example.local/sample", fset, files, info)
    return pkg, info, err
}

这里的 files 顺序主要影响它们在 FileSet 中建立位置的先后；它不会把第二个文件变成“后声明文件”。只要所有 AST 来自同一个 FileSet，fset.Position(id.Pos()) 才能把 Defs 和 Uses 中的标识符还原到正确的文件、行和列。

配置 Info 和错误回调

Config.Check 会返回包对象和第一个错误；当传入非空 Info 时，它还会填充其中已经初始化的非空映射。静态分析工具通常至少需要 Defs、Uses 和 Types，否则只能判断“检查是否失败”，却无法把 AST 节点关联到对象或类型。

func inspectPackage(fset *token.FileSet, files []*ast.File) (*types.Package, *types.Info, []error) {
    info := &types.Info{
        Defs:  make(map[*ast.Ident]types.Object),
        Uses:  make(map[*ast.Ident]types.Object),
        Types: make(map[ast.Expr]types.TypeAndValue),
    }
    var reported []error
    conf := types.Config{
        // Error 回调用于收集检查过程中的错误；Check 仍会返回第一个错误。
        Error: func(err error) {
            reported = append(reported, err)
        },
        Importer: importer.Default(),
    }
    pkg, firstErr := conf.Check("example.local/sample", fset, files, info)
    if firstErr != nil {
        // 把首个错误纳入统一结果，避免调用方只看回调而漏掉失败状态。
        reported = append([]error{firstErr}, reported...)
    }
    return pkg, info, reported
}

如果检查失败，返回的 Package 可能是不完整的。文章或工具链应该先处理错误，再决定是否读取包级对象；不要因为 Info.Defs 里已经有部分结果，就把不完整包当成成功结果继续生成代码。

为什么还要关心文件排列

“顺序不影响包级语义”和“顺序完全不重要”不是一回事。go/types 会使用对象的 token.Pos 进行源位置相关的确定性处理，而 token.Pos 的坐标来自 FileSet 中登记文件的布局。于是，目录遍历每次返回不同顺序时，工具的诊断排序、对象遍历顺序或展示出来的源位置可能出现漂移。

这也是为什么推荐在解析前对文件名做一次稳定排序：它不是为了让跨文件声明“按顺序生效”，而是为了给位置分配和后续展示建立可复现的基线。若你的上游已经按照编译配置决定了文件集合，就不要在这里擅自加入或删除文件。

把顺序问题落到 InitOrder 和诊断

包级变量初始化顺序不是按照文件名简单拼接出来的。首先要满足初始化依赖；对于没有依赖关系的对象，类型检查器会使用源位置来获得确定结果。对应信息会写入 types.Info.InitOrder，每项描述一组左值和初始化表达式。

因此可以用下面的判断拆开排查：

1. 初始化结果不对：先检查变量之间是否存在依赖或循环，不要先调整文件名。
2. 诊断位置漂移：检查是否复用了同一个 FileSet，以及文件是否以稳定顺序加入其中。
3. 跨文件对象找不到：确认文件确实属于同一个 package，且没有被上游构建条件过滤掉。
4. 重复检查结果互相污染：不要把上一次检查的 Info、Package 或 AST 文件混到下一次独立检查中。

func printInitOrder(pkg *types.Package, info *types.Info, fset *token.FileSet) {
    // InitOrder 只描述包级变量初始化表达式，不是普通函数调用顺序。
    for _, init := range info.InitOrder {
        for _, variable := range init.Lhs {
            pos := fset.Position(variable.Pos())
            // 用源文件位置输出变量，便于比较不同输入批次的稳定性。
            println(pkg.Name(), pos.Filename, pos.Line, variable.Name())
        }
    }
}

上面的输出函数只是在读取信息；它没有重新计算初始化规则。真正的顺序由语言初始化依赖决定，FileSet 只负责让“源位置”有一致解释，不能用它绕过循环依赖或修复错误的包加载。

从单文件检查迁移到多文件包的清单

• 文件集合：只传入同一个 package 的文件，并把测试包、构建标签和生成文件的选择放在明确的上游阶段。
• 位置坐标：整个文件集合共用一个 token.FileSet，不要为每个文件单独创建。
• 稳定输入：目录遍历结果先按文件名或上游定义的确定规则排列，再解析到 FileSet。
• 结果读取：按需初始化 Info 的映射；检查失败时先处理错误，再使用不完整的包对象。
• 增量接口：如果需要多次加入文件，可以使用 types.NewChecker 和 Checker.Files，但仍要保持同一包、同一位置体系，并明确每次调用的生命周期。

结论：文件顺序影响位置，不替换包语义

一句话总结：types.Config.Check 会把同包的多个 ast.File 一起检查，文件切片顺序不会决定声明能否互相引用；但所有文件共用的 token.FileSet 会决定源位置，进而影响诊断和源顺序相关的可复现输出。工程上应稳定选择文件集合、稳定加入 FileSet、一次性检查整包，再根据 Package 的完整性处理结果。

相关问题

多文件必须按字母顺序传给 Check 吗？

不是。字母顺序只是容易实现的确定性规则。更重要的是文件集合正确、共享同一个 FileSet，并且上游选择逻辑可复现。

每个文件单独建一个 FileSet 可以吗？

不建议。跨文件的 AST 位置会落在不同坐标体系里，之后用一个 FileSet 解读位置就会失去一致性；多文件包应共用同一个 FileSet。

Check 返回错误后还能读 Info 吗？

可能仍有部分信息，但包会被标记为不完整。是否继续读取取决于工具的容错目标；生成代码或做可靠索引时，应先明确处理错误，不要把部分结果当成完整语义。