SpringBoot3.3.5全栈升级与框架适配总结（技术分享版）

：2026年04月11日

适配环境：Spring Boot 3.3.5 + JDK 17 + MySQL 8.0.12 + Redis 6.2.6

一、升级背景与必要性

（一）项目基础信息

本项目属于 Java Spring Boot + Python AI 全栈项目。项目包含风险预测、权限管理、数据上传、故障报修、数据可视化等核心能力，面向医疗场景提供轻量化筛查工具。

架构：标准分层com.cucn.springboot

• controller / service / mapper / config / entity
• 运行端口：9090
• 数据库：MySQL 8.0.12
• 缓存：Redis 6.2.6
• 文件存储：files/、upload/
• AI 模块：.h5 模型 + .pkl 标准化器

本项目属于Java Spring Boot + Python AI全栈项目。项目核心功能涵盖疾病风险预测、多角色用户权限管理、诊疗数据上传与解析、运维故障报修、数据可视化报表展示等，致力于为医疗场景提供便捷、高效的疾病风险筛查工具。

项目采用标准分层架构，包结构为com.cucn.springboot，包含controller（控制层）、service（业务层）、mapper（数据访问层）、config（配置层）、entity（实体层）等核心模块；运行端口固定为9090，数据库采用MySQL 8.0.12（库名：dongfang），搭配Redis 6.2.6实现缓存优化，采用本地文件存储（files/、upload/目录）处理上传的CSV数据集与模型文件；AI模块基于Python语言开发，依托.h5模型文件、.pkl标准化器/编码器，实现CSV数据集的糖尿病风险预测功能。

（二）升级必要性

• Spring Boot 2.x 停止官方维护，存在安全漏洞
• Jakarta EE 全面替代 Java EE，javax包彻底废弃
• 旧框架启动报错、依赖冲突、接口文档失效
• 提升长期可维护性与开发效率

1. 框架生命周期考量：旧版本采用的Spring Boot 2.x系列已正式停止官方维护，存在未修复的安全漏洞与兼容性隐患，无法满足项目长期可维护、高稳定性的要求。

2. 技术规范适配要求：Jakarta EE已全面替代传统Java EE规范，旧框架中依赖的javax包已被官方废弃，若不升级，将导致项目无法适配现代Java开发标准，且可能出现核心类找不到、接口调用失败等问题。

3. 核心功能稳定保障：项目核心的AI预测模块、文件上传下载、数据库交互等功能，在旧框架环境下已出现启动报错、功能异常等隐患，升级框架是解决此类问题、保障功能正常运行的关键。

4. 开发与维护效率优化：旧框架存在依赖冲突、接口文档失效、编译报错等问题，占用大量开发与排查时间，升级后可实现依赖结构清晰化、开发流程规范化，提升后续迭代与维护效率。

二、核心升级内容

（一）基础环境升级

本次升级围绕Spring Boot 3.3.5生态适配展开，对项目基础运行环境进行全面升级，确保各组件版本兼容、运行稳定，具体升级明细如下表所示：

组件名称	旧版本	升级后版本	适配说明
Spring Boot	2.x	3.3.5	官方LTS稳定版，强制要求JDK 17及以上版本，适配Jakarta EE规范
JDK	8	17	Spring Boot 3系列最低兼容版本，长期支持，无安全漏洞，性能更优
Maven	3.6+	3.8+	适配Spring Boot 3依赖加载规则，解决旧版本依赖下载慢、冲突排查难问题
MySQL驱动	mysql-connector-java	mysql-connector-j	Spring Boot 3官方推荐驱动，适配MySQL 8.0+版本，提升数据库连接稳定性
MyBatis Plus	3.5.8	3.5.9（Spring Boot 3专属）	修复旧版本与Spring Boot 3.3.5不兼容的Bean定义冲突BUG，优化分页插件性能

（二）框架与依赖调整

结合Spring Boot 3.3.5的规范要求，对项目依赖进行全面梳理，移除不兼容依赖、补充必要依赖、优化依赖结构，确保依赖无冲突、无冗余，具体调整如下：

