企业官网建设流程全解析

三年前我刚接手一个四个业务模块的 Spring Boot 工程时，做的第一件事就是从 user-service 的 src/test/java 里拷了一份 BaseIntegrationTest 到 order-service——两份文件内容几乎一样，只是包名不同、数据库连接方式不同。后来我数了一下，这类高度相似的测试基类和工具类散落在七个模块里。我想维护过多模块 Maven 项目的朋友对这个场景都不陌生。

这篇文章要聊的，就是在 Maven 多模块 Spring Boot 项目中构建一个独立的聚合测试模块（我习惯叫 test-support，有的团队叫 test-common / test-kit），把测试基类、测试工具、容器管理和测试依赖统一收敛到一起。业务模块通过 test-jar 依赖快速复用测试资产，跨模块的集成测试也有一个明确的栖息地。文章会给出两种落地路线、完整 pom 配置、共享基类设计，以及我实测踩过的五个连环坑。

1. 多模块项目测试的隐性成本：三笔最容易攒下的"测试债"

1.1 第一笔：测试工具类在每个业务模块里复制粘贴

Maven 多模块项目默认有个强隔离策略：模块之间的常规依赖只看src/main/java，src/test下的测试代码不会通过普通<dependency>共享。这个设计本意是好的，防止测试产物污染生产，但副作用也很明显——团队一旦没人懂 test-jar 这种共享机制，就只剩复制粘贴一条路。

不信你可以回顾一下自己的项目：BaseIntegrationTest、RandomDataUtils、MockResponseBuilder，这些类是不是每个业务模块的src/test/java里各有一份？而且相互之间大概率已经"进化"出差异了。有人说 H2 不依赖 Docker，有人说 Testcontainers 才是正道，有人说自己本地装了个 MySQL 直接连。改一个公共断言工具，要在三四个模块里同步改，漏一个就埋雷。

复制粘贴的根因是 Maven 默认不让常规依赖见到 test classpath，所以你也没法用正常方式去引用另一个模块的测试类。要解决这个问题，必须显式开辟一条共享通道——也就是 test-jar 或者独立测试聚合工程，后面会详细展开。

1.2 第二笔：跨模块集成测试不知道放哪个模块

多模块项目里最尴尬的问题：一个涉及 user-service 创建用户、order-service 下单、gateway 转发链路的集成测试，到底放哪？

放 user-service 里？它得依赖 order-service 的接口和测试数据，模块职责被污染。放 order-service 里？同理。最常出现的结果是"谁先遇到谁先塞"，最后网关工程或者最上层的聚合 pom 工程里长出了一堆别的模块的测试代码。每次跑全量构建，那个最上层工程要跑十几分钟，而它本意根本不想承载业务测试。

你注意这个问题不是测试代码量的问题，是归属感的问题。业务模块的单元测试有清晰的属地，跨模块的集成测试没有。没有一个独立的聚合测试模块，这类测试就永远在"借住"别人的地盘，时间一长必然滋生混乱。

1.3 第三笔：测试依赖版本各写各的，升级时全盘崩溃

Spring Boot 多模块项目最常见的测试依赖是spring-boot-starter-test，它内部带 JUnit、AssertJ、Mockito 等一整套库。麻烦在于：如果你在 user-service 的 pom 里写了它，order-service 的 pom 里也写了它，版本号在 Spring Boot 父 pom 的统一管理下通常不会差太多，但一旦有人手贱加了<version>，或者某个模块单独引了高版本的 Testcontainers，版本分裂就开始了。

我见过一个项目里 A 模块用 JUnit 5.8，B 模块用 JUnit 5.9，平时各跑各的没问题，直到要引入 Testcontainers 的新特性，才发现 B 模块的容器镜像拉取行为跟 A 模块完全不同。这种依赖版本"各自为政"的问题，在单体项目里不存在，在多模块项目里却是常态。聚合测试模块配合父 pom 的 dependencyManagement，可以把测试相关依赖全部锁在同一水平线上，谁也别想乱来。

