Go list -m -json 怎样读取模块元数据

读取模块元数据可以使用 go list -m -json。无参数时查询主模块，追加 all 查询活动模块集合。自动化脚本应保留原模块路径与替换声明，并用 JSON 解码器读取多个对象，而不是按行拆分。

比如为报表服务生成依赖身份报告，重点是模块路径、选中版本和替换关系，不必把构建机器的绝对目录全部交付。下面的命令和程序是可保存的原创示例，不是本机运行记录。

先固定模块查询的工作环境

在目标模块目录执行查询。单模块任务可以明确关闭工作区；工作区任务则应保留真实环境，不能把两种视角的报告混用。

# 记录实际工具链和模块环境
go version
go env GOMOD GOWORK
# 只查看主模块
GOWORK=off go list -m -json
# 查看活动模块，限制模块文件自动修改
GOWORK=off go list -mod=readonly -m -json all

readonly 不是离线开关，也不承诺缓存不发生写入。依赖信息不足可能触发网络访问或失败。不要为读取清单顺手执行 go get、tidy；它们会改变依赖状态。生产任务应使用预先准备的依赖环境，并记录调用参数。

区分模块身份和本地替换位置

顶层 Path 和 Version 保留原模块身份；Replace 描述替换目标。替换存在时，Dir 若有值，指向替换源码位置。GoMod 是模块描述文件位置，不能用 Dir 拼接文件名来猜。Main 表示主模块，Indirect 表示间接依赖信息；GoVersion 不能代替实际工具链版本。

主模块或目录替换可能没有普通发布版本号，字段缺失不等于损坏。不要擅自补成 latest。图中把 Path、Version、Replace 放入“逻辑身份”，把 Dir、GoMod 放入“落盘信息”；Replace 与 Dir、Path 与 Version、Path 与 Replace、Dir 与 GoMod 的关系是理解报告的入口，不是执行步骤。

把多个 JSON 对象作为数据流读取

all 的输出不能假设有数组外壳。将下面程序保存为模块根目录的 module_report.go，循环解码到 EOF，再输出自己定义的报告数组。EOF 只在对象之间正常出现时算结束，截断对象不能当成成功。报告数组暂存在内存中，规模随模块数增长。

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "os"
)

type Module struct {
    Path string
    Version string
    Replace *Module
    Error *struct { Err string }
}

type Row struct {
    Path string
    Version string
    Replacement string
}

func report(in io.Reader, out io.Writer) error {
    dec := json.NewDecoder(in)
    rows := make([]Row, 0)
    for {
        var m Module
        err := dec.Decode(&m)
        if err == io.EOF { break } // 正常结束，不吞掉截断错误
        if err != nil { return fmt.Errorf("读取模块: %w", err) }
        if m.Error != nil { return fmt.Errorf("模块 %s: %s", m.Path, m.Error.Err) }
        if m.Path == "" { return fmt.Errorf("模块路径为空") }
        row := Row{Path:m.Path, Version:m.Version}
        if m.Replace != nil {
            row.Replacement = m.Replace.Path // 不覆盖原模块路径
            if m.Replace.Version != "" {
                row.Replacement += "@" + m.Replace.Version
            }
        }
        rows = append(rows, row)
    }
    if len(rows) == 0 { return fmt.Errorf("模块对象为空") }
    return json.NewEncoder(out).Encode(rows) // 统一输出一个数组
}

func main() {
    if err := report(os.Stdin, os.Stdout); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Decoder 接收对象流并解码为 Module，Row 只保存任务需要的字段。未知字段被忽略，缺省字符串保持为空。错误对象要单独处理；JSON 语法合法不代表模块查询本身成功。这里定义的 Row 并非 Go 官方完整模块结构。

在自动化中保留失败状态和最小报告

普通 shell 管道的退出码可能只反映最后一个命令，因此把采集与解析分开判断。以下脚本适用于 POSIX shell，在模块根目录执行。它仅把完整报告写到标准输出，由任务系统保存为独立产物，不覆盖项目文件。

# 仅处理本脚本创建的临时目录
set -eu
report_dir=$(mktemp -d)
trap 'rm -f "$report_dir/modules.json" "$report_dir/report.json"; rmdir "$report_dir"' EXIT
# 采集成功以后才允许解析
if ! GOWORK=off go list -mod=readonly -m -json all > "$report_dir/modules.json"; then
    echo "模块采集失败" >&2
    exit 1
fi
# 标准错误不混入 JSON 输入
if ! go run ./module_report.go  "$report_dir/report.json"; then
    echo "报告解析失败" >&2
    exit 1
fi
# 成功报告交给调用方归档
cat "$report_dir/report.json"

主模块中不应有另一个同名文件；示例工具用文件参数执行，不把项目其他 main 文件一起编译。Replace.Path 仍可能暴露本地目录或内部仓库名，外发前按接收方需求缩减；省略 Dir 不等于内容天然可以公开。

不默认加 -e 掩盖错误。如果特意用 -e 收集错误模块，消费者必须处理 Error。普通现状清单也不默认追加 -u 或 -versions：升级候选、历史版本属于额外查询，并非当前选中版本。

几个容易混淆的模块查询问题

为什么不带 -m 时字段不同？

默认查询对象是包，带 -m 才是模块。不要把包列表的嵌套模块信息误当完整模块清单。

all 是 go.mod 的逐行翻译吗？

不是，它反映当前环境的活动模块。查询声明文本和查询选择结果是不同任务，报告应写明自己的视角。

元数据能证明最终二进制依赖安全吗？

不能。它不是漏洞扫描、源码完整性证明或二进制构建信息。归档时同时记录项目、命令、工具链及工作区环境，避免清单失去上下文。

参考：Go 命令文档、Go 模块参考。