1. MyBatis Plus专属适配：将旧版本的mybatis-plus-boot-starter替换为Spring Boot 3专属的mybatis-plus-spring-boot3-starter:3.5.9，新增mybatis-plus-jsqlparser:3.5.9依赖（分页插件必需，用于SQL解析），彻底移除原生mybatis-spring-boot-starter依赖，避免出现依赖冲突。

2. 接口文档迁移：旧版本采用的springfox-swagger2、knife4j依赖不兼容Jakarta EE规范，无法在Spring Boot 3环境下正常运行，故全部移除；新增springdoc-openapi-starter-webmvc-ui:2.2.0依赖，适配OpenAPI 3标准，实现接口文档自动生成、在线调试功能。

3. Jakarta EE基础包补充：为满足Spring Boot 3底层运行要求，补充jakarta.servlet-api、jakarta.annotation-api:2.1.1依赖，确保项目符合Jakarta EE 9+规范，解决核心类找不到的问题。

4. 兼容依赖保留：保留项目原有稳定依赖，包括Spring Boot Web、Redis、JWT（0.11.5+版本，适配Jakarta EE）、Hutool工具库、EasyExcel等，确保业务功能不受影响；Python AI模块相关依赖无侵入式兼容，无需修改任何代码即可正常运行。

• MP 替换为mybatis-plus-spring-boot3-starter
• Swagger → SpringDoc OpenAPI 3
• 补充jakarta基础包
• 保留兼容依赖：Web、Redis、JWT、Hutool、EasyExcel

（三）代码与配置优化

为适配Spring Boot 3.3.5框架规范，解决升级过程中的代码报错问题，对项目代码与配置进行统一优化，确保代码规范、配置合理，具体优化内容如下：

1. 包名全局替换：由于Jakarta EE规范替代Java EE，对项目中所有涉及javax包的代码进行全局替换，将javax.servlet替换为jakarta.servlet、javax.validation替换为jakarta.validation，同时清理所有Swagger2遗留注解（如@ApiModel、@ApiModelProperty），避免注解冲突。

2. Mapper注入统一规范：在项目启动类上添加@MapperScan("com.cucn.springboot.mapper")注解，统一扫描数据访问层接口，移除所有Mapper接口上零散的@Mapper注解，避免出现重复注入导致的Bean定义异常（如diabetesRecordMapper注入失败）。

3. 分页插件配置修正：完善MyBatis Plus分页插件配置，显式指定数据库类型为MySQL，确保分页SQL自动拼接LIMIT语句，解决分页功能失效问题，具体配置代码如下：

MyBatis Plus 分页插件配置（高亮优化）

/**
 * MyBatis Plus 分页配置（SpringBoot3专用）
 */
@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 指定MySQL方言
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

@Configuration public class MybatisPlusConfig { /** * 分页插件配置，适配MySQL数据库 */ @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); return interceptor; } }

4. Maven编译配置修正：在pom.xml文件中强制指定Java编译版本为17，解决Maven编译时出现的“不支持发行版本23”报错，确保编译过程顺利，具体配置如下：

Maven 编译版本指定（JDK17 强制指定）

<properties>
    <!-- SpringBoot3 必须指定JDK17编译 -->
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <maven.compiler.release>17</maven.compiler.release>
</properties>

<properties> <java.version>17</java.version> <maven.compiler.source>17</maven.compiler.source> <maven.compiler.target>17</maven.compiler.target> <maven.compiler.release>17</maven.compiler.release> </properties>

三、实战问题排查与解决

本次升级过程中，遇到了一系列框架适配、依赖冲突、编译报错等问题，通过逐一排查、针对性解决，最终实现项目正常启动与运行。现将核心问题、原因及解决方案整理如下，为后续类似升级提供参考：

