企业官网建设流程全解析

08-微服务多模块版本管理：服务独立迭代、依赖版本兼容方案

前言

单体应用时代，版本管理简单粗暴——整个项目一个版本号，一荣俱荣一损俱损。到了微服务架构，画风变成了：用户服务 v1.3.0、设备网关 v2.1.0、支付服务 v1.0.2，每个服务独立迭代、独立发版，但服务之间又要互相调用。

怎么管理多个模块各自的版本号？服务 A 升级了接口，服务 B 怎么知道要不要跟着改？依赖升级了，如何确保不把其他服务搞崩？

本文围绕 Spring Cloud 微服务多模块项目，从 Maven 多模块版本管理、服务间 API 兼容、依赖升级回归测试三个维度讲清楚。

一、Spring Cloud 多模块独立版本管理

1.1 项目结构

典型的智慧农业 SaaS 微服务项目结构：

alspd-cloud/ ├── pom.xml # 父 POM（统一依赖版本管理） ├── alspd-common/ # 公共模块（工具类、DTO、常量） │ └── pom.xml ├── alspd-gateway/ # API 网关 │ └── pom.xml ├── alspd-user-service/ # 用户服务 │ └── pom.xml ├── alspd-device-service/ # 设备服务 │ └── pom.xml ├── alspd-ai-service/ # AI 服务（YOLO 推理） │ └── pom.xml └── alspd-pay-service/ # 支付服务 └── pom.xml

1.2 父 POM 统一依赖版本管理

父 POM 的核心职责是统一管理依赖版本，子模块只引用不指定版本号：

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.0</version></parent><groupId>com.alspd</groupId><artifactId>alspd-cloud</artifactId><version>1.0.0</version><!-- 父项目版本号 --><packaging>pom</packaging><modules><module>alspd-common</module><module>alspd-gateway</module><module>alspd-user-service</module><module>alspd-device-service</module><module>alspd-ai-service</module><module>alspd-pay-service</module></modules><properties><java.version>17</java.version><spring-cloud.version>2023.0.0</spring-cloud.version><mybatis-plus.version>3.5.5</mybatis-plus.version><hutool.version>5.8.25</hutool.version></properties><dependencyManagement><dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><version>${spring-cloud.version}</version><type>pom</type><scope>import</scope></dependency><dependency><groupId>com.alspd</groupId><artifactId>alspd-common</artifactId><version>${project.version}</version></dependency></dependencies></dependencyManagement>

关键点：

• dependencyManagement只声明版本，不实际引入依赖
• 子模块引用时不需要写<version>，自动继承父 POM 的版本
• 公共模块alspd-common的版本用${project.version}引用，和父项目保持一致

1.3 子模块 POM 示例

<parent><groupId>com.alspd</groupId><artifactId>alspd-cloud</artifactId><version>1.0.0</version></parent><artifactId>alspd-device-service</artifactId><dependencies><!-- 引用公共模块，不需要写 version --><dependency><groupId>com.alspd</groupId><artifactId>alspd-common</artifactId></dependency><!-- Spring Cloud 其他依赖同理 --><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-netflix-eureka-client</artifactId></dependency></dependencies>

二、服务独立迭代与版本号策略

2.1 共享版本 vs 独立版本

小团队起步用共享版本，等服务数量超过 5 个、迭代节奏出现明显差异时，切换到独立版本。

2.2 独立版本的 Maven 配置

独立版本管理的关键是让公共模块的版本和服务版本解耦：

<!-- alspd-device-service/pom.xml --><parent><groupId>com.alspd</groupId><artifactId>alspd-cloud</artifactId><version>1.0.0</version><!-- 父 POM 版本 --></parent><artifactId>alspd-device-service</artifactId><version>2.1.0</version><!-- 服务自己的版本号，覆盖父版本 --><dependencies><!-- 引用公共模块时显式指定版本 --><dependency><groupId>com.alspd</groupId><artifactId>alspd-common</artifactId><version>1.2.0</version><!-- common 模块独立版本 --></dependency></dependencies>

2.3 版本号流转示意

alspd-common: 1.2.0 （公共模块，变更频率低） alspd-gateway: 1.0.3 （网关，偶尔迭代） alspd-user-service: 1.3.0 （用户服务，迭代频繁） alspd-device-service: 2.1.0 （设备服务，大版本迭代） alspd-ai-service: 0.9.2 （AI服务，还在开发期） alspd-pay-service: 1.0.0 （支付服务，刚上线）