2. 两种落地路线：共享 test-jar 与独立聚合测试工程

2.1 方案 A：test-support 共享测试模块（打 test-jar）

test-support 是一个普通的 Maven 子模块，它不参与任何业务逻辑，只放可复用的测试基建。核心机制是利用 Maven 的 maven-jar-plugin 把该模块src/test/java下编译出来的测试类，额外打成一个 classifier 为tests的 jar，也就是 test-jar。

业务模块想用 test-support 里的BaseIntegrationTest，只需要在 pom 里这样声明：

<dependency> <groupId>com.example</groupId> <artifactId>test-support</artifactId> <version>${project.version}</version> <scope>test</scope> <type>test-jar</type> </dependency>

<type>test-jar</type>是核心，它会去解析com.example:test-support:tests这个带特殊 classifier 的构件。test-support 自身不依赖任何业务模块，所以不存在循环依赖。

2.2 方案 B：aggregation-test 独立聚合测试工程

test-support 解决的是"共享测试类"的问题，但它不解决"跨模块集成测试放哪"的问题。后者的答案是一个真正的聚合测试模块，我习惯叫它 aggregation-test。

它的定位很简单：在 pom 中依赖所有被测业务模块，scope 用 test，然后把跨模块的集成测试统一写在它自己的src/test/java里。比如：

