第三方库与Go版本匹配

概述

go-version

把当前 Go 项目的依赖降级到能被指定 Go 版本（TARGET_GO_VER）满足的最新已发布版本，循环执行 go mod tidy 直到不再出现"依赖版本超过 Go 版本限制"的报错。

前置条件

1. HTTP 服务 go-version 可达：https://go-version.xzsmtech.top（公开访问，无需鉴权，

无需任何本地配置）。不可达时提示用户检查网络后重试。

1. 本机已安装 Go 工具链。

参数

• 无参数：以当前目录 go.mod 中 go 指令的值作为 TARGET_GO_VER；

若当前目录没有 go.mod，或其中没有 go 指令，报错并终止。

• 一个参数：直接作为 TARGET_GO_VER。接受 1.22、1.22.3、go1.22.3 三种写法

（go 前缀剥离后再校验），剥离前缀后必须匹配 ^d+.d+(.d+)?$；不合法则报错并终止，不要带病进入循环。

流程

1. 按上述参数规则确定并归一化 TARGET_GO_VER。
2. 进入循环（最多 20 轮）：

a. 运行 GOTOOLCHAIN=local go mod tidy --go=<TARGET_GO_VER>。b. 成功 → 转到第 3 步。c. 失败 → 从报错中解析出所有形如module <模块路径> requires go >= <X.Y> 的依赖版本超限库（每轮全量收集）。d. 对每个超限库，请求GET https://go-version.xzsmtech.top/resolve_module_version?module_path=<模块路径>&go_version=<TARGET_GO_VER>（URL 中模块路径需编码；服务端只取最新已发布版本，无其他参数）：

• 响应含 status 字段：
  • ok：执行 GOTOOLCHAIN=local go get <模块路径>@<resolved_version>。
  • in_progress：单次扫描预算耗尽但进度已保存，用相同参数重新请求

继续扫描，最多重试 10 次，直到返回 ok 或 no_compatible_version。

• no_compatible_version：目标版本下无解，终止整个流程，

向用户报告该库及响应中的 minimum_go_required，建议提高目标 Go 版本后重试。

• 响应含 error 字段（模块不在公共代理/上游失败）：最多重试 2 次，仍失败则

终止整个流程并报告原始错误信息。e. 本轮所有超限库都处理完后，进入下一轮（回到步骤 a）。f. 已达 20 轮仍未成功：报告已完成哪些降级、当前还剩什么报错，然后终止。

1. tidy 成功后输出汇总（见「汇报格式」），流程结束。

汇报格式

• 每轮结束输出一行简报：第 N 轮 | <模块路径> → v<降级到的版本> | tidy 结果。
• 终止时输出汇总：
  • 总轮数与最终结果（成功 / 提前终止的原因）；
  • 全部变更清单：<模块路径>: <原版本> → <新版本>；
  • 确认 go.mod 的 go 指令已为 TARGET_GO_VER。

注意事项

• 所有 go 命令一律加 GOTOOLCHAIN=local 前缀，防止工具链自动下载掩盖

版本兼容性判定，保证报错形态稳定可解析。

• 统一用 go get <模块>@<版本> 降级（会同步更新 go.sum），不要手改 go.mod

的 require 行；每轮的 go mod tidy 会自动整理 indirect 注释等差异。

• 报错中若出现无法解析为超限错误的其他失败（如网络错误、认证失败、

代码编译错误），如实向用户报告并终止，不要盲目循环。

• 若一轮中某个库已成功降级、另一个库遇到终止性错误，汇总时需同时报告

已完成的变更与终止原因。