架构设计
本页解释 Maven SDK Go 各部分如何协同工作,以及一次请求如何从你的代码 一路流向 mvn 进程再返回。下面每张图都由本页内嵌的 Mermaid 源码渲染而成。
系统上下文
在最上层,你的应用(或 AI 智能体)与一组职责单一的小模块交互。只有 command 与 installer 会触碰外部世界(mvn 进程、网络、文件系统);其余 都是纯 Go 代码,只对路径、XML 和字符串做处理。
蓝色模块是纯函数 / 无副作用的,易于单元测试。琥珀色模块 (command、installer)会执行 I/O,测试时用 mock 进程和 HTTP 测试 服务器覆盖。
典型的 AI 智能体调用
SDK 最常见的调用方是需要构建陌生项目的自动化智能体。整个会话贯穿四个模块, 而智能体无需硬编码任何 mvn 路径:
模块依赖图
内部依赖刻意保持很浅——没有循环依赖,叶子模块只依赖标准库。
| 模块 | 依赖 | 副作用 |
|---|---|---|
finder | command(版本检查) | 读取 PATH、M2_HOME、文件系统 |
command | 仅标准库 | 启动 mvn 进程 |
pom | encoding/xml | 无(纯函数) |
settings | encoding/xml | 无(纯函数) |
local_repository | command | 读取 ~/.m2 |
installer | finder、command | 网络、文件系统、环境变量 |
触点:谁触碰什么
只有两个模块会触及进程外部。搞清楚某个副作用归谁管,就知道测试时该 mock 什么:
Maven 定位(finder)
FindBestMaven 实现了一条优先级级联:项目自带的 Maven Wrapper 永远 优先于系统安装,因为 Wrapper 锁定了项目构建时所用的确切 Maven 版本。
命令执行流水线
command 模块把流式构建器转换为 *exec.Cmd,执行它,并把非零退出码映射为 结构化的 *MavenError(而非裸字符串)。
构建器的不可变性
便捷方法(Clean()、Install()……)不会修改接收者本身。每次调用都 返回一个追加了目标的全新构建器,因此一个已配置好的构建器可以被复用来执行 多条命令而互不干扰。
Maven 构建生命周期
便捷方法映射到 Maven 内置的三条生命周期。执行某个阶段会连带执行同一条 生命周期中它之前的所有阶段。
| SDK 方法 | 实际命令 | 典型用途 |
|---|---|---|
Install(mvn) | mvn clean install | 本地构建并安装到 ~/.m2 |
CleanPackage() | mvn clean package | 产出构件,不安装 |
CleanDeploy() | mvn clean deploy | 发布到远程仓库 |
Verify(mvn) | mvn verify | 运行集成测试与检查 |
多模块 reactor 构建
对于多模块项目,Maven 的 reactor 根据模块间依赖图计算构建顺序,再按该顺序 让每个模块依次执行所请求的阶段。WithProjects / WithAlsoMake(-pl / -am) 裁剪这张图;不指定时整个 reactor 都会运行:
-pl a,c -am("also-make")会重建 a、c 以及 a 的上游依赖——这样你就 不会拿着一个陈旧的 a 去发布 c。-amd("also-make-dependents")反之, 重建下游的消费方。
安装器:端到端流程
InstallWithOptions 具备幂等性且感知平台。它优先尝试成本最低的方案(已经 安装好的 Maven),再尝试原生包管理器,只有在万不得已时才下载二进制归档。
带镜像回退的下载
每个镜像会以指数退避重试若干次后再切换;校验和不匹配被视作一次失败下载, 同样触发切换到下一个镜像。
各平台环境变量配置
三种操作系统持久化 MAVEN_HOME 和扩展 PATH 的方式差异很大。Windows 最 棘手:setx PATH 会在 1024 字符处截断,因此安装器从注册表读取现有的用户 PATH 再安全地追加,若超长则降级为打印提示而不是破坏 PATH。
POM 对象模型
pom.ParseFile 把 pom.xml 反序列化为 Project 树。访问器方法 (GetGAV、GetDependencies……)提供空安全读取并带有合理默认值 (例如 packaging 默认为 jar)。
有效 POM 的组装
解析得到的 Project 是原始模型——即文件里字面写的内容。Maven 实际 构建的有效 POM,是把原始模型与父 POM、激活的 profile 以及全局/用户 settings.xml 合并的结果。SDK 把原始模型解析为结构体;合并本身由 mvn help:effective-pom 物化出来:
TIP
子 POM 中留空的字段(版本、scope、插件配置)会从父 POM 继承。正因如此, 解析模型里的 Dependency.Version 完全可以是 ""——见 POM 解析器参考。
本地仓库布局
local_repository 把一个 Maven 坐标(GAV)映射到它在 ~/.m2/repository 下的磁盘路径,与 Maven 自身的目录约定一致。
group id org.springframework 会变成嵌套目录 org/springframework——每个 点号都是一个路径分隔符。
CLI 命令面
cmd/mvn-skills 二进制是六个包之上的一层薄薄的 cobra 包装。每个子命令都用 同样的方式解析 mvn 可执行文件(通过 --executable 或 finder.FindBestMaven), 然后委托给对应包的函数——所以 CLI 只是 SDK 的又一个调用者,不是平行实现。
一次 CLI 调用如何流动
一次典型的 mvn-skills build 调用贯穿三层——flag 解析、可执行文件解析、 SDK 函数——而 SDK 函数本身又会落到 mvn 子进程:
每个子命令都是同样的形状:flags → 解析可执行文件(如需)→ 调一个 SDK 函数 → 打印。CLI 自身不加业务逻辑,这正是 SDK 始终是唯一事实源的原因。