<dependencies> <dependency> <groupId>com.example</groupId> <artifactId>user-service</artifactId> <version>${project.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>order-service</artifactId> <version>${project.version}</version> <scope>test</scope> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>test-support</artifactId> <version>${project.version}</version> <scope>test</scope> <type>test-jar</type> </dependency> </dependencies>

这里 dependency 全部是 test scope，符合它"测试专用工程"的身份。它可以在 test 编译期使用所有业务模块的 main 类，从而启动完整 Spring Boot 上下文做端到端验证。聚合测试工程本身可以参与或不参与生产发布，取决于你是否愿意把它 install 到本地仓库——我们项目里会让它参与构建，这样 CI 在一个命令里就能跑完所有测试。

2.3 对比：什么时候选 A、什么时候选 B

一句话选型：只想共享测试基建，选 A；想给跨模块测试找个家，选 B。两者不是互斥关系。

2.4 我推荐的组合打法

实践下来，A 和 B 配合使用效果最好。test-support 作为底座，提供所有模块都要用的测试基类和容器管理；aggregation-test 作为顶层入口，依赖所有业务模块和 test-support，专门放跨模块场景用例。业务模块自己的单元测试引用 test-support 即可，不用管 aggregation-test；CI 全量构建时单独跑一次 aggregation-test 就能覆盖所有跨模块链路。

这个组合的另一个好处是依赖方向特别清晰：业务模块只依赖 test-support，test-support 不依赖任何业务模块，aggregation-test 依赖所有业务模块——整个构建图是树状而不是环状，Maven 不会报循环依赖。

3. 实操搭建：pom 配置、目录结构与第一个共享基类

3.1 模块目录与父 pom 声明

假设项目已经存在 common-core、user-service、order-service 几个模块，现在要新增 test-support 和 aggregation-test。完整目录长这样：

my-project/ ├── pom.xml ├── common-core/ ├── user-service/ ├── order-service/ ├── test-support/ │ └── src/ │ └── test/ │ └── java/ │ └── com/example/support/ │ ├── BaseIntegrationTest.java │ ├── BaseWebTest.java │ └── RandomDataUtils.java └── aggregation-test/ └── src/ └── test/ └── java/ └── com/example/it/ ├── UserApiIT.java └── OrderFlowIT.java

在父 pom 的<modules>里加两行：

<modules> <module>common-core</module> <module>user-service</module> <module>order-service</module> <module>test-support</module> <module>aggregation-test</module> </modules>

注意模块顺序不能乱写。Maven 按依赖关系自动排序，但如果我手动指定构建顺序，通常把 test-support 放在业务模块之后、aggregation-test 之前更直观。

3.2 test-support 的 pom 关键配置逐行拆解

直接看一个能跑的 pom：

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>com.example</groupId> <artifactId>my-project</artifactId> <version>1.0.0-SNAPSHOT</version> </parent> <artifactId>test-support</artifactId> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.testcontainers</groupId> <artifactId>junit-jupiter</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.testcontainers</groupId> <artifactId>mysql</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.testcontainers</groupId> <artifactId>redis</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <executions> <execution> <goals> <goal>test-jar</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skipTests>true</skipTests> </configuration> </plugin> </plugins> </build> </project>

这里有两个关键点很多人第一次会踩。

第一，test-support 依赖的 starter-test 和 testcontainers 全部是 test scope。因为 Maven 对 test scope 依赖不传递，业务模块引用 test-jar 时拿不到这些第三方测试库。下面两个解决思路二选一：

• 思路一：在父 pom 的<dependencies>统一加一份 test scope 的 starter-test 和 testcontainers，让所有子模块自动继承。优点是业务模块 pom 里不再需要重复声明测试依赖，缺点是对所有子模块全局生效，不够灵活。
• 思路二：每业务模块自己声明自己需要的测试依赖，test-support 只管自己的测试类能编译就行。优点是控制粒度细，缺点是每个模块 pom 都要写一遍。

我实际项目里用的是思路一，因为测试依赖本来就该"聚合"管理，不然聚合测试模块就失去了一半意义。

第二，test-support 自身的 surefire 要配<skipTests>true</skipTests>。它只提供测试类给别的模块用，自己不应该跑测试。否则你哪次不小心在里面写了个测试类，全量构建时它也会被执行，而且因为它依赖了 Testcontainers，还会莫名其妙地启动 Docker 容器。

3.3 业务模块怎么引用 test-support

在 user-service 的 pom 里加这么一段：

<dependency> <groupId>com.example</groupId> <artifactId>test-support</artifactId> <version>${project.version}</version> <scope>test</scope> <type>test-jar</type> </dependency>

如果父 pom 的 dependencyManagement 已经管理了 test-support 的版本，<version>可以省略。注意<type>test-jar</type>背后关联的 classifier 默认就是tests，所以不需要再加<classifier>tests</classifier>，加了反而可能冲突。

3.4 第一个能跑的 BaseIntegrationTest

接下来在 test-support 的src/test/java下写一个共享基类。这个类的作用是统一所有模块的 Spring Boot 测试环境，包括容器管理：

package com.example.support; import org.junit.jupiter.api.extension.ExtendWith; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.ActiveProfiles; import org.springframework.test.context.DynamicPropertyRegistry; import org.springframework.test.context.DynamicPropertySource; import org.testcontainers.containers.MySQLContainer; import org.testcontainers.junit.jupiter.Container; import org.testcontainers.junit.jupiter.Testcontainers; @Testcontainers @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @ActiveProfiles("test") public abstract class BaseIntegrationTest { @Container static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0.32") .withDatabaseName("app_test") .withUsername("test") .withPassword("test"); @DynamicPropertySource static void mysqlProps(DynamicPropertyRegistry registry) { registry.add("spring.datasource.url", mysql::getJdbcUrl); registry.add("spring.datasource.username", mysql::getUsername); registry.add("spring.datasource.password", mysql::getPassword); } }

注意容器是 static 的，保证同一个 JVM 内所有测试类共享同一个 MySQL 容器，不会每个测试类起一个新库。@DynamicPropertySource是 Spring 5.2 之后的标准做法，比手动设置spring.datasource.url更优雅，因为可以用容器运行时的真实连接信息。

业务模块里的测试类只需要这样继承：

class UserServiceTest extends BaseIntegrationTest { // 直接具备完整 Spring Boot 环境 }

这样 team 里所有人都能跑一致的测试环境，不会出现"我本地能跑你本地不能跑"的问题。

3.5 首次构建的命令与顺序

新 clone 项目后第一次跑测试，有个隐藏的构建顺序问题：test-support 的 test-jar 必须先生成并 install 到本地仓库，业务模块的 test 阶段才能解析到它。如果直接跑mvn test，业务模块可能会报 "Could not resolve dependencies"。

推荐的首跑命令是：

mvn clean install -DskipTests -pl test-support -am

-pl test-support指定只构建 test-support，-am表示同时构建它依赖的上游模块。-DskipTests只跳过已有测试的执行，不会跳过测试代码的编译，所以 test-jar 依然会生成。

之前提过：千万不要在需要 test-jar 时用-Dmaven.test.skip=true，那个参数会直接跳过测试代码的编译，test-jar 根本打不出来，后文踩坑部分再细说。

4. 聚合模块里放什么：共享测试基建的"六件套"

4.1 基础测试类与 MockMvc 封装

第一件套是基础测试类的封装。除了上一节那个 BaseIntegrationTest，通常还会按场景拆出 Web 层的封装：

package com.example.support; import com.fasterxml.jackson.databind.ObjectMapper; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; import org.springframework.test.web.servlet.MockMvc; @AutoConfigureMockMvc public abstract class BaseWebTest extends BaseIntegrationTest { @Autowired protected MockMvc mockMvc; @Autowired protected ObjectMapper objectMapper; protected String toJson(Object obj) throws Exception { return objectMapper.writeValueAsString(obj); } }

这样业务模块里做 Controller 测试时，不需要每个模块都写一遍@AutoConfigureMockMvc和 ObjectMapper 注入。实测里最大的收益是：如果公司代码规范要求所有测试用例走同一种 MockMvc 配置，你只需要改这一个文件就能全项目生效。

4.2 Testcontainers 容器统一管理

第二件套是容器管理。除了 MySQL，多模块项目常会用到 Redis、Kafka、Elasticsearch。把这些容器封装在 test-support 里，可以避免每个模块各自定义一套容器配置。

一个实用的做法是定义专门的容器启动类：

package com.example.support; import org.testcontainers.containers.GenericContainer; import org.testcontainers.utility.DockerImageName; public final class TestContainers { private static final GenericContainer<?> REDIS = new GenericContainer<>(DockerImageName.parse("redis:7.0")) .withExposedPorts(6379); public static GenericContainer<?> redis() { return REDIS; } }

当然更推荐用 Testcontainers 官方提供的模块类，比如RedisContainer。关键是这个类一旦在 test-support 里定义好，所有业务模块的测试都能直接引用，不再出现"order-service 用 Redis 5、user-service 用 Redis 7"这种不一致。我对容器统一管理最大的感悟是：它不只是省代码，而是强制整个团队使用同一套测试环境基线，这是测试稳定的前提。

4.3 测试数据构造器与随机数据工具

第三件套是测试数据工具。很多项目里测试数据生成逻辑散落在各个模块，比如模块 A 用Math.random()，模块 B 用UUID.randomUUID()，生成的字符串长度还不一样。把这些统一收敛到 test-support：

package com.example.support; import java.util.concurrent.ThreadLocalRandom; public final class RandomDataUtils { private static final String CHARS = "abcdefghijklmnopqrstuvwxyz0123456789"; private RandomDataUtils() { } public static String randomString(int length) { StringBuilder sb = new StringBuilder(length); for (int i = 0; i < length; i++) { sb.append(CHARS.charAt(ThreadLocalRandom.current().nextInt(CHARS.length()))); } return sb.toString(); } public static Long randomLong() { return ThreadLocalRandom.current().nextLong(1_000_000L); } }

生产环境用这个工具比手写UUID.randomUUID().toString()更可控，因为你能设定长度和字符集。一些测试框架甚至推荐使用固定种子生成数据，这样用例可复现。我在项目里见过最离谱的是有人用System.currentTimeMillis()生成手机号，测试跑快了会重复。统一工具类之后这些问题都消失了。

4.4 JSON 断言与数据比对工具

第四件套是 JSON 断言工具。Spring Boot 的 starter-test 自带 jsonassert，但直接用它心智负担较高。建议在 test-support 里封装一层：

package com.example.support; import com.jayway.jsonpath.JsonPath; import org.springframework.test.web.servlet.ResultActions; public final class JsonAssertUtils { private JsonAssertUtils() { } public static String readJson(ResultActions result, String path) throws Exception { String content = result.andReturn().getResponse().getContentAsString(); return JsonPath.read(content, path).toString(); } }

当然如果你习惯 AssertJ 的json().isEqualTo，也可以封一层。反正原则是把 JSON 的解析、断言、错误信息格式化都集中在一处。多模块项目里，各模块对接口返回结构的断言方式五花八门，统一封装后，接口变更时只需要更新一个类。

4.5 可选测试配置：@TestConfiguration 的正确用法

第五件套是@TestConfiguration配置类。很多时候测试需要 mock 掉某个外部 RPC 客户端，或者替换某个 Bean。把这些配置类放在 test-support 里有一个隐藏的好处：多个模块可以复用同一个测试配置模板。

package com.example.support; import org.springframework.boot.test.context.TestConfiguration; import org.springframework.context.annotation.Bean; @TestConfiguration public class MockExternalClientConfig { @Bean public SomeExternalClient someExternalClient() { return new MockExternalClient(); } }

业务模块测试类上只要这样引入即可：

@Import(MockExternalClientConfig.class) class SomeServiceTest extends BaseIntegrationTest { }

注意@TestConfiguration不会被 Spring Boot 的组件扫描自动加载，必须显式@Import，这是它和普通@Configuration最大的区别。把这类配置统一放到 test-support 里，能保证所有模块对外部服务的 mock 行为一致，不会出现这个模块 mock 了、那个模块忘了 mock 的情况。

4.6 包名与目录约定

第六件套不是代码，是约定。test-support 里的共享类包名统一用com.example.support，业务模块的测试代码里 import 这个包下的类。aggregation-test 里的集成测试统一用com.example.it包，并且类名以IT结尾，方便 surefire / failsafe 识别。

不要小看包名约定。多模块项目里如果不统一，就会出现"每个模块各自又搞了一个 internal 包"的混乱局面。包名也是聚合测试模块的"广场"，大家从同一个地方 import，代码结构自然就收敛了。

5. 实测中踩过的坑：test-jar 依赖与构建顺序的连环雷

5.1 坑一：忘掉 test-jar 的 type 或 classifier，报找不到符号

最典型的报错长这样：

[ERROR] /xx/user-service/src/test/java/xx/UserServiceTest.java:[10,29] package com.example.support does not exist

排查思路第一步是看业务模块的 pom 里是否写了<type>test-jar</type>。有人会只写scope=test，然后发现 test-support 的普通 jar 里根本没有BaseIntegrationTest.class——因为在 test-support 里那个类本来就放在src/test/java下，普通 jar 不含它。加<type>test-jar</type>后依赖就会解析到test-support:tests这个特殊构件。

还有个容易混淆的点：test-jar 默认 classifier 是tests，所以你在依赖里写<classifier>tests</classifier>也能达到类似效果，但这时候 type 不要写成jar，否则 Maven 解析坐标会怪怪的。最省心的写法就是type用test-jar，其他交给 Maven。

5.2 坑二：用 -Dmaven.test.skip=true 把 test-jar 一起跳没了

很多老 Java Maven 用户习惯了-Dmaven.test.skip=true来跳过测试，但这个参数对 test-support 模块是致命的。它会跳过测试代码的编译，maven-jar-plugin的 test-jar goal 找不到 test-classes 目录，最后生成的 artifacts 里就没有 test-jar。

结果就是：你在本地仓库里确实看到了 test-support 的目录，但里面只有test-support-1.0.0-SNAPSHOT.jar，没有test-support-1.0.0-SNAPSHOT-tests.jar。业务模块构建时还是找不到com.example.support包。

正确做法是用-DskipTests，它只跳过执行，不跳过编译，test-jar 照常生成。我建议在团队的 CI 脚本里明文统一写好两个场景的参数：

# 快速构建，但保留测试编译产物 mvn clean install -DskipTests # 全量测试 mvn clean verify

5.3 坑三：IDE 里编译通过，命令行构建却失败

IDEA 有个让所有人都困惑的行为：当你把 test-support 作为依赖 module 导入后，IDE 可以在编译时直接从另一个 module 的 target/test-classes 里拿类，所以很多人在 IDE 里跑测试没问题，一到命令行mvn test就报依赖解析失败。

原因还是 Maven 仓库里没有安装 test-support 的 test-jar。IDE 编译走的是项目内部模块依赖，Maven 走的是本地仓库 artifacts，两者根本不是一回事。

解决方法是回到 3.5 节的首跑命令，先把 test-support install 一遍。并且我有个习惯：每次改了 test-support 里共享类的方法签名，都手动跑一次：

mvn install -pl test-support -am -DskipTests

不改 test-support 的情况下，业务模块的日常测试不需要多次 install。

5.4 坑四：test-support 反向依赖业务模块造成循环引用

有个同事觉得 test-support 里反正要写集成测试基类，干脆让 test-support 直接依赖所有业务模块，这样基类药物注入更方便。结果 Maven 构建直接报循环依赖：user-service 依赖 test-support，test-support 依赖 user-service，构建图无法拓扑排序。

这是聚合测试模块设计中最容易犯的架构错误。test-support 的定位是"无业务依赖的测试底座"，它只能依赖第三方库和 Spring Boot 测试框架，绝不能反向依赖任何业务模块。如果你需要在基类里使用某个业务模块的 Bean 类型，那不是 write once 的问题，说明该测试类本身就属于某个特定模块，应该放在那个模块的src/test里，而不是塞进共享底座。

5.5 坑五：聚合测试模块跑起来显示没有测试可运行

aggregation-test 建好之后，第一次跑mvn test -pl aggregation-test，你可能会看到：

Tests run: 0, Failures: 0, Errors: 0, Skipped: 0

原因通常是 surefire 默认只识别*Test.java、*Tests.java等命名规则，而你在聚合测试模块里把跨模块用例都命名成UserApiIT、OrderFlowIT，它默认不认。解决方法是给 aggregation-test 的 surefire 配置 includes：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <includes> <include>**/*Test.java</include> <include>**/*Tests.java</include> <include>**/*IT.java</include> </includes> </configuration> </plugin>

更规范的做法是用 maven-failsafe-plugin 跑集成测试，单元测试用 surefire，集成测试用 failsafe，两个插件的生命周期阶段不同，能把单测和集成测试在 CI 里分开执行。我个人的体会是：聚合测试模块能让你非常自然地引入这种"单测 / 集成测试分离"的纪律，因为所有集成测试都集中在了一个工程里，处理命名规则反而成为一种纯粹的技术选型。

测试基建这件事，表面上是 pom 配置和目录结构的小事，实际操作起来却牵一发动全身。把 test-support 这一层架构搭稳之后，最大收益不是少写了几百行重复代码，而是整个团队有了统一的测试基线和一套"测试代码该往哪里放"的明确规则。后来接手这个项目的新人，第一次写集成测试就知道去 aggregation-test 里写，再也不会往网关模块里乱塞用例了。这大概就是聚合测试模块最值得投入的地方。