Go list -json 怎么区分测试文件和普通源文件

我第一次用 `go list -json` 给代码生成器收集源文件时，最容易犯的错是把所有以 `_test.go` 结尾的文件都当成同一种测试文件。实际应该先看包边界：普通源文件放在 `GoFiles`，与被测代码使用同一个 package 名的测试文件放在 `TestGoFiles`，使用外部测试包名的文件放在 `XTestGoFiles`。

官方文档：https://go.dev/cmd/go/#hdr-List_packages_or_modules

先把三个字段放进同一张对照表

Go 官方的 package JSON 结构把源文件分组列出。`GoFiles` 是普通的 `.go` 源文件，但会排除 `CgoFiles`、`TestGoFiles` 和 `XTestGoFiles`；两个测试字段都只表示包目录中的测试源文件，区别在于测试文件属于当前包还是外部测试包。

这里的“普通”不是按文件名简单筛选出来的结果，而是 `go list` 根据包加载规则整理出的字段。我的经验是，先相信字段语义，再决定工具是否需要合并数组；不要先扫描目录再猜 package 关系。

用包名判断同包测试和外部包测试

假设目录里有下面三类文件：

service.go                 // 普通源文件，通常声明 package demo
service_test.go            // 同包测试，声明 package demo
service_external_test.go   // 外部测试，声明 package demo_test

执行 `go list -json .` 时，前两个测试文件虽然都以 `_test.go` 结尾，但不会进入同一个数组。`service_test.go` 属于 `TestGoFiles`，`service_external_test.go` 属于 `XTestGoFiles`。判断标准是测试文件的 package 声明，而不是文件名里有没有 “external”。

go list -json . | jq '{ImportPath, GoFiles, TestGoFiles, XTestGoFiles}'
# 只保留本文讨论的四个字段，方便快速查看包文件分组

如果环境没有 `jq`，也可以让 `go list` 直接输出模板字段。只是当工具需要稳定消费结构化结果时，我更倾向保留 `-json`，由程序读取数组，避免依赖命令行文本格式。

为不同工具选择最小字段集合

真实项目里，我通常先问“这个工具要处理哪一类源文件”，再选字段，而不是无条件把三个数组拼成一个列表：

• 源码索引或代码生成器通常先取 `GoFiles`，避免把测试辅助类型当成生产代码。
• 只生成同包测试报告时取 `TestGoFiles`；如果要覆盖黑盒测试，再单独加入 `XTestGoFiles`。
• 测试统计工具可以分别保留两个测试数组，这样报告里能区分白盒测试和外部包测试。

如果必须合并，建议在内存模型中保留来源字段，而不是直接把字符串数组拼平：

package main

import "fmt"

type PackageFiles struct {
    GoFiles      []string
    TestGoFiles  []string
    XTestGoFiles []string
}

func printGroups(files PackageFiles) {
    // 分组打印，保留测试来源，后续生成报告时还能区分白盒与黑盒测试。
    for _, name := range files.GoFiles {
        fmt.Println("source:", name)
    }
    for _, name := range files.TestGoFiles {
        fmt.Println("same-package-test:", name)
    }
    for _, name := range files.XTestGoFiles {
        fmt.Println("external-test:", name)
    }
}

上面的结构体只展示消费端模型，不负责执行 `go list`。实际解析 JSON 时，字段名与 Go 官方文档保持一致即可；如果某个数组为空，应把它理解成当前包没有该类文件，而不是字段含义发生了变化。

命令选项和容易混淆的边界

`-json` 让 package 数据以 JSON 输出，也可以指定必需字段名；默认情况下文件名是相对于包目录的路径。对本文场景，`go list -json .` 已经足够。不要因为看到 `CompiledGoFiles` 就把它当成 `GoFiles` 的同义词：加入 `-compiled` 后，编译器实际接收的文件集合可能包含生成文件。

同样，`CgoFiles` 代表导入 `C` 的源文件；它被官方结构单独列出。本文也不讨论 `-deps`、`-test` 产生的依赖或测试二进制信息，因为它们会改变问题范围。我要做源码收集时，会先固定命令选项，再决定是否扩展字段，避免同一次扫描混入不同语义。

常见问题

两个测试文件都以 _test.go 结尾，为什么会进入不同字段？

因为 `TestGoFiles` 与 `XTestGoFiles` 的区别是包归属：前者与被测包使用同一个 package 名，后者使用以 `_test` 结尾的外部测试包名。

GoFiles 会包含所有能编译的 Go 文件吗？

不一定。`GoFiles` 是普通源文件字段，Cgo、测试和外部测试文件都有单独字段；加入 `-compiled` 后应关注 `CompiledGoFiles` 的语义。

可以把 TestGoFiles 和 XTestGoFiles 直接合并吗？

如果工具只关心“全部测试文件”，可以合并；但建议先保留来源标签。白盒测试和外部包测试的可见性边界不同，后续做报告或代码生成时仍可能需要区分。