421 lines
11 KiB
Markdown
421 lines
11 KiB
Markdown
# TongWeb自启动适配后端 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED: Use `superpowers:executing-plans` to implement this plan. Repository policy in `AGENTS.md` forbids subagents. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在 `ruoyi-admin` 模块中接入 TongWeb Spring Boot Starter，替换默认内嵌 Tomcat，并让 `Tongweb_license.dat` 通过 classpath 生效，同时保持现有 `java -jar` 自启动方式不变。
|
||
|
||
**Architecture:** 方案只落在 `ruoyi-admin` 模块。通过调整 `ruoyi-admin/pom.xml` 的运行时依赖与资源打包规则，将 TongWeb 作为唯一内嵌容器，并在 `application-dev.yml`、`application-uat.yml`、`application-pro.yml` 中统一声明 `server.tongweb.license.path`。验证分为资源存在性测试、环境配置测试、构建产物检查和本地启动验证四层。
|
||
|
||
**Tech Stack:** Java 8, Spring Boot 2.5.15, Maven, JUnit 5, RuoYi-Vue backend (`ruoyi-admin`)
|
||
|
||
---
|
||
|
||
### File Map
|
||
|
||
**Create:**
|
||
- `ruoyi-admin/src/main/resources/Tongweb_license.dat`
|
||
- `ruoyi-admin/src/test/java/com/ruoyi/TongWebLicenseResourceTest.java`
|
||
- `ruoyi-admin/src/test/java/com/ruoyi/TongWebYamlConfigTest.java`
|
||
- `doc/2026-04-16-TongWeb自启动适配后端实施记录.md`
|
||
|
||
**Modify:**
|
||
- `ruoyi-admin/pom.xml`
|
||
- `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- `ruoyi-admin/src/main/resources/application-uat.yml`
|
||
- `ruoyi-admin/src/main/resources/application-pro.yml`
|
||
|
||
**Reference:**
|
||
- `doc/2026-04-16-TongWeb自启动适配后端设计文档.md`
|
||
- `doc/Tongweb_license.dat`
|
||
- `ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java`
|
||
- `ruoyi-admin/src/main/java/com/ruoyi/RuoYiServletInitializer.java`
|
||
|
||
### Task 1: 锁定 license 资源接入链路
|
||
|
||
**Files:**
|
||
- Create: `ruoyi-admin/src/test/java/com/ruoyi/TongWebLicenseResourceTest.java`
|
||
- Create: `ruoyi-admin/src/main/resources/Tongweb_license.dat`
|
||
- Modify: `ruoyi-admin/pom.xml`
|
||
|
||
- [ ] **Step 1: 编写失败测试，先证明 classpath 中还没有 TongWeb license**
|
||
|
||
```java
|
||
package com.ruoyi;
|
||
|
||
import static org.junit.jupiter.api.Assertions.assertNotNull;
|
||
|
||
import org.junit.jupiter.api.Test;
|
||
|
||
class TongWebLicenseResourceTest
|
||
{
|
||
@Test
|
||
void shouldLoadTongWebLicenseFromClasspath()
|
||
{
|
||
assertNotNull(
|
||
TongWebLicenseResourceTest.class.getClassLoader().getResource("Tongweb_license.dat"));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行单测确认当前失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -Dtest=TongWebLicenseResourceTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
FAIL
|
||
resource "Tongweb_license.dat" is null
|
||
```
|
||
|
||
- [ ] **Step 3: 最小实现资源接入与运行时依赖替换**
|
||
|
||
在 `ruoyi-admin/pom.xml` 中完成以下最小改造：
|
||
|
||
- 给 `ruoyi-framework` 依赖增加对 `spring-boot-starter-tomcat` 的排除，避免默认内嵌 Tomcat 继续进入运行时依赖树。
|
||
- 新增 TongWeb Starter 依赖：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.tongweb.springboot</groupId>
|
||
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
|
||
<version>7.0.E.7</version>
|
||
</dependency>
|
||
```
|
||
|
||
- 在 `build` 中补充资源配置，确保 `.dat` 文件被正常打包：
|
||
|
||
```xml
|
||
<resources>
|
||
<resource>
|
||
<directory>src/main/resources</directory>
|
||
<filtering>false</filtering>
|
||
<includes>
|
||
<include>**/*</include>
|
||
</includes>
|
||
</resource>
|
||
</resources>
|
||
```
|
||
|
||
- 将 `doc/Tongweb_license.dat` 原样复制到 `ruoyi-admin/src/main/resources/Tongweb_license.dat`。
|
||
|
||
- [ ] **Step 4: 重新运行资源测试确认通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -Dtest=TongWebLicenseResourceTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BUILD SUCCESS
|
||
Tests run: 1, Failures: 0
|
||
```
|
||
|
||
- [ ] **Step 5: 提交这一小步**
|
||
|
||
```bash
|
||
git add ruoyi-admin/pom.xml \
|
||
ruoyi-admin/src/main/resources/Tongweb_license.dat \
|
||
ruoyi-admin/src/test/java/com/ruoyi/TongWebLicenseResourceTest.java
|
||
git commit -m "接入TongWeb依赖与许可证资源"
|
||
```
|
||
|
||
### Task 2: 补齐多环境 TongWeb 配置
|
||
|
||
**Files:**
|
||
- Create: `ruoyi-admin/src/test/java/com/ruoyi/TongWebYamlConfigTest.java`
|
||
- Modify: `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- Modify: `ruoyi-admin/src/main/resources/application-uat.yml`
|
||
- Modify: `ruoyi-admin/src/main/resources/application-pro.yml`
|
||
|
||
- [ ] **Step 1: 编写失败测试，先锁定三套环境配置必须同时存在**
|
||
|
||
```java
|
||
package com.ruoyi;
|
||
|
||
import static org.junit.jupiter.api.Assertions.assertEquals;
|
||
|
||
import java.util.List;
|
||
import org.junit.jupiter.api.Test;
|
||
import org.springframework.boot.env.YamlPropertySourceLoader;
|
||
import org.springframework.core.env.PropertySource;
|
||
import org.springframework.core.io.ClassPathResource;
|
||
|
||
class TongWebYamlConfigTest
|
||
{
|
||
@Test
|
||
void shouldExposeTongWebLicensePathInAllProfiles() throws Exception
|
||
{
|
||
assertEquals("classpath:Tongweb_license.dat", load("application-dev.yml"));
|
||
assertEquals("classpath:Tongweb_license.dat", load("application-uat.yml"));
|
||
assertEquals("classpath:Tongweb_license.dat", load("application-pro.yml"));
|
||
}
|
||
|
||
private String load(String fileName) throws Exception
|
||
{
|
||
YamlPropertySourceLoader loader = new YamlPropertySourceLoader();
|
||
List<PropertySource<?>> sources = loader.load(fileName, new ClassPathResource(fileName));
|
||
return (String) sources.get(0).getProperty("server.tongweb.license.path");
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行单测确认当前失败**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -Dtest=TongWebYamlConfigTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
FAIL
|
||
expected: classpath:Tongweb_license.dat
|
||
but was : null
|
||
```
|
||
|
||
- [ ] **Step 3: 在三套环境配置中追加 TongWeb license 路径**
|
||
|
||
在以下文件的 `server:` 节点下新增同一段配置：
|
||
|
||
- `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- `ruoyi-admin/src/main/resources/application-uat.yml`
|
||
- `ruoyi-admin/src/main/resources/application-pro.yml`
|
||
|
||
新增内容：
|
||
|
||
```yml
|
||
tongweb:
|
||
license:
|
||
path: classpath:Tongweb_license.dat
|
||
```
|
||
|
||
要求：
|
||
|
||
- 保持现有 YAML 缩进风格。
|
||
- 不删除现有 `server.tomcat.*` 配置。
|
||
- 不新增任何容器切换开关。
|
||
|
||
- [ ] **Step 4: 重新运行配置测试确认通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -Dtest=TongWebYamlConfigTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BUILD SUCCESS
|
||
Tests run: 1, Failures: 0
|
||
```
|
||
|
||
- [ ] **Step 5: 提交这一小步**
|
||
|
||
```bash
|
||
git add ruoyi-admin/src/main/resources/application-dev.yml \
|
||
ruoyi-admin/src/main/resources/application-uat.yml \
|
||
ruoyi-admin/src/main/resources/application-pro.yml \
|
||
ruoyi-admin/src/test/java/com/ruoyi/TongWebYamlConfigTest.java
|
||
git commit -m "补充TongWeb许可证配置"
|
||
```
|
||
|
||
### Task 3: 完成构建验证与启动验证
|
||
|
||
**Files:**
|
||
- Modify: `ruoyi-admin/pom.xml`（如 Task 1 后仍需微调资源或依赖排除）
|
||
- Reference: `ruoyi-admin/target/ruoyi-admin.jar`
|
||
- Reference: `ruoyi-admin/target/*.war`
|
||
|
||
- [ ] **Step 1: 运行模块构建，确认 TongWeb 依赖能够正常解析**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am package -DskipTests
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BUILD SUCCESS
|
||
```
|
||
|
||
- [ ] **Step 2: 检查构建产物中确实包含 TongWeb license**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
jar tf ruoyi-admin/target/ruoyi-admin.jar | rg "Tongweb_license.dat"
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BOOT-INF/classes/Tongweb_license.dat
|
||
```
|
||
|
||
- [ ] **Step 3: 检查运行时依赖树，确认默认 Tomcat 已退出主链路**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin dependency:tree -Dincludes=com.tongweb.springboot:*,org.apache.tomcat.embed:*
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
显示 TongWeb Starter
|
||
不再出现 spring-boot-starter-tomcat 的运行时主依赖链
|
||
```
|
||
|
||
- [ ] **Step 4: 按 dev 环境启动应用并观察 TongWeb 相关日志**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am spring-boot:run -Dspring-boot.run.profiles=dev
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
应用成功启动
|
||
未出现 TongWeb license 加载失败
|
||
未出现容器冲突导致的启动中断
|
||
```
|
||
|
||
- [ ] **Step 5: 停止启动验证进程并记录结果**
|
||
|
||
执行方式：
|
||
|
||
- 若前台运行，使用 `Ctrl+C` 停止。
|
||
- 若后台运行，记录 PID 后执行 `kill <PID>`。
|
||
|
||
要求：
|
||
|
||
- 确保本次验证产生的进程被关闭，符合仓库“测试结束后自动结束进程”的约束。
|
||
|
||
- [ ] **Step 6: 若出现 `server.tomcat.*` 触发的明确报错，仅修正报错项后重跑 Task 3**
|
||
|
||
处理原则：
|
||
|
||
- 只处理导致 TongWeb 启动失败的具体项。
|
||
- 不做容器参数体系重构。
|
||
|
||
- [ ] **Step 7: 提交这一小步**
|
||
|
||
```bash
|
||
git add ruoyi-admin/pom.xml
|
||
git commit -m "完成TongWeb自启动验证"
|
||
```
|
||
|
||
### Task 4: 补齐后端实施记录
|
||
|
||
**Files:**
|
||
- Create: `doc/2026-04-16-TongWeb自启动适配后端实施记录.md`
|
||
- Reference: `doc/2026-04-16-TongWeb自启动适配后端设计文档.md`
|
||
- Reference: `doc/2026-04-16-TongWeb自启动适配后端实施计划.md`
|
||
|
||
- [ ] **Step 1: 编写实施记录，覆盖本次改造结果**
|
||
|
||
记录内容至少包含：
|
||
|
||
- 改动文件清单
|
||
- TongWeb 依赖替换说明
|
||
- `Tongweb_license.dat` 接入说明
|
||
- 配置新增说明
|
||
- 测试与启动验证结果
|
||
- 若有额外兼容调整，写明触发原因与处理结果
|
||
|
||
- [ ] **Step 2: 自检实施记录与计划、设计文档保持一致**
|
||
|
||
检查点：
|
||
|
||
- 文件名、配置名均为 `Tongweb_license.dat`
|
||
- 只记录后端改造
|
||
- 未写入需求之外的扩展方案
|
||
|
||
- [ ] **Step 3: 提交这一小步**
|
||
|
||
```bash
|
||
git add doc/2026-04-16-TongWeb自启动适配后端实施记录.md
|
||
git commit -m "补充TongWeb适配实施记录"
|
||
```
|
||
|
||
### Task 5: 最终回归与交付检查
|
||
|
||
**Files:**
|
||
- Reference: `ruoyi-admin/pom.xml`
|
||
- Reference: `ruoyi-admin/src/main/resources/Tongweb_license.dat`
|
||
- Reference: `ruoyi-admin/src/main/resources/application-dev.yml`
|
||
- Reference: `ruoyi-admin/src/main/resources/application-uat.yml`
|
||
- Reference: `ruoyi-admin/src/main/resources/application-pro.yml`
|
||
- Reference: `ruoyi-admin/src/test/java/com/ruoyi/TongWebLicenseResourceTest.java`
|
||
- Reference: `ruoyi-admin/src/test/java/com/ruoyi/TongWebYamlConfigTest.java`
|
||
- Reference: `doc/2026-04-16-TongWeb自启动适配后端实施记录.md`
|
||
|
||
- [ ] **Step 1: 运行本次新增测试，确认均通过**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -Dtest=TongWebLicenseResourceTest,TongWebYamlConfigTest test
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BUILD SUCCESS
|
||
Tests run: 2, Failures: 0
|
||
```
|
||
|
||
- [ ] **Step 2: 再执行一次模块构建，确认最终产物稳定**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am package -DskipTests
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
BUILD SUCCESS
|
||
```
|
||
|
||
- [ ] **Step 3: 检查工作区，仅保留本次需求相关变更**
|
||
|
||
Run:
|
||
|
||
```bash
|
||
git status --short
|
||
```
|
||
|
||
Expected:
|
||
|
||
```text
|
||
仅出现本次 TongWeb 适配相关文件变更
|
||
忽略 .DS_Store
|
||
```
|
||
|
||
- [ ] **Step 4: 整理最终说明，准备向用户回报**
|
||
|
||
回报内容应包含：
|
||
|
||
- 具体改动范围
|
||
- 测试与启动验证结果
|
||
- 是否存在需用户额外确认的运行环境前置条件
|
||
- 实施记录文档路径
|