Go go/ast.MergePackageFiles 怎样合并包级 AST 文件

如果你已经通过 go/parser.ParseFile 得到同一个包的多个 *ast.File，又希望把它们看成一棵可遍历的文件级语法树，可以调用 go/ast.MergePackageFiles。它会把包注释、声明和文件注释收拢到一个 *ast.File 中，MergeMode 再决定是否过滤重复函数、无归属注释和重复导入。

先记住一个边界：MergePackageFiles 只做语法树层面的拼接与过滤，不负责类型检查，也不会把多个文件重新格式化成源码。

MergePackageFiles 解决的是哪一层问题

解析一个 Go 包时，每个源文件天然对应一个 *ast.File。但做文档索引、声明统计或简单源码分析时，逐文件遍历常常需要自己维护文件循环、注释收集和声明汇总。MergePackageFiles(pkg, mode) 的输入是一个 *ast.Package，输出是合并后的 *ast.File。

合并过程会按文件名排序后收集包注释、顶层声明和注释列表。输出仍然是一棵 AST；函数名、声明位置等节点信息不会因此变成类型信息。若你的目标是判断标识符的真实类型、定义和引用关系，应把 AST 交给 go/types，不要把合并结果当成类型检查结果。

三个 MergeMode 选项分别改变什么

当前 API 的模式位只有三个常用选项，建议按任务显式组合：

这些选项会改变合并结果的内容，不是排序开关。尤其是注释过滤：如果工具需要保留文件头说明、版权注释或孤立注释，就不要盲目打开 FilterUnassociatedComments。

一个可复用的合并示例

下面的示例把目录中的 Go 文件解析成 ast.Package，再合并并打印顶层声明数量。示例只展示 AST 流程，不代表执行了完整的 Go 构建。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
	"os"
	"path/filepath"
)

func main() {
	// 用命令行目录作为输入，避免把待分析源码写死在程序里。
	dir := "."
	if len(os.Args) > 1 {
		dir = os.Args[1]
	}

	set := token.NewFileSet()
	files := make(map[string]*ast.File)
	entries, err := os.ReadDir(dir)
	if err != nil {
		// 目录不可读时直接返回，避免继续合并不完整的包。
		panic(err)
	}
	for _, entry := range entries {
		if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" {
			continue
		}
		path := filepath.Join(dir, entry.Name())
		file, err := parser.ParseFile(set, path, nil, parser.ParseComments)
		if err != nil {
			// 单个文件解析失败时保留真实错误，不把坏文件伪装成空 AST。
			panic(err)
		}
		files[path] = file
	}

	// Package 只负责把同包文件组织起来，类型关系仍需 go/types 处理。
	pkg := &ast.Package{Name: "main", Files: files}
	mode := ast.FilterFuncDuplicates | ast.FilterImportDuplicates
	merged := ast.MergePackageFiles(pkg, mode)
	fmt.Printf("merged declarations: %d\\n", len(merged.Decls))
}

这里的关键不是把所有文件简单追加，而是先把它们放进 ast.Package.Files，再把过滤意图交给 MergeMode。如果保留文件头或孤立注释，把 FilterUnassociatedComments 从模式组合中移除即可。

弃用与兼容边界怎么处理

官方文档已经把 MergePackageFiles、ast.Package 和 MergeMode 标为 deprecated，并明确提示该函数规格不够清晰且存在无法修复的缺陷。因此它更适合维护已有的 AST 工具或做兼容性读取，不适合作为新类型分析器的长期核心接口。

• 只要任务是统计声明、收集注释或生成简单索引，可以先用上面的合并流程。
• 需要定义、引用、方法集和真实类型关系时，使用 go/types 的类型检查流程。
• 需要输出规范 Go 源码时，使用 go/format 或 go/printer，不要指望合并函数负责格式化。

最终可以把判断压缩成一句话：MergePackageFiles 解决“多个文件 AST 如何暂时汇总”，而不是解决“这个 Go 包在语义上是什么”。在新代码中把这条边界写进接口说明，后续迁移会更轻松。

相关问题

MergePackageFiles 会进行类型检查吗？

不会。它只处理 AST 节点和合并过滤，类型检查需要单独配置 go/types。

为什么合并后还要保留 token.FileSet？

AST 节点的位置仍然依赖解析时的文件集。后续打印、定位源码行或报告错误时，应继续使用同一个 token.FileSet。