---
URL: "/zh-CN/blog/2026-09/Spring-Boot-Bom.html"
LLMS_URL: "/zh-CN/blog/2026-09/Spring-Boot-Bom.md"
lastUpdated: true
commentabled: true
recommended: true
title: "Spring Boot 保证版本一致性的核心机制"
description: "Spring Boot 保证版本一致性的核心机制"
date:

pageClass: "blog-page-class"
cover: "/covers/springboot.svg"
---

## 版本一致性问题的来源 ##

Maven 的传递依赖机制在带来便利的同时，引入了版本冲突的风险。一个项目可能通过不同的路径引入同一个库的不同版本，比如 `spring-boot-starter-web` 依赖了 Jackson 2.13.5，另一个业务模块直接引入了 Jackson 2.14.0，Maven 的依赖仲裁规则（最短路径优先、最先声明优先）会选择其中一个加载。如果加载的版本与 Spring Boot 预期的不一致，运行时可能出现 `NoSuchMethodError` 或 `NoClassDefFoundError`。

Spring Boot 针对这个问题构建了一套完整的版本管控体系，核心由三个层次组成：BOM（物料清单）锁定版本、Parent 继承传递锁定、依赖仲裁规则控制冲突。

## 核心机制一：BOM（物料清单） ##

BOM（Bill of Materials）是 Maven 中一种特殊的 POM 文件，它的作用不是引入依赖，而是统一声明依赖的版本号。

Spring Boot 的 BOM 是 spring-boot-dependencies。它的核心结构如下：

```xml
<project>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-dependencies</artifactId>
    <version>2.7.18</version>
    <packaging>pom</packaging>

    <properties>
        <spring.version>5.3.31</spring.version>
        <jackson.version>2.13.5</jackson.version>
        <tomcat.version>9.0.83</tomcat.version>
        <slf4j.version>1.7.36</slf4j.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-core</artifactId>
                <version>${spring.version}</version>
            </dependency>
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
                <version>${jackson.version}</version>
            </dependency>
            <!-- 数百个依赖版本锁定 -->
        </dependencies>
    </dependencyManagement>
</project>
```

这个 BOM 锁定了数百个常用库的版本号。它通过 `<properties>` 集中管理版本号变量，通过 `<dependencyManagement>` 锁定依赖版本，最终通过 BOM 文件下发版本定义。

在 Spring Boot 应用中，`spring-boot-starter-parent` 继承自 `spring-boot-dependencies`，因此所有官方 Starter 的依赖都通过这个 BOM 统一版本。由于它使用了 `dependencyManagement` 而非 `dependencies`，这只会影响版本的解析，不会强制引入依赖，保证了 BOM 只负责任何依赖的版本，实际引用由各模块声明。

## 核心机制二：Parent 继承与传递 ##

`spring-boot-starter-parent` 本身是 `spring-boot-dependencies` 的子 POM，它做了一件事情：继承 BOM 的 `dependencyManagement`，同时在 `pluginManagement` 中锁定插件版本。

```xml
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-dependencies</artifactId>
    <version>2.7.18</version>
</parent>
```

子项目继承 `spring-boot-starter-parent` 后，Maven 会向上递归解析父 POM 的 `dependencyManagement`。依赖版本继承的层级如下：

- `spring-boot-starter-parent` 是项目的直接父 POM
- `spring-boot-starter-parent` 的父 POM 是 `spring-boot-dependencies`
- `spring-boot-dependencies` 的 `dependencyManagement` 中锁定了所有版本

这就是为什么子项目的 `pom.xml` 中引入 Starter 不需要写版本号的原因——版本号从父 POM 链中继承得到。

如果你的项目已经继承了其他父 POM（如公司公共父 POM），无法再继承 `spring-boot-starter-parent`，可以通过 BOM 导入达到相同的效果：

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>2.7.18</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

`type=pom` 指定这是一个 BOM 文件，`scope=import` 告诉 Maven 把这个 BOM 的 `dependencyManagement` 内容导入到当前项目的 `dependencyManagement` 中。这个导入会生效，但不会继承 `spring-boot-starter-parent` 中的插件配置。

## 核心机制三：依赖仲裁规则 ##

Maven 有一套决定传递依赖最终版本的路由规则：

*最短路径优先*：A → C → D（2.0）和 A → D（1.5），路径短的 D 1.5 胜出，因为 A 直接依赖了 D，路径最短。这条规则使得在顶层 POM 中显式声明一个依赖，可以覆盖 BOM 锁定的版本。

*最先声明优先*：如果路径长度相同，先声明的依赖版本胜出。这解释了为什么 pom.xml 中 `<dependencies>` 的声明顺序会影响最终的版本仲裁结果。

Spring Boot 利用这条规则保证版本一致性：BOM 中所有的依赖版本都是经过兼容性测试的，子项目中通过 `dependencyManagement` 继承这些版本。如果项目中没有显式覆盖，Maven 沿最短路径找到 BOM 中的版本并加载。

## 版本属性集中管理 ##

在 spring-boot-dependencies 中，版本号通过 `<properties>` 集中定义：

```xml
<properties>
    <spring.version>5.3.31</spring.version>
    <jackson.version>2.13.5</jackson.version>
    <tomcat.version>9.0.83</tomcat.version>
</properties>
```

这种集中管理的好处是升级时只需要修改一处属性，所有依赖同步更新。子项目需要覆盖某个版本时，只需在子 POM 中重新定义属性：

```xml
<properties>
    <jackson.version>2.14.0</jackson.version>
</properties>
```

这会覆盖父 POM 中的 Jackson 版本，使项目中所有通过 BOM 管理的 Jackson 依赖都升级到 2.14.0。但升级时可能引入兼容性问题，这是覆盖 BOM 版本需要评估的风险。

## 版本一致性验证工具 ##

Spring Boot 提供了几个验证版本一致性的工具：

- `spring-boot-dependencies` BOM 本身通过 `maven-enforcer-plugin` 验证依赖版本是否冲突
- `spring-boot-maven-plugin` 的 `build-info` 目标可以生成 `build-info.properties` 记录所有依赖版本
- `spring-boot-starter-actuator` 的 `/actuator/env` 端点可以查看运行时的版本信息

在开发过程中，可以用 `mvn dependency:tree` 查看依赖树，确认最终选择的版本是否符合预期。

## 核心机制的局限 ##

这套版本管控体系主要管控的是 Spring Boot 官方 Starter 中的依赖。以下场景需要额外关注：

- 项目中引入了非 BOM 管理的第三方依赖，需要自己声明版本号
- 不同 BOM 之间可能存在版本冲突，引入多个 BOM 时版本仲裁规则依然适用
- 父 POM 中锁定的版本被覆盖时，需要人工验证兼容性

## 总结 ##

Spring Boot 的版本一致性由三个层次保障：

| 层次 | 机制 | 作用 |
| :--- | :--- | :--- |
| BOM | `spring-boot-dependencies` 锁定版本 | 定义所有依赖的版本基准 |
| Parent 继承 | `spring-boot-starter-parent` 传递 BOM | 将版本基准传递给所有子模块 |
| 依赖仲裁 | 最短路径优先、最先声明优先 | 控制多版本冲突时最终加载的版本 |


这套机制的核心是“集中定义、继承传递、自动仲裁”。Spring Boot 团队对锁定的版本组合完成了兼容性测试，开发者默认使用这些版本时不会出现因版本不匹配导致的运行时错误。当业务需要引入 BOM 未覆盖的依赖或升级版本时，需要自行评估兼容性风险。