报错类型	核心报错信息	问题原因	解决方案
类找不到异常	javax.servlet.http.HttpServletRequest not present	旧Java EE的javax包已被Jakarta EE废弃，Spring Boot 3不支持	全局替换项目中所有javax包为jakarta包，补充Jakarta EE基础依赖
Bean定义异常	Invalid value type for attribute 'factoryBeanObjectType': java.lang.String	项目使用了非 Spring Boot 3 专用的 mybatis-plus-boot-starter，导致 Bean 定义类型冲突。	升级MyBatis Plus为Spring Boot 3专属版本3.5.9，替换对应依赖
分页插件报错	找不到符号：类PaginationInnerInterceptor	MyBatis Plus 3.5.9拆分了模块，分页插件依赖jsqlparser解析器，未单独引入	新增mybatis-plus-jsqlparser:3.5.9依赖，完善分页插件配置
编译版本错误	Fatal error compiling: 错误: 不支持发行版本 23	Maven编译版本配置为23，与本地安装的JDK 17不匹配，且Spring Boot 3不支持JDK 23	在pom.xml中强制指定编译版本为JDK 17，同步调整IDEA项目JDK配置
接口文档失效	Swagger启动失败，无法访问接口文档页面	旧版Springfox Swagger不兼容Jakarta EE与Spring Boot 3	移除旧Swagger依赖，替换为SpringDoc OpenAPI 3，适配新版框架

注：所有问题均已彻底解决，解决方案经过实际验证，可直接应用于同类Spring Boot 3升级场景。

四、升级验证结果

升级完成后，对项目进行全维度验证，涵盖编译、启动、功能、兼容性等方面，确保项目运行稳定，具体验证结果如下：

（一）编译与启动指标

1. Maven编译：项目共76个源码文件，全部编译成功，无报错、无警告，编译过程流畅，无依赖冲突；

2. 项目启动：在Windows环境下，项目可在15秒内完成启动，较旧版本（22秒）启动速度提升约32%，启动日志无异常；

3. 运行状态：项目启动后，端口9090正常监听，控制台可正常打印Spring Boot 3.3.5、MyBatis Plus 3.5.9版本信息，核心Bean加载成功；

4. 依赖状态：所有依赖加载正常，无冗余、无冲突，Maven构建稳定，可重复编译、启动。

• 源码 76 个文件 → 全量编译成功
• 启动耗时：15 秒（原 22 秒 → 提升 32%）
• 端口 9090 正常监听
• 依赖无冲突、无冗余

（二）核心功能全量验证

对项目所有核心功能进行全量测试，确保升级后功能无异常、运行稳定，具体验证结果如下表所示：

功能模块	验证状态	详细验证结果
用户登录/权限管理	验证通过	管理员、普通用户、运维人员三角色登录正常，权限分配合理，无越权访问问题
数据库CRUD操作	验证通过	MySQL数据库连接稳定，数据新增、查询、修改、删除操作正常，事务机制生效
MyBatis Plus分页	验证通过	分页插件正常工作，可自动拼接LIMIT SQL，分页参数设置有效，分页结果准确
AI糖尿病预测	验证通过	Python脚本、.h5模型文件、.pkl标准化器调用正常，CSV数据集导入预测结果准确
文件上传/下载	验证通过	本地files、upload目录读写权限正常，CSV文件、模型文件上传、下载功能无异常
CSV数据集处理	验证通过	训练集、测试集导入正常，数据解析无误，可正常用于AI模型训练与预测
接口文档	验证通过	访问http://localhost:9090/swagger-ui/index.html可正常打开接口文档，支持在线调试
Redis缓存	验证通过	Redis配置加载正常，缓存读写、失效机制正常，有效提升项目响应速度
运维报修/消息	验证通过	运维报修流程完整，消息通知正常，无逻辑异常，可满足日常运维需求

（三）兼容性验证

对项目运行环境进行多维度兼容性测试，确保项目在不同场景下均可正常运行，具体验证结果如下：

1. JDK兼容性：完全兼容JDK 17，运行无异常，不支持JDK 8及以下版本（符合Spring Boot 3要求）；

2. 操作系统兼容性：在Windows 10/11操作系统下正常运行，无环境适配问题；

3. 数据库兼容性：兼容MySQL 8.0.12及以上版本，数据交互无异常；

4. AI模块兼容性：Python AI模块无侵入式适配，无需修改任何Python代码，可正常调用。

五、升级价值与提升

本次全栈升级不仅解决了旧框架存在的各类问题，还显著提升了项目的技术规范性、稳定性与开发效率，具体价值与提升如下：

