Go mod edit -json 怎样读取 go.mod 的结构化内容

如果脚本需要知道模块名、直接依赖、替换规则或撤回范围，先不要用正则去拆 go.mod 的文本。更稳妥的入口是 go mod edit -json：它把单个 go.mod 表示成结构化 JSON，方便脚本或 Go 工具按字段读取。

官方地址：https://go.dev/ref/mod#go-mod-edit

把任务限定为“读取一个 go.mod 的声明结构”，就用 go mod edit -json；如果要研究整个构建可见的模块集合，再换成 go list -m -json all。两者不要混为一个输入。

先把 go.mod 当成结构化资产

这类工具通常要保护的是模块声明本身：模块路径、Go 版本、require、replace、exclude 和 retract。风险不在于 JSON 难读，而在于把一份声明文件误当成完整依赖图，或者用字符串匹配漏掉重复块、间接依赖标记和替换关系。

官方文档明确说明，go mod edit 只读取一个 go.mod，不会替你查找其他模块；它适合工具和脚本读取或修改文件。完整模块集合属于另一层数据，应由 go list -m -json all 提供。

用 -json 输出指定文件

默认情况下，命令读取主模块的 go.mod；需要处理另一个文件时，把文件名放在编辑选项之后。下面的命令只输出 JSON，不改写原文件：

# 读取当前模块的 go.mod，输出结构化 JSON
go mod edit -json

# 读取指定的模块文件，仍然只打印结果
go mod edit -json tools.mod

如果把输出交给下游脚本，建议把 stdout 当作唯一数据源，stderr 单独保留给错误日志。不要把命令输出再拼接回 go.mod，也不要因为看到 Require 就推断所有传递依赖都已列出。

示例结果可以抽象成下面的 JSON 结构。它是字段说明，不是要求在严格 JSON 中添加注释：

{
  "Module": {"Path": "example.com/service"},
  "Go": "1.27",
  "Require": [{"Path": "example.com/lib", "Version": "v1.2.3", "Indirect": false}],
  "Replace": [],
  "Exclude": [],
  "Retract": []
}

按字段消费，而不是按文本猜测

脚本侧可以只提取需要审计的字段。例如只想列出模块路径和替换关系时，先让 jq 处理 JSON，再把结果写入审计记录：

# 只选择模块路径和 replace 列表，避免把整份文件混进日志
go mod edit -json | jq '{module: .Module.Path, replace: .Replace}'

# 明确指定目标文件，便于批量处理多个模块
go mod edit -json tools.mod | jq -r '.Require[]? | [.Path, .Version, (.Indirect // false)] | @tsv'

这里的 []? 允许没有 require 条目时输出为空，而不是把“没有依赖”误报成解析失败。Indirect 只描述当前 go.mod 中的声明标记，不代表工具已经完成整个构建图分析。

如果要在 Go 程序中消费，给 JSON 定义一个窄结构即可。字段名要对齐官方 JSON 表示，解码失败必须返回，不要静默使用空结构继续执行：

package main

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

type Module struct {
    Path    string `json:"Path"`
    Version string `json:"Version"`
}

type Require struct {
    Path     string `json:"Path"`
    Version  string `json:"Version"`
    Indirect bool   `json:"Indirect"`
}

type GoMod struct {
    Module  Module    `json:"Module"`
    Go      string    `json:"Go"`
    Require []Require `json:"Require"`
    Replace []any     `json:"Replace"`
}

func readGoModJSON() (GoMod, error) {
    // 让 go 工具读取单个 go.mod，避免手写文本解析规则。
    cmd := exec.Command("go", "mod", "edit", "-json")
    output, err := cmd.Output()
    if err != nil {
        return GoMod{}, fmt.Errorf("读取 go.mod 失败: %w", err)
    }
    var mod GoMod
    // JSON 是结构化输入；解码失败时停止，不能继续写错误审计记录。
    if err := json.Unmarshal(output, &mod); err != nil {
        return GoMod{}, fmt.Errorf("解析 go.mod JSON 失败: %w", err)
    }
    return mod, nil
}

func main() {
    mod, err := readGoModJSON()
    if err != nil {
        fmt.Println(err)
        return
    }
    // 只输出本次工具真正需要的资产字段。
    fmt.Printf("%s %s requires=%d\n", mod.Module.Path, mod.Go, len(mod.Require))
}

示例把 Replace 保留为通用数组，是为了突出读取边界；正式工具可以按实际版本定义更精确的替换结构。若需要完整模块集合，不要继续扩张这个结构体，而应单独调用 go list -m -json all 并建立另一种输入模型。

把输入控制和审计记录分开

从安全角度看，最容易出错的是把外部路径、未确认的模块文件和完整依赖图混在同一条处理链里。一个小工具至少应明确三件事：

图2展示的是静态消费关系：JSON 文档可以进入 jq 或 Go 结构体，随后输出审计记录；这不表示命令、解析和写日志之间已经在本机运行过。

发布前的读取清单

• 标题任务是否只是读取一个 go.mod，而不是分析完整模块图。
• 命令失败时是否保留错误并停止后续写入。
• 没有 Require、Replace、Exclude 或 Retract 时，是否按空数组处理。
• 审计记录是否保存模块路径、目标文件和关键字段，而不是保存一段难以解析的原始文本。
• 需要完整构建模块集合时，是否明确切换到 go list -m -json all。

相关问题

go mod edit -json 会修改 go.mod 吗？

单独使用 -json 时，作用是以 JSON 形式打印最终内容，不应把它当作写回操作。把修改选项和输出选项混用前，应先确认工具的输入文件和输出目的。

为什么不用正则直接解析 go.mod？

go.mod 是有结构的声明文件，文本布局和重复块会让正则规则不断膨胀。若目标是读取字段，优先消费官方 JSON 表示；若目标是编辑语法树，再考虑专门的模块文件解析库。

怎么读取全部依赖模块？

不要从 go mod edit -json 的 Require 列表推断完整依赖图。按任务边界改用 go list -m -json all，并让下游模型明确它处理的是模块集合。