ccdi/docs/plans/backend/2026-04-17-tongweb-integration-implementation.md

2026-04-17 TongWeb 接入实施记录

1. 改动目标

• 按 TongWeb 接入指南将后端默认内嵌容器从 Tomcat 切换为 TongWeb
• 保持当前 Spring Boot 3.5.8 工程结构不变，按 Jakarta 体系接入 TongWeb 3.x Starter
• 将 TongWeb license 随 ruoyi-admin 产物一起打包，并补齐可回归测试

2. 实施内容

2.1 Maven 依赖与仓库配置

涉及文件：

• pom.xml
• ruoyi-admin/pom.xml

实施内容：

• 在根 pom.xml 增加 tongweb.version=7.0.E.7
• 在根 pom.xml 增加 TongWeb Maven 仓库 https://mvn.elitescloud.com/nexus/repository/maven-releases/
• 在根 pom.xml 的 dependencyManagement 中声明 com.tongweb.springboot:tongweb-spring-boot-starter-3.x
• 在 ruoyi-admin/pom.xml 中对 ruoyi-framework 传递进来的 spring-boot-starter-tomcat 做排除
• 在 ruoyi-admin/pom.xml 中引入 tongweb-spring-boot-starter-3.x
• 在 ruoyi-admin/pom.xml 中显式保留 src/main/resources 资源打包规则，确保 .dat 文件进入产物

说明：

• 指南中的 tongweb-spring-boot-starter-2.x 仅适用于 Spring Boot 2.x
• 当前仓库为 Spring Boot 3.5.8，因此本次按 TongWeb 3.x Starter 接入，避免 Jakarta/Servlet 版本不兼容

2.2 TongWeb 基础配置与 license 资源

涉及文件：

• ruoyi-admin/src/main/resources/application.yml
• ruoyi-admin/src/main/resources/Tongweb_license.dat

实施内容：

• 在基础配置 application.yml 中新增 server.tongweb.license.path=classpath:Tongweb_license.dat
• 将 TongWeb license 以 Tongweb_license.dat 固定名称放入 ruoyi-admin/src/main/resources/
• 保留现有环境文件中的 server.tomcat.* 配置，先不做额外收缩，后续仅在 TongWeb 启动日志明确报冲突时再按最小范围调整

2.3 回归测试补齐

涉及文件：

• ruoyi-admin/src/test/java/com/ruoyi/config/TongWebIntegrationConfigurationTest.java

实施内容：

• 新增 classpath 资源测试，校验 Tongweb_license.dat 能从测试类路径读取
• 新增基础配置测试，校验 application.yml 中存在 server.tongweb.license.path
• 测试目标是防止后续重构时误删 TongWeb 配置或 license 资源

3. 验证项

建议执行以下命令：

mvn -pl ruoyi-admin -am test -Dtest=TongWebIntegrationConfigurationTest,LogbackConfigurationTest
mvn -pl ruoyi-admin -am package -DskipTests
mvn -pl ruoyi-admin -am dependency:tree "-Dincludes=com.tongweb.springboot:*,com.tongweb:*,org.apache.tomcat.embed:*"
jar tf ruoyi-admin/target/ruoyi-admin.jar | rg 'Tongweb_license.dat|tongweb'

验证重点：

• TongWeb 依赖能够正常解析
• spring-boot-starter-tomcat 不再作为 ruoyi-admin 主依赖链出现
• Tongweb_license.dat 已进入打包产物
• TongWeb 相关 jar 已进入 BOOT-INF/lib/

4. 结论

• 本次接入保持现有工程结构与启动入口不变，仅替换内嵌 Servlet 容器实现
• 接入链路已经覆盖依赖、配置、资源与自动化校验四个层面
• 后续若要做运行态验证，可继续基于本次改造执行 spring-boot:run 或打包后启动，并在验证完成后关闭测试进程