194 lines
6.4 KiB
Markdown
194 lines
6.4 KiB
Markdown
# TongWeb 自启动适配后端设计文档
|
||
|
||
## 1. 背景
|
||
|
||
当前项目为 RuoYi-Vue 前后端分离架构，后端启动入口位于 `ruoyi-admin` 模块，现状采用 Spring Boot 自启动方式运行。根据 `doc/tongweb.docx` 的要求，本次需要将后端运行容器从默认 Tomcat 调整为 TongWeb，并接入 TongWeb license 文件。
|
||
|
||
本次改造范围已经确认如下：
|
||
|
||
- 只改后端，不涉及前端。
|
||
- 保持 Spring Boot 自启动模式，不改为外部 TongWeb 容器部署。
|
||
- 资源目录中直接使用 `Tongweb_license.dat` 文件名，不改名。
|
||
- TongWeb Starter 依赖坐标为 `com.tongweb.springboot:tongweb-spring-boot-starter-2.x:7.0.E.7`。
|
||
|
||
## 2. 目标
|
||
|
||
本次改造需要达成以下结果：
|
||
|
||
- 后端仍可通过 `java -jar` 方式启动。
|
||
- 运行时内嵌 Web 容器由默认 Tomcat 切换为 TongWeb。
|
||
- TongWeb license 文件随应用构建产物一起打包并可通过 classpath 访问。
|
||
- 新增 TongWeb license 配置后，现有业务模块与接口链路保持不变。
|
||
|
||
## 3. 设计原则
|
||
|
||
- 采用最短路径实现，只修改 TongWeb 适配所必需的内容。
|
||
- 改动集中在 `ruoyi-admin` 模块，避免无关模块受到影响。
|
||
- 不增加兼容性开关、双容器切换方案或补丁式旁路逻辑。
|
||
- 先完成容器替换与 license 接入，再通过启动验证确认链路闭环。
|
||
|
||
## 4. 方案对比
|
||
|
||
### 方案 A：仅在 `ruoyi-admin` 替换为 TongWeb 自启动
|
||
|
||
做法：
|
||
|
||
- 在 `ruoyi-admin/pom.xml` 中排除 Spring Boot 默认 Tomcat。
|
||
- 引入 TongWeb Starter 依赖。
|
||
- 将 `Tongweb_license.dat` 放入 `ruoyi-admin/src/main/resources`。
|
||
- 在环境配置中新增 `server.tongweb.license.path`。
|
||
|
||
优点：
|
||
|
||
- 改动范围最小，完全贴合当前需求。
|
||
- 不改变现有 `main` 方法启动链路。
|
||
- 对业务模块零侵入。
|
||
|
||
缺点：
|
||
|
||
- 需要验证现有 `server.tomcat.*` 配置在 TongWeb 下是否存在无效项。
|
||
|
||
### 方案 B：在父 `pom` 统一管理 TongWeb 版本，再由 `ruoyi-admin` 接入
|
||
|
||
做法：
|
||
|
||
- 在根 `pom.xml` 中增加 TongWeb 版本管理。
|
||
- 在 `ruoyi-admin` 声明依赖与资源处理。
|
||
|
||
优点：
|
||
|
||
- 依赖管理更集中。
|
||
|
||
缺点：
|
||
|
||
- 当前只有 `ruoyi-admin` 使用 TongWeb，额外抽象收益较低。
|
||
- 相比本次需求略显偏重。
|
||
|
||
### 方案 C：同时保留 Tomcat 与 TongWeb 切换能力
|
||
|
||
做法：
|
||
|
||
- 通过 Maven Profile 或可选依赖实现容器切换。
|
||
|
||
优点：
|
||
|
||
- 运行方式更灵活。
|
||
|
||
缺点：
|
||
|
||
- 明显超出当前需求。
|
||
- 会增加打包、启动、部署链路复杂度。
|
||
|
||
### 结论
|
||
|
||
采用方案 A。该方案满足当前需求且实现路径最短，符合本次改造边界。
|
||
|
||
## 5. 详细设计
|
||
|
||
### 5.1 模块范围
|
||
|
||
仅修改 `ruoyi-admin` 模块，保留现有业务模块、启动入口和打包主流程。
|
||
|
||
### 5.2 依赖调整
|
||
|
||
在 `ruoyi-admin/pom.xml` 中执行以下改造：
|
||
|
||
- 引入 `com.tongweb.springboot:tongweb-spring-boot-starter-2.x:7.0.E.7`。
|
||
- 排除 Spring Boot 默认内嵌 Tomcat 依赖，避免运行时容器冲突。
|
||
- 补充资源打包配置，确保 `.dat` 许可证文件进入构建产物。
|
||
|
||
依赖管理不下沉到父 `pom`，保持改造聚焦在当前实际使用模块。
|
||
|
||
### 5.3 资源文件接入
|
||
|
||
将仓库中的 `doc/Tongweb_license.dat` 复制到：
|
||
|
||
- `ruoyi-admin/src/main/resources/Tongweb_license.dat`
|
||
|
||
资源文件名保持为 `Tongweb_license.dat`，与用户确认结果一致，不额外重命名为 `license.dat`。
|
||
|
||
### 5.4 配置设计
|
||
|
||
由于项目当前按环境拆分配置文件，因此在以下文件中统一补充 TongWeb license 配置：
|
||
|
||
- `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- `ruoyi-admin/src/main/resources/application-uat.yml`
|
||
- `ruoyi-admin/src/main/resources/application-pro.yml`
|
||
|
||
新增配置位于 `server` 节点下，形式为：
|
||
|
||
```yml
|
||
server:
|
||
tongweb:
|
||
license:
|
||
path: classpath:Tongweb_license.dat
|
||
```
|
||
|
||
这样可以确保 dev、uat、pro 三套环境在 TongWeb 自启动时行为一致。
|
||
|
||
### 5.5 Tomcat 配置处理策略
|
||
|
||
当前环境配置中存在 `server.tomcat.*` 参数。针对这些参数，本次采用以下策略：
|
||
|
||
- 不主动做大规模迁移或参数重写。
|
||
- 若 TongWeb Starter 启动时仅忽略这些配置，则保持不动。
|
||
- 若个别参数导致启动失败，再针对报错项做最小必要调整。
|
||
|
||
该策略的目的，是避免在本次需求中扩展出容器参数全面改造。
|
||
|
||
## 6. 数据流与运行链路
|
||
|
||
改造后的启动链路如下：
|
||
|
||
1. 应用仍从 `RuoYiApplication.main` 进入。
|
||
2. Spring Boot 自动装配 TongWeb Starter。
|
||
3. TongWeb 从 classpath 读取 `Tongweb_license.dat`。
|
||
4. 应用在 TongWeb 内嵌容器中完成启动。
|
||
5. 现有业务接口继续由 Spring MVC 与现有业务模块处理。
|
||
|
||
本次不改变业务接口、数据库访问、鉴权、缓存和前端交互逻辑。
|
||
|
||
## 7. 错误处理与风险边界
|
||
|
||
本次重点关注以下风险：
|
||
|
||
- TongWeb 依赖无法从当前 Maven 仓库解析。
|
||
- `Tongweb_license.dat` 未被正确打包进产物。
|
||
- `server.tongweb.license.path` 与实际资源名不一致导致 license 加载失败。
|
||
- 现有 `server.tomcat.*` 中存在与 TongWeb 冲突的配置项。
|
||
|
||
对应处理原则如下：
|
||
|
||
- 先保证依赖可解析、资源可入包、配置可读取。
|
||
- 仅在出现明确启动错误时处理 TongWeb 与 Tomcat 参数冲突。
|
||
- 不扩展到业务逻辑调整、容器双模切换或外部部署方案。
|
||
|
||
## 8. 验证方案
|
||
|
||
验证范围限定为 TongWeb 适配闭环，不扩展无关测试：
|
||
|
||
1. 执行 Maven 构建，确认依赖解析正常、项目可打包。
|
||
2. 检查 `ruoyi-admin` 最终构建产物，确认包含 `Tongweb_license.dat`。
|
||
3. 按现有 Spring Boot 自启动方式启动应用。
|
||
4. 确认应用能完成启动，且未因 TongWeb license 配置报错中断。
|
||
|
||
若启动时报出 TongWeb 对 `server.tomcat.*` 配置不兼容，再做针对性修正并重新验证。
|
||
|
||
## 9. 非目标
|
||
|
||
以下内容不在本次改造范围内：
|
||
|
||
- 前端页面或前端构建链路调整。
|
||
- 外部 TongWeb 服务器 WAR 部署方案。
|
||
- Tomcat 与 TongWeb 双容器切换能力。
|
||
- 容器参数体系重构。
|
||
- 业务接口、数据库结构、权限逻辑变更。
|
||
|
||
## 10. 文档产出
|
||
|
||
本次仅涉及后端，因此实施阶段只需要补充一份后端实施记录，保存在 `doc/` 目录下。
|
||
|
||
## 11. 审阅说明
|
||
|
||
根据仓库协作约束，本次不启用 subagent。设计文档将采用手工自检方式完成审阅，待用户确认后再进入实施计划阶段。
|