411 lines
9.6 KiB
Markdown
411 lines
9.6 KiB
Markdown
# TongWeb接入全流程通用指南
|
||
|
||
## 1. 适用场景
|
||
|
||
本文档用于指导 Spring Boot 2.x 项目接入东方通 TongWeb 内嵌容器，适用于以下场景：
|
||
|
||
- 现有项目默认使用 Spring Boot 内嵌 Tomcat。
|
||
- 需要切换为 TongWeb 自启动运行。
|
||
- 需要将 TongWeb license 文件随应用一起打包。
|
||
- 需要沉淀一套可以迁移到其他项目的标准接入步骤。
|
||
|
||
本文以本仓库的接入经验为基础，输出的是一套可复用流程，而不是只面向当前项目的零散记录。
|
||
|
||
## 2. 前置准备
|
||
|
||
接入前需要准备以下信息：
|
||
|
||
### 2.1 TongWeb Starter 依赖
|
||
|
||
当前使用的依赖坐标：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.tongweb.springboot</groupId>
|
||
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
|
||
<version>7.0.E.7</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2.2 Maven 仓库
|
||
|
||
如果项目默认只配了 Maven Central 或阿里云公共仓库，TongWeb 依赖通常无法直接解析，需要补充 TongWeb 仓库：
|
||
|
||
```xml
|
||
<repositories>
|
||
<repository>
|
||
<id>tongweb-releases</id>
|
||
<name>TongWeb Maven Releases</name>
|
||
<url>https://mvn.elitescloud.com/nexus/repository/maven-releases/</url>
|
||
<releases>
|
||
<enabled>true</enabled>
|
||
</releases>
|
||
<snapshots>
|
||
<enabled>false</enabled>
|
||
</snapshots>
|
||
</repository>
|
||
</repositories>
|
||
```
|
||
|
||
### 2.3 License 文件
|
||
|
||
需要一份可用的 TongWeb license 文件，例如：
|
||
|
||
- `Tongweb_license.dat`
|
||
|
||
建议确认以下信息：
|
||
|
||
- 许可证版本是否与目标 TongWeb 版本一致。
|
||
- 许可证是否仍在有效期内。
|
||
- 许可证是否允许当前部署规模使用。
|
||
|
||
## 3. 接入总流程
|
||
|
||
TongWeb 接入建议按下面顺序执行：
|
||
|
||
1. 确认项目里是谁引入了默认 Tomcat。
|
||
2. 排除默认 Tomcat 依赖。
|
||
3. 引入 TongWeb Starter。
|
||
4. 把 license 文件放入 `resources`。
|
||
5. 在 `application.yml` 中增加 TongWeb 配置。
|
||
6. 执行构建、依赖树、产物检查和启动验证。
|
||
7. 根据日志处理依赖解析、license 不匹配、配置冲突等问题。
|
||
|
||
## 4. 依赖改造
|
||
|
||
### 4.1 找出默认 Tomcat 来源
|
||
|
||
很多项目不是在启动模块直接声明 `spring-boot-starter-web`，而是通过公共框架模块间接引入。因此第一步必须先查清默认 Tomcat 的入口来源。
|
||
|
||
例如：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-web</artifactId>
|
||
</dependency>
|
||
```
|
||
|
||
如果它出现在公共框架模块里，实际排除 Tomcat 时通常要在应用启动模块对该依赖做 `exclusion`。
|
||
|
||
### 4.2 排除默认 Tomcat
|
||
|
||
推荐在最终启动模块中对上游框架模块做排除，避免默认内嵌 Tomcat 和 TongWeb 同时进入运行时：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.xxx</groupId>
|
||
<artifactId>project-framework</artifactId>
|
||
<exclusions>
|
||
<exclusion>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||
</exclusion>
|
||
</exclusions>
|
||
</dependency>
|
||
```
|
||
|
||
### 4.3 引入 TongWeb Starter
|
||
|
||
在最终启动模块增加 TongWeb Starter：
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.tongweb.springboot</groupId>
|
||
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
|
||
<version>7.0.E.7</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 4.4 资源打包
|
||
|
||
如果项目资源打包规则比较严格，建议显式保留 `resources` 配置，避免 `.dat` 文件没有进入产物：
|
||
|
||
```xml
|
||
<build>
|
||
<resources>
|
||
<resource>
|
||
<directory>src/main/resources</directory>
|
||
<filtering>false</filtering>
|
||
<includes>
|
||
<include>**/*</include>
|
||
</includes>
|
||
</resource>
|
||
</resources>
|
||
</build>
|
||
```
|
||
|
||
## 5. License 文件接入
|
||
|
||
### 5.1 放置路径
|
||
|
||
将 TongWeb license 文件放到：
|
||
|
||
```text
|
||
src/main/resources/Tongweb_license.dat
|
||
```
|
||
|
||
建议直接随项目源码管理，便于构建产物统一携带。
|
||
|
||
### 5.2 命名原则
|
||
|
||
配置中的文件名必须与实际资源名完全一致。例如资源名是：
|
||
|
||
```text
|
||
Tongweb_license.dat
|
||
```
|
||
|
||
那么配置里也必须写：
|
||
|
||
```text
|
||
classpath:Tongweb_license.dat
|
||
```
|
||
|
||
不要一个地方写 `license.dat`，另一个地方写 `Tongweb_license.dat`，否则运行时会直接出现 license 读取失败。
|
||
|
||
## 6. 配置接入
|
||
|
||
建议把 TongWeb 配置统一放到 `application.yml` 中，便于其他项目直接复用，而不是散落到多个环境文件。
|
||
|
||
推荐配置如下：
|
||
|
||
```yml
|
||
server:
|
||
tongweb:
|
||
license:
|
||
path: classpath:Tongweb_license.dat
|
||
```
|
||
|
||
如果项目本身已经有 `server` 节点，直接挂到其下即可，不需要额外拆配置文件。
|
||
|
||
## 7. 构建与验证
|
||
|
||
接入完成后，至少执行下面几类验证。
|
||
|
||
### 7.1 依赖解析验证
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin -am package -DskipTests
|
||
```
|
||
|
||
预期：
|
||
|
||
- TongWeb 依赖能够正常下载。
|
||
- 项目可以正常构建。
|
||
|
||
### 7.2 产物检查
|
||
|
||
```bash
|
||
jar tf ruoyi-admin/target/ruoyi-admin.jar | rg 'Tongweb_license.dat|tongweb'
|
||
```
|
||
|
||
预期：
|
||
|
||
- `Tongweb_license.dat` 已进入 `BOOT-INF/classes/`
|
||
- TongWeb 相关 jar 已进入 `BOOT-INF/lib/`
|
||
|
||
### 7.3 依赖树检查
|
||
|
||
```bash
|
||
mvn -pl ruoyi-admin dependency:tree '-Dincludes=com.tongweb.springboot:*,com.tongweb:*,org.apache.tomcat.embed:*'
|
||
```
|
||
|
||
预期：
|
||
|
||
- 能看到 TongWeb Starter 及相关依赖。
|
||
- 默认 `spring-boot-starter-tomcat` 不应再作为主依赖链出现。
|
||
|
||
注意：
|
||
|
||
- 某些项目中仍可能看到 `tomcat-embed-el`，它可能来自 `spring-boot-starter-validation` 等其他依赖。
|
||
- 是否需要继续清理，最终以实际启动结果为准。
|
||
|
||
### 7.4 启动验证
|
||
|
||
建议从应用模块目录直接执行：
|
||
|
||
```bash
|
||
mvn -f ruoyi-admin/pom.xml spring-boot:run -Dspring-boot.run.profiles=dev
|
||
```
|
||
|
||
这样可以避免从聚合工程根目录调用时，Maven 把插件错误落到父 `pom` 上。
|
||
|
||
验证重点：
|
||
|
||
- 应用是否成功启动。
|
||
- TongWeb License SDK 日志是否出现。
|
||
- 端口是否成功监听。
|
||
- 是否出现 TongWeb 与 Tomcat 的容器冲突报错。
|
||
|
||
### 7.5 启动后进程清理
|
||
|
||
如果是本地验证，结束测试后需要手动关闭 Java 进程，避免残留服务继续占用端口。
|
||
|
||
例如：
|
||
|
||
```bash
|
||
lsof -nP -iTCP:63310 -sTCP:LISTEN
|
||
kill <PID>
|
||
```
|
||
|
||
## 8. 推荐自动化测试
|
||
|
||
如果项目有测试体系，建议至少补两类测试。
|
||
|
||
### 8.1 资源存在性测试
|
||
|
||
验证 license 文件能否从 classpath 读取：
|
||
|
||
```java
|
||
assertNotNull(
|
||
TongWebLicenseResourceTest.class.getClassLoader().getResource("Tongweb_license.dat"));
|
||
```
|
||
|
||
### 8.2 配置存在性测试
|
||
|
||
验证 `application.yml` 中是否存在：
|
||
|
||
```text
|
||
server.tongweb.license.path
|
||
```
|
||
|
||
这样可以避免后续重构时把 TongWeb 配置误删。
|
||
|
||
## 9. 常见问题
|
||
|
||
### 9.1 TongWeb 依赖下载失败
|
||
|
||
典型现象：
|
||
|
||
- Maven 提示找不到 `tongweb-spring-boot-starter-2.x`
|
||
|
||
原因：
|
||
|
||
- 项目只配置了公共仓库，没有配置 TongWeb 专用仓库。
|
||
|
||
处理方式：
|
||
|
||
- 补充 TongWeb Maven 仓库。
|
||
|
||
### 9.2 `spring-boot:run` 找不到插件
|
||
|
||
典型现象：
|
||
|
||
- `No plugin found for prefix 'spring-boot'`
|
||
|
||
处理方式：
|
||
|
||
- 改为从子模块目录执行，或者用 `-f ruoyi-admin/pom.xml` 指向具体模块。
|
||
|
||
### 9.3 `spring-boot:run` 落到父工程
|
||
|
||
典型现象：
|
||
|
||
- `Unable to find a suitable main class`
|
||
|
||
原因：
|
||
|
||
- Spring Boot 插件被执行在聚合父 `pom` 上。
|
||
|
||
处理方式：
|
||
|
||
- 使用：
|
||
|
||
```bash
|
||
mvn -f ruoyi-admin/pom.xml spring-boot:run
|
||
```
|
||
|
||
### 9.4 License 不匹配或已过期
|
||
|
||
典型现象：
|
||
|
||
- 版本号不匹配告警
|
||
- 有效期已过期
|
||
|
||
这类问题说明 TongWeb 配置链路通常已经生效，真正的问题是授权文件本身不适配当前环境。
|
||
|
||
处理方式：
|
||
|
||
- 更换与目标 TongWeb 版本一致、且仍在有效期内的 license 文件。
|
||
|
||
### 9.5 项目里仍保留 `server.tomcat.*`
|
||
|
||
如果项目原先已有：
|
||
|
||
```yml
|
||
server:
|
||
tomcat:
|
||
...
|
||
```
|
||
|
||
建议先不要大规模重构。
|
||
|
||
处理策略：
|
||
|
||
- 若 TongWeb 启动时仅忽略这些配置，则先保留。
|
||
- 只有当日志明确指出这些配置导致启动失败时，再做最小必要调整。
|
||
|
||
## 10. 可复制模板
|
||
|
||
### 10.1 `pom.xml` 最小改造模板
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.xxx</groupId>
|
||
<artifactId>project-framework</artifactId>
|
||
<exclusions>
|
||
<exclusion>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-tomcat</artifactId>
|
||
</exclusion>
|
||
</exclusions>
|
||
</dependency>
|
||
|
||
<dependency>
|
||
<groupId>com.tongweb.springboot</groupId>
|
||
<artifactId>tongweb-spring-boot-starter-2.x</artifactId>
|
||
<version>7.0.E.7</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 10.2 `application.yml` 模板
|
||
|
||
```yml
|
||
server:
|
||
tongweb:
|
||
license:
|
||
path: classpath:Tongweb_license.dat
|
||
```
|
||
|
||
### 10.3 目录模板
|
||
|
||
```text
|
||
src/main/resources/Tongweb_license.dat
|
||
```
|
||
|
||
## 11. 最终检查清单
|
||
|
||
在其他项目复用时，可以按下面清单逐项确认：
|
||
|
||
- 是否已确认默认 Tomcat 的引入来源
|
||
- 是否已排除 `spring-boot-starter-tomcat`
|
||
- 是否已引入 TongWeb Starter
|
||
- 是否已配置 TongWeb Maven 仓库
|
||
- 是否已将 `Tongweb_license.dat` 放入 `src/main/resources`
|
||
- 是否已在 `application.yml` 中加入 `server.tongweb.license.path`
|
||
- 是否已通过构建验证
|
||
- 是否已确认产物中包含 TongWeb 相关 jar 与 license 文件
|
||
- 是否已完成启动验证
|
||
- 是否已确认 license 版本、有效期和授权范围可用
|
||
|
||
## 12. 结论
|
||
|
||
TongWeb 接入本质上只包含四件事：
|
||
|
||
- 替换默认内嵌容器依赖
|
||
- 接入 TongWeb 仓库与 Starter
|
||
- 让 license 文件进入 classpath
|
||
- 用启动日志验证 TongWeb 是否真正接管运行
|
||
|
||
只要按这个顺序执行，TongWeb 接入通常可以用最短路径完成，且这套流程可以直接迁移到其他 Spring Boot 项目中。
|