每个服务独立打 Tag：

gittag device-service-v2.1.0gitpush origin device-service-v2.1.0

三、服务间 API 版本兼容策略

3.1 问题场景

设备服务alspd-device-service提供了查询设备列表的接口，用户服务需要调用它来做权限校验。现在设备服务要重构这个接口的返回格式——用户服务怎么办？

3.2 API 版本化策略

策略一：URL 路径版本（推荐）

GET /api/v1/device/list # 老版本接口 GET /api/v2/device/list # 新版本接口

新老接口共存，调用方按自己的节奏迁移。等所有调用方都迁移到 v2 后，再下线 v1。

策略二：Header 版本

GET /api/device/list X-API-Version: 2

URL 不变，通过请求头区分版本。好处是 URL 干净，坏处是不如路径版本直观，调试不友好。

策略三：Service 层版本隔离

在公共模块alspd-common中定义 DTO 和接口契约，通过包名隔离版本：

com.alspd.common.api.v1.DeviceDTO com.alspd.common.api.v2.DeviceDTO

调用方按需引用对应版本的 DTO。

3.3 兼容性保证规则

3.4 过渡期管理

不兼容的接口变更不能一刀切，标准流程：

1. 发 v2 新接口，同时保留 v1
2. v1 接口标记 @Deprecated，在响应头加Sunset头告知弃用时间
3. 通知所有调用方迁移，给出迁移文档和过渡期（通常 2-3 个迭代）
4. 监控 v1 调用量，归零后下线

四、依赖升级与回归测试流程

4.1 依赖升级的三条原则

1. 不跨大版本同时升级多个依赖：Spring Boot 从 2.x 升 3.x 和 MyBatis-Plus 升级不要放一起，出了问题分不清是谁的锅
2. 先在非关键服务上验证：拿一个边缘服务试水，没问题再推广到核心服务
3. 每次升级都有回滚预案：保留旧版本 Tag，出问题随时切回去

4.2 依赖升级流程

第一步：评估 ├── 查看 Release Notes，确认不兼容变更 ├── 评估影响范围（哪些服务用了这个依赖） └── 评估工作量 第二步：分支升级 ├── 新建 upgrade/mybatis-plus-3.5.5 分支 ├── 修改父 POM 版本号 ├── mvn clean install -U 强制更新依赖 └── 解决编译错误 第三步：回归测试 ├── 单元测试全量跑 ├── 集成测试（接口契约测试） ├── 人工冒烟（关键业务流程） └── 性能对比（防止版本升级引入性能退化） 第四步：合并发布 ├── Code Review ├── 合并到开发分支 ├── 灰度发布 └── 全量发布

4.3 Maven 依赖版本冲突排查

微服务多模块项目中，依赖冲突是最常见的坑。用以下命令排查：

# 查看依赖树mvn dependency:tree-Dincludes=com.alspd:alspd-common# 查看冲突的依赖mvn dependency:tree-Dverbose# 检查是否有版本冲突mvn enforcer:enforce-Drules=dependencyConvergence

典型冲突场景：设备服务引用了alspd-common:1.2.0，同时通过其他依赖间接引入了alspd-common:1.0.0。Maven 会按"最近优先"原则选择版本，但可能引入不兼容的类。

解决方案：在子模块 POM 中显式指定版本，强制覆盖间接依赖。

<dependency><groupId>com.alspd</groupId><artifactId>alspd-common</artifactId><version>1.2.0</version></dependency>

4.4 自动化回归测试

用 Maven Surefire 插件跑单元测试：

<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><configuration><testFailureIgnore>false</testFailureIgnore></configuration></plugin>

CI 流水线中的回归测试配置：

# 完整构建+测试mvn clean verify# 只跑测试mvntest# 跑指定服务的测试mvntest-plalspd-device-service

五、版本号协同矩阵

当多服务独立迭代时，维护一张"兼容矩阵"非常有必要：

这张矩阵让团队随时知道：哪个版本的服务能和哪个版本的服务对话，升级依赖时有据可查。

总结

微服务的版本管理本质上是在独立迭代和协同兼容之间找平衡。模块能独立走是基础，但走的时候不把别人带沟里才是关键。版本号、API 版本、依赖管理、回归测试，四条腿走路，缺一条都容易翻车。