Spring Boot 3升级后Testcontainers端口获取异常问题排查

问题本质 #

这个错误确实是Spring应用上下文启动早于Testcontainers容器初始化完成导致的。升级到3.x版本后，上下文启动逻辑有所调整，部分场景下会在容器完全启动、端口映射完成前就尝试读取配置，此时通过@DynamicPropertySource获取端口自然会触发报错。

@DynamicPropertySource执行时机的变化 #

Spring Boot 3.x对@DynamicPropertySource的执行时机做了优化，但也引入了边界场景问题：

• 在2.x版本中，@DynamicPropertySource的逻辑会在上下文启动前、容器完全就绪后执行；
• 3.x版本为了加快启动速度，部分初始化逻辑提前。如果测试类同时使用@SpringBootTest和@Testcontainers，且未明确控制容器启动顺序，@DynamicPropertySource可能会在容器刚创建但还未启动完成时执行，此时端口尚未完成映射，就会抛出错误。

Spring Boot 3对Testcontainers配置的变更 #

确实有几个关键变更需要注意：

1. 自动配置优先级调整：3.x增强了Testcontainers的自动配置，但默认不再强制容器启动优先级高于上下文初始化，需要显式指定依赖关系；
2. @Testcontainers作用范围优化：默认是类级别，但如果测试类继承了其他配置类，可能会导致容器初始化顺序混乱；
3. 推荐自动绑定方式：官方现在更推荐用@Container配合@ServiceConnection自动绑定容器与Spring配置，替代手动在@DynamicPropertySource中设置端口的方式，这种方式能确保容器完全启动后再注入配置。

修复方案 #

• 方案一：使用@ServiceConnection自动绑定（推荐）
  给Testcontainers容器实例添加@ServiceConnection注解，Spring会自动处理容器启动和配置注入，无需手动获取端口：

  @Testcontainers
  @SpringBootTest
  class YourTest {
      @Container
      @ServiceConnection
      val postgresContainer = PostgreSQLContainer("postgres:15")
  
      // 测试代码
  }
  

• 方案二：手动确保容器就绪
  如果要保留@DynamicPropertySource，可以在获取端口前手动启动容器，或用waitingFor()确保容器就绪：

  @DynamicPropertySource
  fun dynamicProperties(registry: DynamicPropertyRegistry) {
      postgresContainer.start()
      registry.add("spring.datasource.url", postgresContainer::getJdbcUrl)
      registry.add("spring.datasource.username", postgresContainer::getUsername)
      registry.add("spring.datasource.password", postgresContainer::getPassword)
  }
  

• 方案三：调整上下文生命周期
  在@SpringBootTest中添加属性配置，确保每次测试前容器就绪后再启动上下文：

  @SpringBootTest(properties = ["spring.test.context.lifecycle.enabled=before_test_method"])
  @Testcontainers
  class YourTest {
      // 容器配置与测试代码
  }
  

内容的提问来源于stack exchange，提问作者J. H