Go parser.ParseDir 怎样按文件名解析一个 Go 包目录

如果要扫描一个 Go 包目录、按文件名排除测试文件，并继续访问每个源码文件的 AST，可以使用 go/parser 的 ParseDir。它会读取目录中以 .go 结尾且通过筛选函数的文件，再按源码里的包名整理成 map[string]*ast.Package。

官方地址：https://pkg.go.dev/go/parser#ParseDir

最小可用做法是先创建非 nil 的 token.FileSet，再传入目录、文件过滤函数和解析模式；返回的 map 按包名分组，语法错误时仍可能拿到不完整的包结果，但必须同时处理返回的第一个错误。

准备 FileSet 与目录路径

ParseDir 的第一个参数是 *token.FileSet，不能传 nil。它用于保存 AST 中的文件位置，后续打印行号、列号或定位诊断信息时，都要依赖同一个 FileSet。第二个参数是本地目录路径，不是 Go module 名称。

下面先写一个最小函数，只负责打开一个目录并返回按包名组织的 AST。这里把 ParseComments 打开，便于后续工具读取文档注释；SkipObjectResolution 用来跳过已经不推荐依赖的标识符对象解析。

func parseDirectory(dir string) (map[string]*ast.Package, *token.FileSet, error) {
	// FileSet 负责保存每个 AST 文件的源码位置，不能传 nil。
	fset := token.NewFileSet()
	pkgs, err := parser.ParseDir(
		fset,
		dir,
		nil, // nil 表示不额外过滤，ParseDir 仍只考虑 .go 文件。
		parser.ParseComments|parser.SkipObjectResolution,
	)
	if err != nil {
		return pkgs, fset, fmt.Errorf("解析目录失败: %w", err)
	}
	return pkgs, fset, nil
}

这个返回签名保留了 pkgs，而不是遇到错误就直接返回 nil。原因是目录可读但某个文件有语法错误时，ParseDir 可能返回非 nil 的不完整 map；调用方可以根据场景选择继续做部分扫描，或者把错误提升为整个任务失败。

用 filter 按文件名选择源码

ParseDir 会自动跳过子目录和非 .go 文件。第三个参数 filter 用来进一步筛选 fs.FileInfo，例如排除 _test.go、临时生成文件或某个固定前缀。过滤函数只决定“这个文件是否参与解析”，不会改变 AST 中的文件名。

func parsePackageFiles(dir string) (map[string]*ast.Package, *token.FileSet, error) {
	// FileSet 统一记录本次扫描涉及的源码位置。
	fset := token.NewFileSet()
	pkgs, firstErr := parser.ParseDir(
		fset,
		dir,
		func(info fs.FileInfo) bool {
			// 只排除测试文件；扩展名和目录判断由 ParseDir 处理。
			return !strings.HasSuffix(info.Name(), "_test.go")
		},
		parser.ParseComments|parser.SkipObjectResolution,
	)
	if firstErr != nil {
		// 保留可能已经成功解析的包，交给上层决定是否继续。
		return pkgs, fset, fmt.Errorf("目录中存在无法解析的文件: %w", firstErr)
	}
	return pkgs, fset, nil
}

过滤条件应该表达业务边界，而不是重复实现 ParseDir 的内部规则。比如过滤函数不需要再次判断 info.IsDir()，因为 ParseDir 已经跳过目录；也不应把绝对路径拼接逻辑写进 filter，归档路径或输出路径应由后续阶段单独处理。

按包名读取 AST 文件集合

返回值的第一层 key 是源码声明的包名，value 是 *ast.Package。其中 Files 是从文件名到 *ast.File 的 map，同一个包的多个源码文件会被放在同一个集合里。文件名来自 ParseDir 拼接出的目录路径，因此遍历时不要假设 map 的顺序。

func summarizePackages(pkgs map[string]*ast.Package) []string {
	// 先把包名收集出来，避免依赖 map 的随机遍历顺序。
	names := make([]string, 0, len(pkgs))
	for name := range pkgs {
		names = append(names, name)
	}
	sort.Strings(names)

	result := make([]string, 0, len(names))
	for _, name := range names {
		pkg := pkgs[name]
		// Files 的长度表示该包本次实际收集到的源码文件数。
		result = append(result, fmt.Sprintf("%s: %d 个文件", name, len(pkg.Files)))
	}
	return result
}