• 技术规范：全面适配 Jakarta EE 9+
• 稳定性：消除 5 项启动 / 编译级报错
• 安全性：修复 SB2.x 官方漏洞
• 效率：启动提速 32%，接口文档自动生成
• 竞争力：前后端 + AI 完整栈，无技术债务

（一）技术规范提升

项目全面适配Jakarta EE 9+开发规范，彻底摒弃废弃的javax包，代码结构更规范、更符合现代Java开发标准；依赖结构经过梳理优化，无冲突、无冗余，Maven构建流程稳定，便于后续团队协作开发与二次迭代。

（二）稳定性与安全性提升

消除了Spring Boot 2.x已知的安全漏洞，解决了5项启动、编译级核心报错，项目运行稳定性大幅提升；框架生态完整，依赖版本统一，减少了因版本兼容问题导致的功能异常，保障项目长期稳定运行。

（三）技术竞争力提升

采用Spring Boot 3.3.5官方最新稳定框架，技术选型先进、规范，项目具备完整的前后端+AI能力，无技术债务，可满足实际生产与开发需求，提升项目的技术实用性与可扩展性。

（四）开发效率提升

SpringDoc OpenAPI接口文档自动生成，无需手动编写，调试更便捷；依赖版本统一，减少了依赖冲突排查时间；项目启动速度提升32%，开发迭代效率显著提高，为后续功能优化、bug修复节省了大量时间。

六、后续维护建议

为确保项目长期稳定运行、满足后续迭代需求，结合项目实际情况，提出以下后续维护建议：

• 定期升级小版本，不盲目升大版本
• AI 模型文件（.h5/.pkl）加入.gitignore
• 生产环境建议使用云存储 OSS
• 长期使用 JDK17，不追新过高版本
• 代码生成器注意：mp-generator 3.5.9 与 SB3 存在兼容风险
• 定期清理冗余代码，规范注释

1. 依赖维护：定期关注Spring Boot、MyBatis Plus、SpringDoc等核心依赖的版本更新，优先升级小版本（修复bug、提升性能），避免盲目升级大版本，防止出现兼容性问题。

2. AI模块管理：AI模型文件（.h5、.pkl）体积较大，且无需参与代码版本控制，建议按.gitignore规则配置，不提交至Git仓库，避免占用仓库空间、影响代码提交速度。

3. 文件存储优化：当前项目采用本地文件存储，适合开发场景；若后续部署至生产环境，建议将files/目录替换为云存储服务（如阿里云OSS），提升文件存储安全性与可访问性。

4. JDK版本管理：长期使用JDK 17，不盲目升级至JDK 21、23等非长期支持版本，确保项目运行稳定性，避免因JDK版本过高导致的兼容性问题。

5. 代码维护：定期梳理项目代码，优化代码结构，删除冗余代码；规范注释编写，确保代码可读性，便于后续团队维护与代码讲解。

6. 代码生成器兼容提醒：mybatis-plus-generator:3.5.9 与 Spring Boot 3 存在不完全兼容（依赖 velocity 1.7），虽本次启动未触发该问题，但后续使用代码生成器时需重点关注，避免出现兼容性报错。

七、总结

本次升级以Spring Boot 3.3.5为核心，完成环境升级、依赖替换、代码迁移、问题修复，成功解决包名迁移、依赖冲突、Bean 异常、编译错误、文档失效五大类问题。

项目实现编译成功、启动无报错、功能全覆盖、AI 正常运行，技术栈规范、稳定、可长期维护，可为同类 Spring Boot 3 升级项目提供完整参考方案。

本次糖尿病智能预测系统全栈升级，以Spring Boot 3.3.5生态适配为核心目标，完成了基础环境升级、依赖调整、代码与配置优化，成功解决了包名迁移、依赖冲突、Bean定义异常、编译版本错误、接口文档失效等5项核心问题。

升级后，项目实现了Maven编译成功、启动无报错、核心功能全覆盖、AI预测模块正常运行的目标，技术规范性、稳定性、开发效率均得到显著提升，完全满足实际开发与长期使用需求。

本次升级不仅解决了旧框架的各类隐患，还为项目后续的功能迭代、性能优化奠定了坚实的技术基础，可为同类Spring Boot 3升级项目提供参考与借鉴。