title: Spring Boot 3.2.x 最佳兼容环境清单
uid: 20260815115210132
created: 2026-08-15 11:52
updated: 2026-08-15 11:52

tags: [项目, 实践, 清单]

Spring Boot 3.2.x 最佳兼容环境清单

Spring Boot 3.2.x 官方基线：

• 最低 JDK：JDK17，推荐 JDK17 LTS（17.0.12+），支持 JDK21；不支持JDK8/JDK11
• Maven 最低 3.8.7+，推荐 3.9.x
• Gradle 推荐 8.5+
• Spring Framework 6.2.x

原则：优先使用 Spring‑Boot‑Dependencies BOM 托管版本，不手动指定版本；只有BOM没有管理的组件才手动指定稳定兼容版本。
数据库中间件版本：MySQL8.0 / Redis6.x~7.x / MinIO 服务端>=2024

一、基础运行环境

父pom 引入BOM方式（多模块项目）

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

二、Spring Boot Starter 核心启动器

全部不写version，由BOM自动管理

<!-- web 核心 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- 数据库JDBC -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

<!-- 校验 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- redis  lettuce客户端 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- 测试 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- aop -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

三、中间件驱动 & ORM

1. MySQL驱动 mysql‑connector‑j

SpringBoot3.2.x BOM托管版本：8.3.0，适配JDK17/JDK21，不要用8.0.30及更早版本

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <!-- 不写version，BOM托管 -->
    <scope>runtime</scope>
</dependency>

2. MyBatis‑Spring‑Boot‑Starter

官方兼容：SpringBoot3.2.x → 3.0.3（mybatis‑spring‑boot‑starter）
注意：mybatis 3.x 是适配SpringBoot3，不要用2.x

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

3. Lombok

版本：1.18.34，适配JDK17、SpringBoot3，IDEA必须安装对应lombok插件

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.34</version>
    <scope>provided</scope>
</dependency>

4. MinIO SDK

SpringBoot3.2，minio sdk 8.5.9；注意：minio 8.x是新SDK，包名io.minio
BOM没有管理，需要手动指定version

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.5.9</version>
</dependency>

四、常用工具类 & JSON & 文档

1. Knife4j（OpenAPI3，替代swagger2）

SpringBoot3必须用knife4j 4.x，OpenAPI3规范；4.3.0稳定版
⚠️ 不要用knife4j 3.x，是SpringBoot2版本，会报错

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

2. Hutool 工具集

版本 6.0.0‑M22（hutool6适配JDK17+；hutool5兼容SpringBoot2，不要混用）
hutool6 模块按需引入，也可以全量hutool‑all

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>6.0.0-M22</version>
</dependency>

3. Fastjson2（注意：fastjson1已经停止维护，安全漏洞，必须用fastjson2）

fastjson2 版本 2.0.53，适配JDK17，jakarta包

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.53</version>
</dependency>
<!-- springboot json序列化适配器（可选，如果需要用fastjson2做http消息转换器） -->
<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-spring</artifactId>
    <version>2.0.53</version>
</dependency>

提示：SpringBoot默认使用jackson，如无强业务需求，优先jackson，不必引入fastjson。

五、其他高频可选依赖（生产常用）

1. PageHelper 分页（MyBatis分页）

SpringBoot3版本：2.1.0

<dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

2. Druid 连接池

druid springboot3 starter：1.2.24

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <version>1.2.24</version>
</dependency>

3. sa‑token 权限框架（可选）

sa‑token 适配SpringBoot3：1.37.0

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>1.37.0</version>
</dependency>

六、服务端中间件版本建议（服务部署环境，不是maven依赖）

七、重要避坑清单（SpringBoot3.2重点）

1. 包名变更 javax → jakarta

   • SpringBoot3 全部使用jakarta.*，所有老SpringBoot2组件不能直接升级，例如swagger2、hutool5、knife4j3、pagehelper1.x全部废弃不能用。
2. JDK必须17+，Maven>=3.8.7。
3. mysql驱动：groupId改为com.mysql，旧mysqlgroupId已经废弃。
4. fastjson 1.x 严禁使用，安全漏洞，必须fastjson2。
5. lombok版本不能过低，1.18.24以下会JDK17编译异常。
6. mybatis‑spring‑boot‑starter必须3.x，2.x只适配SpringBoot2。
7. 多模块项目，父pom通过spring‑boot‑dependencies import BOM，子模块尽量不写版本号，减少版本冲突。

八、完整父pom片段参考（多模块）

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.11</version>
        <relativePath/>
    </parent>

    <groupId>com.xxx</groupId>
    <artifactId>demo-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    <modules>
        <!--子模块-->
    </modules>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!--第三方组件版本 BOM未托管的-->
        <lombok.version>1.18.34</lombok.version>
        <mybatis.spring.boot.version>3.0.3</mybatis.spring.boot.version>
        <knife4j.version>4.3.0</knife4j.version>
        <hutool.version>6.0.0-M22</hutool.version>
        <fastjson2.version>2.0.53</fastjson2.version>
        <minio.version>8.5.9</minio.version>
        <pagehelper.version>2.1.0</pagehelper.version>
        <druid.version>1.2.24</druid.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- SpringBoot BOM，父是spring‑boot‑starter‑parent可以省略，import方式用于非继承父工程场景 -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>3.2.11</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- mybatis -->
            <dependency>
                <groupId>org.mybatis.spring.boot</groupId>
                <artifactId>mybatis-spring-boot-starter</artifactId>
                <version>${mybatis.spring.boot.version}</version>
            </dependency>

            <!-- lombok -->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
                <scope>provided</scope>
            </dependency>

            <!-- knife4j -->
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>${knife4j.version}</version>
            </dependency>

            <!-- hutool -->
            <dependency>
                <groupId>cn.hutool</groupId>
                <artifactId>hutool-all</artifactId>
                <version>${hutool.version}</version>
            </dependency>

            <!-- fastjson2 -->
            <dependency>
                <groupId>com.alibaba.fastjson2</groupId>
                <artifactId>fastjson2</artifactId>
                <version>${fastjson2.version}</version>
            </dependency>

            <!-- minio -->
            <dependency>
                <groupId>io.minio</groupId>
                <artifactId>minio</artifactId>
                <version>${minio.version}</version>
            </dependency>

            <!-- pagehelper -->
            <dependency>
                <groupId>com.github.pagehelper</groupId>
                <artifactId>pagehelper-spring-boot-starter</artifactId>
                <version>${pagehelper.version}</version>
            </dependency>

            <!-- druid -->
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>druid-spring-boot-3-starter</artifactId>
                <version>${druid.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

如果你需要，我可以再输出一份子模块pom示例，或者application.yml基础配置模板（mybatis、druid、redis、minio、knife4j）。