一套系统的 Maven 项目版本演进指南

在软件开发的世界里，我们每天都在与代码打交道。但除了代码本身，还有一个东西默默地记录着项目的生命轨迹，它就是——版本号。

一个混乱的版本号体系，就像一本没有页码和章节的乱书，会让团队协作、问题追溯和项目发布变得一团糟。你是否也曾遇到过这些场景？

• “生产环境用的是 my-app-final-final-v2.jar，这到底是哪个版本的代码？”
• “我依赖了同事的 common-utils 模块，怎么他一更新，我的项目就编译失败了？”
• “这次发布要修复一个紧急 Bug，我们应该基于哪个版本的分支来改？”

如果这些问题让你感同身受，那么恭喜你，这篇文章就是为你准备的。今天，我们将一起学习一套系统的、专业的 Maven 项目版本演进方法，让你的项目管理从此变得清晰、可控、有条不紊。

第一章：两个世界，两种状态 —— SNAPSHOT 与 RELEASE

在 Maven 的世界里，任何一个构件（artifact）都活在两个基本状态之一：开发快照（SNAPSHOT）或正式发布（RELEASE）。理解它们的区别，是版本管理的第一步。

我们可以用一个生动的比喻来理解：写书。

• SNAPSHOT (快照版) - “草稿”
  SNAPSHOT 版本代表一个项目正处于积极的开发阶段。它就像一位作家正在创作的草稿。

  • 它是可变的：作家每天都会修改草稿，增加新章节、修正错别字。同样，SNAPSHOT 版本可以被无限次地覆盖部署到仓库。你今天拉取的 1.2.0-SNAPSHOT 和明天拉取的，内容可能完全不同。
  • 它是不稳定的：草稿中的情节和人物随时可能调整。同样，SNAPSHOT 版本中的 API 和功能也可能随时改变，不承诺任何稳定性。
  • 它用于内部协作：草稿是作者和编辑之间沟通的媒介。同样，SNAPSHOT 版本是开发团队内部使用的，确保大家都能获取到最新的开发进展。

• RELEASE (正式版) - “出版物”
  RELEASE 版本则代表一个项目已经完成了一个稳定的里程碑。它就像一本已经正式出版的书。

  • 它是不可变的：一旦书籍出版，它的内容就永远固定了。同样，一个 RELEASE 版本（如 1.2.0）一旦发布到仓库，就绝对不能再被修改或覆盖。这是 Maven 的铁律，保证了构建的可重现性。
  • 它是稳定的：出版物承诺了内容的确定性。同样，RELEASE 版本承诺了其功能的稳定性和 API 的向后兼容性（遵循语义化版本的前提下）。
  • 它用于公开分发：书籍是卖给读者的。同样，RELEASE 版本是给生产环境、客户或其他稳定项目使用的。

特性	SNAPSHOT (草稿)	RELEASE (出版物)
本质	开发中、不稳定	稳定、已发布
可变性	可变（可重复部署）	不可变（神圣不可侵犯）
适用场景	团队内部开发、持续集成	生产发布、对外交付
命名	以 -SNAPSHOT 结尾 (e.g., 1.2.0-SNAPSHOT)	标准版本号 (e.g., 1.2.0)

第二章：版本的语言 —— 读懂语义化版本 (SemVer)

既然知道了版本有两种状态，那么 1.2.0 这种数字又该如何定义和演进呢？业界最佳实践是遵循**语义化版本（Semantic Versioning, SemVer）**规范。

它的格式是：主版本号(MAJOR).次版本号(MINOR).修订号(PATCH)

• MAJOR：当你做了不兼容的 API 修改。比如你删掉了一个被广泛使用的 public 方法，或者修改了方法签名。升级 MAJOR 版本号意味着使用者必须修改他们的代码才能适应新版。
• MINOR：当你做了向下兼容的功能性新增。比如你增加了一个新的 public 方法，或者为一个现有方法增加了新的可选参数。升级 MINOR 版本号意味着使用者可以无痛升级，并享用新功能。
• PATCH：当你做了向下兼容的问题修正。比如你修复了一个内部实现的 Bug，没有对 API 产生任何影响。升级 PATCH 版本号意味着使用者应该尽快升级，以获得更稳定的体验。

一个特别的规则：0.y.z
当主版本号为 0 时 (e.g., 0.1.0, 0.2.5)，代表项目处于初始开发阶段。在这个阶段，任何事情都可能改变，API 不被认为是稳定的。这给了你在 1.0.0 之前大刀阔斧进行重构和设计的自由。

