过度设计的代价：从 Maven 版本幻觉到工程上的简单原则

过度设计的代价从 Maven 版本幻觉到工程上的简单原则前段时间我在梳理内部组件库的版本管理方式。一开始我想解决的问题很直接组件越来越多每个模块又有自己的版本号能不能把这些版本统一管理起来减少重复配置也让后续维护更规范沿着这个思路我把版本号集中放进 parent POM通过dependencyManagement管理内部组件依赖。子模块不再单独填写版本所有版本都从同一个地方获取。从配置上看这套方式确实更整齐。但当我继续推演组件的构建、发布和消费过程时一个问题逐渐暴露出来本地构建时使用的依赖版本未必就是消费者最终解析到的版本。如果子模块发布后的 POM 仍然需要依靠远程 parent POM 才能获得内部依赖版本那么只要两者没有同步更新组件自己的版本虽然升级了消费者拿到的底层依赖仍然可能停留在旧版本。版本号写的是 A实际运行的却可能是 B。我原本想通过统一管理减少维护成本结果却引入了一个新的前提子模块、parent POM 和私服中的发布状态必须始终保持一致。它在形式上更整齐却把复杂度藏进了发布流程。继续分析 A、B、C 三种方案后我才重新意识到一件事工程上的统一不是越多越好。如果统一管理没有消除复杂度只是把复杂度转移到更隐蔽的地方它反而可能把人引向错误的方向。目录我们为什么想统一管理版本看起来整齐的方案如何制造麻烦三种版本管理方案的真实取舍为什么我最终更倾向于方案 C这次问题真正让我反思的事我们为什么想统一管理版本我们的内部组件库基于 Java、Maven 和 Spring Boot包含核心工具库、HTTP 客户端、开放接口 SDK、SSO 组件、监控组件、日志组件以及多个 Starter。它们之间存在清晰的依赖关系开放接口 SDK └── HTTP 客户端 └── 核心工具库 SSO 组件 └── 核心工具库 监控、日志等组件 └── 核心工具库这些组件的更新频率并不相同。核心模块相对稳定部分边缘模块仍在快速迭代。如果所有模块使用同一个版本号一个小模块改动一次就可能带着一批没有变化的模块一起升级。所以我们最初采用了“独立版本 parent POM 集中管理”的方式每个组件拥有自己的版本号版本值集中定义在 parent POM 的properties中parent POM 通过dependencyManagement统一管理内部组件版本子模块声明内部依赖时不重复填写version。例如子模块只需要这样写dependencygroupIdcom.example/groupIdartifactIdcore-lib/artifactId/dependency版本由 parent POM 统一提供dependencyManagementdependenciesdependencygroupIdcom.example/groupIdartifactIdcore-lib/artifactIdversion${core-lib.version}/version/dependency/dependencies/dependencyManagement从开发视角看这套方案很合理版本定义只有一份子模块 POM 更简洁修改版本时不需要到处搜索替换仍然保留了各组件独立升级的能力。如果只看源码仓库它甚至显得很优雅。问题出现在“构建完成之后”。看起来整齐的方案如何制造麻烦Maven 构建使用的不是某一个孤立的pom.xml而是经过父子继承、属性解析和依赖管理后形成的有效模型。在本地多模块工程中子模块可以顺利从 parent POM 获得依赖版本所以编译和测试都可能正常通过。但消费者不会读取我们的整个源码仓库。它只会从私服获取发布后的组件、组件 POM以及解析该 POM 所需的其他模型。这意味着真正需要检查的不是我们源码里的版本配置是否正确而是消费者拿到的发布后 POM能否独立、准确地描述构建时使用的依赖如果发布后的子模块 POM 仍然需要依靠远程 parent POM 才能获得内部依赖版本那么子模块和 parent 就形成了一个必须同步发布的组合。假设核心工具库从0.1.0升级到了0.1.11. 本地修改 parent 中的版本属性 2. 本地重新构建 HTTP 客户端 3. HTTP 客户端构建时使用 core-lib 0.1.1 4. 只发布 HTTP 客户端没有同步发布对应的 parent 5. 消费者读取远程模型时仍得到 core-lib 0.1.0于是就出现了最让人困惑的情况生产出来的组件和消费者依据发布元数据重新解析出来的依赖关系不是同一个状态。这类问题难排查是因为每个局部看起来都没有错代码改了版本升了本地构建通过了新组件也发布了消费者引入的组件版本也是新的。真正出错的是这些状态之间没有一起前进。新增模块时尤其容易暴露新增组件后如果远程 parent POM 中还没有对应的依赖管理信息消费者可能无法正确解析依赖或者继续使用旧的版本关系。开发者会觉得“Jar 明明已经上传了为什么还是不能用”因为发布一个 Maven 组件从来不只是上传一个 Jar。POM 本身也是发布契约的一部分。依赖升级可能只在本地生效底层组件升级后本地 Reactor 构建会使用当前工作区中的新模型。消费者却只能依据私服中的发布模型解析依赖。如果两边的 parent 状态不同本地验证通过并不能证明消费者会得到同样的依赖树。集中管理还可能引入版本污染为了修复某个组件的依赖版本我们重新发布 parent POM。这个 parent 中却不只管理一个组件而是记录了整个组件库的版本矩阵。原本只想推进 A 组件的状态结果可能把 B、C、D 的新版本关系也一起暴露给消费者。我们原本想用一个中心统一控制所有版本最后却得到了一个需要谨慎维护、频繁覆盖、难以追溯的共享状态。统一管理没有消失它只是从“修改 POM”变成了“保证所有发布状态永远同步”。后者显然更难。三种版本管理方案的真实取舍发现问题后我重新比较了三种方案。它们都能工作但解决的是不同问题也会引入不同成本。方案 A继续集中管理加强发布约束第一种做法是不改变现有结构继续通过 parent POM 的dependencyManagement管理独立版本只要求发布时严格同步相关 parent。它的优势很明确每个组件仍然可以独立升级版本定义集中源码修改方便子模块 POM 保持简洁不需要大规模调整现有结构。但它的代价也没有消失发布流程仍然存在额外步骤自动化之外的人工操作容易遗漏发布结果依赖子模块和 parent 的状态一致同一个可覆盖的 SNAPSHOT parent 难以准确追溯新模块接入时必须同步更新并发布模型。这个方案不是不能用。只要发布流水线足够成熟能够自动计算影响范围、同步发布 parent并验证最终私服中的 POM它可以继续运行。问题是我们当前真正需要的是一套更简单的发布方式而不是再给已有流程增加更多规则和校验。方案 B所有模块使用统一版本第二种方案是所有模块共用一个${revision}。任何模块发生变化整个组件库统一升版。它最大的优势就是简单只有一个版本号parent 和子模块天然处于同一发布批次不需要维护复杂的内部版本矩阵消费者很容易判断一组组件是否来自同一次发布。如果项目中的模块总是一起修改、一起测试、一起发布这通常是一种很自然的选择。但我们的组件库并不是这种形态。在当时的模块中大部分组件已经相对稳定只有少数组件仍在高频变化。如果统一升版一次局部修改会让大量未变更组件产生新版本版本号不能直接反映单个组件是否变化消费者可能被迫进行不必要的升级CI 缓存和依赖下载受到额外影响局部发布变成整组发布。方案 B 用发布批次的一致性换掉了组件独立演进的能力。它比方案 A 更简单但并不符合我们当前的模块变化节奏。方案 C让发布 POM 明确记录内部依赖版本第三种方案最直接子模块声明内部依赖时明确写出所需版本。dependencygroupIdcom.example/groupIdartifactIdcore-lib/artifactIdversion0.1.1-SNAPSHOT/version/dependency这样做之后发布的组件 POM 自己就能说明我在构建和发布时声明依赖的是哪个版本。消费者不再必须依赖某个持续变化的 parent 状态才能知道这个组件希望使用哪个内部依赖版本。这里需要说明一个边界明确写出版本并不意味着消费者绝对不可能覆盖它。Maven 仍然存在依赖仲裁消费方也可以通过自己的dependencyManagement统一指定版本。方案 C 真正解决的是另一件事发布方不再把最基本的依赖版本信息藏在一个需要额外同步的共享状态里。它不是禁止消费者治理依赖而是先让每个发布物把自己的依赖契约说清楚。为什么我最终更倾向于方案 C单看代码方案 C 似乎不够“高级”。同一个版本号可能出现在多个 POM 中。底层组件升级后需要逐个修改真正需要新版本的依赖方。相比集中管理它存在一定重复。但换一个角度看这些重复并不是毫无意义的重复。它记录的是每个组件真实选择的依赖版本。假设core-lib从0.1.1升级到0.1.2只有某个 Starter 需要新功能那么只修改这个 Starter升级 core-lib 到 0.1.2 ↓ 修改确实需要新能力的 Starter ↓ 重新构建并发布这两个组件其他依赖core-lib、但不需要新功能的组件可以继续使用原来的声明不必被迫跟随升级。这种方式带来了几个我更看重的结果。发布物更自包含看到组件的 POM就能知道它声明了哪些直接依赖版本不需要继续追查当时远程 parent 究竟是什么状态。变更范围更符合业务事实谁需要新版本谁就修改自己的 POM 并重新发布。没有变化的组件不需要为了形式上的一致性制造新版本。排查路径更短出现问题时可以直接对照组件源码中的依赖版本私服中发布 POM 的依赖版本消费者最终解析出的依赖树。三个层次清晰可见而不是先猜测 parent 是否被正确发布。人工步骤更少它把“记得同步某个隐式状态”变成了“修改当前组件明确声明的依赖”。两者都需要维护但后者离变更发生的位置更近也更容易在代码评审中被发现。当然方案 C 不是 Maven 组件库的通用最佳实践。如果团队能够正确配置 Flatten Plugin让发布后的 POM 固化有效依赖信息或者维护一个有明确版本、不可覆盖、与发布批次严格绑定的 BOM也可以解决发布模型不自包含的问题。如果所有模块天然同版本发布方案 B 甚至可能比方案 C 更合适。我选择 C不是因为它在理论上最漂亮而是因为它最符合我们当时的几个现实条件模块更新频率不同希望保留独立版本发布流程不应该依赖容易遗漏的额外动作组件规模尚未大到手动维护直接依赖版本不可接受当前最重要的是让构建状态和发布契约更容易理解。它没有消灭所有维护成本只是把成本放到了更显式、更可检查的位置。对我来说这已经是很大的改进。这次问题真正让我反思的事回头看我们最初选择集中管理的理由完全成立。我们想减少重复、统一修改入口、让版本管理更规范。这些目标没有错。错的是我们太早把“统一”当成了答案。当系统中有十几个更新频率不同、发布节奏不同的组件时强行把它们的版本状态集中到一个 parent 中表面上减少了 POM 里的重复实际上增加了更多隐含约束parent 必须同步更新parent 必须同步发布子模块必须引用正确的 parentFlatten 配置必须符合发布目标私服中的模型必须和本地构建模型一致发布者必须理解这些机制并严格执行。我们省掉了几行version却换来了一套更难发现错误的协作协议。这不是说抽象、复用和统一管理没有价值。真正的问题是每增加一层抽象都应该证明它减少了系统的总体复杂度而不只是让局部代码看起来更整齐。判断一个工程方案也不能只看它是否“规范”还要继续追问它减少的是重复代码还是实际维护成本它把状态放到了更明确的位置还是更隐蔽的位置出错后普通开发者能否沿着直觉找到原因它依赖自动化保证还是依赖每个人永远不忘记某个步骤当模块和团队继续增长时这套约束会更稳定还是更脆弱有时候重复写几行版本号看起来不够优雅但每个组件都能把自己的依赖关系说清楚。有时候一个统一入口看起来很先进却要求多个发布物、多个环境和多个人始终保持同步。工程设计不是寻找形式上最漂亮的方案而是在当前约束下把真实复杂度降到最低。我们原本希望通过集中管理消除重复最后却引入了一个必须始终同步、又很容易被遗漏的隐式状态。相比形式上的统一我更愿意让每个 POM 明确写出自己的真实依赖。代码重复了一点但系统简单了很多。这就是我最终更倾向于方案 C 的原因。它可能不是最优雅的答案但它让依赖关系更明确让发布结果更可追溯也让后来的人少记一条“千万不要忘记”的规则。而在真实的软件工程中能少依赖一点人的记忆往往比少写几行配置更重要。如果你也维护过 Maven 多模块组件库可以检查一下消费者最终拿到的 POM是否真的记录了你构建时使用的依赖关系也欢迎在评论区聊聊你更倾向集中管理、统一版本还是让每个组件明确声明依赖。参考资料MavenIntroduction to the Dependency MechanismMavenPOM ReferenceFlatten Maven Pluginflatten:flatten