本文详解如何通过 Maven build-helper-maven-plugin 动态分配随机端口，并确保该端口值在 Cucumber 步骤类中可通过 System.getProperty() 正确获取，关键在于将端口属性显式传递给 Surefire JVM 参数。
本文详解如何通过 maven `build-helper-maven-plugin` 动态分配随机端口，并确保该端口值在 cucumber 步骤类中可通过 `system.getproperty()` 正确获取，关键在于将端口属性显式传递给 surefire jvm 参数。
在基于 Maven 的 Java 项目中集成 Cucumber 进行端到端或集成测试时，常需为被测服务（如 Spring Boot 应用）和依赖组件（如 Kafka）动态分配可用端口，以避免端口冲突、提升 CI/CD 稳定性。Maven 官方推荐的 build-helper-maven-plugin 可在构建生命周期中自动探测并预留空闲端口，并将其作为 Maven 属性（如 ${service.port}）注入构建上下文。
然而，Maven 属性 ≠ JVM 系统属性：build-helper-maven-plugin 设置的 ${service.port} 仅在 Maven 构建阶段可见，而 Cucumber 测试运行在 Surefire 插件启动的独立 JVM 中。若未显式将该属性传递至 JVM，则 System.getProperty("service.port") 必然返回 null。
✅ 正确做法是：在 maven-surefire-plugin 的 <configuration></configuration> 中，通过 <argline></argline> 将 Maven 属性映射为 JVM 系统属性：
Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。 涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。 当用户需要：(1) 编写或审查Java代码 (2) 检查命名/代码规范 (3) 处理异常和日志 (4) 编写单元测试 (5) 安全编码 (6) 数据库设...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
<executions>
<execution>
<id>cucumber-tests</id>
<phase>integration-test</phase>
<goals>
<goal>test</goal>
</goals>
<configuration>
<!-- 其他配置（如 includes, systemPropertyVariables）保持不变 -->
<systemPropertyVariables>
<log.dir>${project.build.directory}/logs</log.dir>
</systemPropertyVariables>
<includes>
<include>**/*Test.java</include>
<include>**/*Steps.java</include>
<exclude>**/*cucumber.RunCucumberIT.java</exclude>
</includes>
<!-- ✅ 关键：将 Maven 属性注入 JVM 系统属性 -->
<argLine>-Dservice.port=${service.port} -Dkafka.port=${kafka.port}</argLine>
<testFailureIgnore>false</testFailureIgnore>
</configuration>
</execution>
</executions>
</plugin>⚠️ 注意事项：
立即学习“Java免费学习笔记（深入）”；
-
执行顺序很重要：确保
build-helper-maven-plugin的<execution></execution>在 POM 中位于maven-surefire-plugin之前，或至少其绑定的生命周期阶段（如process-resources）早于 Surefire 的test执行阶段（默认为test，此处设为integration-test）。否则${service.port}在解析时可能尚未生成，导致空值。 -
属性名一致性：
<portname></portname>中定义的名称（如service.port）必须与<argline></argline>中引用的名称（${service.port}）完全一致，区分大小写。 -
多端口支持：如同时使用 Kafka 和服务端口，需在
<argline></argline>中一并声明多个-Dkey=${value}，例如：-Dservice.port=${service.port} -Dkafka.port=${kafka.port}。 - Cucumber 步骤中安全读取：建议添加空值校验，提升健壮性：
String servicePort = System.getProperty("service.port");
if (servicePort == null || servicePort.trim().isEmpty()) {
throw new RuntimeException("Missing required system property: service.port");
}
int port = Integer.parseInt(servicePort);总结：Maven 属性不会自动透传至测试 JVM，必须通过 Surefire 的 <argline></argline> 显式桥接。配合合理的插件执行顺序与属性命名，即可在 Cucumber Step Definition 中稳定获取动态端口，实现真正可并行、无冲突的集成测试。