第三章：项目的旅程 —— 从 0 到 1 的版本演进实战

现在，让我们把前两章的理论串联起来，模拟一个项目的完整生命周期。

阶段一：创世纪 (项目初始化)

你的团队开始了一个全新的项目 super-app。它的第一个版本号应该是什么？

正确答案：0.1.0-SNAPSHOT

• 0.：表明项目处于不稳定的初始开发阶段。
• .1.：代表我们正在开发第一个功能集。
• .0：修订号从 0 开始。
• -SNAPSHOT：明确告诉所有人：“我们刚开工，别急！”

阶段二：热火朝天的开发

团队在 develop 分支上，基于 0.1.0-SNAPSHOT 版本进行编码。CI/CD 服务器每次构建成功后，都会将最新的 super-app-0.1.0-SNAPSHOT.jar 推送到内部的 Snapshot 仓库。依赖此项目的其他团队，可以随时获取到最新的开发成果，无缝集成。

阶段三：准备发布第一个版本 (Milestone Release)

经过几周的努力，0.1.0 的功能全部完成，测试也通过了。团队决定发布第一个可用的内部版本。

这个过程，我们称之为 “Release Preparation” (发布准备)，它是一系列神圣的仪式：

1. 版本净化：将 pom.xml 中的版本号从 0.1.0-SNAPSHOT 修改为 0.1.0。
2. 锁定代码：在 Git 中，为这次提交打上一个永久的标签，如 v0.1.0。这个标签就像一个历史坐标，让你可以随时回到这个荣耀的时刻。
3. 终极构建：基于这个干净的版本号和标签，执行最后一次构建和测试，确保万无一失。

阶段四：正式发布

执行 Maven 的 deploy 命令，将版本号为 0.1.0 的构件发布到公司的 Release 仓库。从这一刻起，0.1.0 版本就“凝固”了，成为了历史上一个不可磨灭的、稳定的标记。

阶段五：开启新篇章

发布完成后，必须立刻做一件事：开启下一轮迭代。

立即将 pom.xml 中的版本号更新到下一个开发版本。如果下一个版本是增加新功能，那么版本号应该变为 0.2.0-SNAPSHOT。然后将这个改动提交到 develop 分支。

为什么要这么快？
这是为了防止任何新的代码被错误地提交到刚刚发布的 0.1.0 之上，保护 Release 版本的纯洁性。

从 0.5.0 到 1.0.0 的飞跃
项目持续迭代，发布了 0.2.0, 0.3.0… 直到某一天，你们在 0.5.0 版本时觉得：“这个产品已经非常成熟，API 稳定，可以正式推向市场了！”

这时，你就可以决定将下一个版本作为 1.0.0 发布。这标志着项目脱离了“初始开发阶段”，进入了“稳定承诺阶段”。你的发布流程将是：

1. 开发 1.0.0-SNAPSHOT。
2. 准备发布，版本变为 1.0.0，打上 v1.0.0 标签。
3. 发布 1.0.0。
4. 开启下一轮迭代，版本变为 1.1.0-SNAPSHOT (新增功能) 或 1.0.1-SNAPSHOT (修复 Bug)。

第四章：工具赋能 —— 让 maven-release-plugin 成为你的管家

手动执行上述所有步骤，不仅繁琐，而且极易出错。幸运的是，Maven 提供了强大的自动化武器：maven-release-plugin。

你只需要两条简单的命令：

1. mvn release:prepare
   它会自动帮你完成：检查 SNAPSHOT 依赖、移除 -SNAPSHOT 后缀、打 Git 标签、并将版本号更新到下一个 SNAPSHOT 版本。
2. mvn release:perform
   它会自动帮你完成：检出刚才打的标签、执行构建、并将最终的 RELEASE 构件部署到仓库。

使用这个插件，可以将整个发布流程标准化、自动化，把开发者从繁琐的重复劳动中解放出来。

结语

版本号不只是几个简单的数字，它是项目的历史、是团队的承诺、是协作的语言。建立一套清晰、规范的版本演进策略，带来的好处是巨大的：

• 清晰度：任何人看到版本号，都能理解其状态和变更范围。
• 可预测性：构建和依赖关系变得稳定可靠。
• 安全性：严格区分开发与发布，杜绝不稳定代码流入生产。
• 专业性：体现了团队的工程素养和对质量的追求。

希望这篇指南能帮助你和你的团队“驯服”版本这头猛兽，在软件开发的道路上走得更稳、更远。