这里的排序只用于生成稳定的摘要或日志，不代表 ParseDir 本身按字母顺序返回包。若工具需要继续分析函数、导入或注释，可以从 pkg.Files 取出每个 *ast.File，再交给 ast.Inspect 或其他 AST 处理函数。

区分目录错误与语法错误

错误处理是 ParseDir 最容易被忽略的部分。目录无法读取时，返回的是 nil map 和相应错误；如果目录读取成功，但某个 Go 文件解析失败，返回的 map 可能已经包含前面成功解析的包，同时 first 保存遇到的第一个错误。后续文件是否继续扫描，要根据工具目标判断。

func reportParseResult(pkgs map[string]*ast.Package, err error) error {
	if err != nil {
		if pkgs == nil {
			// nil map 通常表示目录本身无法读取，不能继续访问包结果。
			return fmt.Errorf("目录读取失败: %w", err)
		}
		// 非 nil map 仍可能有可用 AST，但结果必须标记为不完整。
		return fmt.Errorf("部分文件解析失败，已得到 %d 个包: %w", len(pkgs), err)
	}
	return nil
}

不要只写成 if err != nil { return err } 就丢掉 map，也不要在错误非 nil 时无条件遍历 map。更稳妥的策略是把“目录不可用”和“部分结果可用”区分开，再由调用方决定是中止、记录诊断，还是继续分析成功的 AST。

确认 build tags 的适用边界

ParseDir 适合轻量级源码扫描，例如统计声明、提取注释、生成简单索引或检查某些语法节点。但它已经被官方标记为 deprecated：它在把文件关联到包时不考虑 build tags，因此得到的包集合不一定等于某个目标平台真正参与构建的文件集合。

如果任务需要精确理解 build tags、模块依赖、目标平台或类型检查，应改用 golang.org/x/tools/go/packages。这不是把 ParseDir 的 filter 写得更复杂就能补上的能力，因为 build tags 影响的是文件选择和包关系，而不仅是文件名筛选。

func collectGoFiles(dir string) ([]string, error) {
	// 这个函数只示范目录级文件名筛选，不模拟 build tags 的构建语义。
	entries, err := os.ReadDir(dir)
	if err != nil {
		return nil, fmt.Errorf("读取目录失败: %w", err)
	}
	files := make([]string, 0, len(entries))
	for _, entry := range entries {
		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".go") {
			continue
		}
		files = append(files, filepath.Join(dir, entry.Name()))
	}
	sort.Strings(files) // 输出顺序稳定，便于生成索引或诊断信息。
	return files, nil
}

上面的辅助函数不能替代 ParseDir，它只是帮助理解两层边界：ParseDir 关注目录中的源码文件和 AST；构建系统还要考虑标签、平台、模块和依赖。把轻量扫描和构建语义分开，后续迁移到 go/packages 时会更容易。

一个可复用的目录扫描器

把前面的规则合并后，调用方可以得到稳定的包摘要，并保留失败时的部分结果。示例没有读取模块信息，也没有尝试执行源码，适合做静态索引或文档工具的第一层输入。

func scan(dir string) ([]string, error) {
	// 过滤测试文件，保留注释并跳过已弃用的对象解析。
	fset := token.NewFileSet()
	pkgs, err := parser.ParseDir(fset, dir, func(info fs.FileInfo) bool {
		return !strings.HasSuffix(info.Name(), "_test.go")
	}, parser.ParseComments|parser.SkipObjectResolution)
	if err != nil {
		if pkgs == nil {
			return nil, fmt.Errorf("扫描目录失败: %w", err)
		}
		return summarizePackages(pkgs), fmt.Errorf("扫描结果不完整: %w", err)
	}
	return summarizePackages(pkgs), nil
}

参数和结果速查

常见问题

ParseDir 会递归解析子目录吗？

不会。它只读取传入目录这一层，子目录会被跳过。如果要扫描整个源码树，需要先自行遍历目录，再对每个目标目录调用解析逻辑。

filter 能根据 build tags 选择文件吗？

不能把它当成完整的 build tags 解析器。filter 只能看到文件信息，ParseDir 也不根据目标平台建立精确的包文件关系；需要构建语义时使用 go/packages。

解析失败时应该丢弃已经得到的包吗？

取决于工具目标。目录扫描器可以保留非 nil map 并标记结果不完整；生成必须完整的代码索引时，则应把错误返回给上层并停止后续输出。

为什么遍历 pkgs 的顺序每次可能不同？

因为返回值和 ast.Package.Files 都是 map。要生成稳定日志、测试快照或索引文件，应先收集 key 再排序。