# 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 项目中。