如何搭建Java的容器化测试环境_Testcontainers集成测试配置-java教程-PHP中文网

需统一Testcontainers各模块版本，推荐用testcontainers-bom管理；Spring Boot 3.2+用户须注意junit-jupiter版本兼容性，避免NoClassDefFoundError。

如何搭建java的容器化测试环境_testcontainers集成测试配置

这是常见于依赖版本混乱的典型错误——testcontainers 主模块和子模块（如 postgresql、junit-jupiter）版本不一致导致类加载失败。

统一用 BOM 管理依赖，Maven 中引入 testcontainers-bom，再声明各模块时不写版本号
避免混用 org.testcontainers:testcontainers 1.17.x 和 org.testcontainers:postgresql 1.18.x —— 即使只差一个小版本，内部 API 也可能断裂
Spring Boot 3.2+ 用户注意：spring-boot-starter-test 自带的 junit-jupiter 是 5.10+，而旧版 Testcontainers（@RegisterExtension 支持不稳定，建议升到 1.19.0+

Testcontainers 的 JDBC URL 方式（tc: 前缀）默认只拉镜像、启动容器，**不会自动执行 initScript 或 schema.sql** —— 这是很多人卡住的第一步。

改用 GenericContainer + withClasspathResourceMapping() 手动挂载 SQL 文件，并通过 withCommand() 调用 psql 执行（适合复杂初始化）
更轻量的做法：用 PostgreSQLContainer 子类，调用 .withInitScript("init.sql") —— 注意该方法只在容器首次启动时生效，且 init.sql 必须在 classpath 根路径下
别把 init.sql 放进 src/test/resources/db/ 就以为能被识别；路径必须是 src/test/resources/init.sql，或显式传入 Paths.get("src/test/resources/db/init.sql") 并用 withFileSystemBind()

本地跑通不代表 CI 能过。Testcontainers 默认尝试连接 unix:///var/run/docker.sock，但多数 CI 环境没暴露该 socket，或权限受限。

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

GitHub Actions 必须加 services 块启用 docker:dind，并设 DOCKER_HOST=tcp://localhost:2376 和 DOCKER_TLS_VERIFY=1
GitLab CI 需配置 docker:dind service，并在 before_script 中运行 docker info 确认连通性 —— 很多人漏掉这步，导致测试直接跳过容器启动，静默失败
如果实在无法启用 Docker，可降级为使用 H2DatabaseContainer 或 EmbeddedPostgres 做单元测试，但要清楚：这不是“容器化测试”，只是绕过问题

默认行为是每次测试都拉最新镜像，既慢又不可控。镜像拉取失败或网络抖动会直接让整个测试套件挂起。

强制指定镜像标签，例如 new PostgreSQLContainer("postgres:15.4")，避免隐式拉 latest
在 CI 前置步骤预拉镜像：docker pull postgres:15.4，然后 Testcontainers 会复用本地镜像
本地开发时，用 TESTCONTAINERS_REUSE=true 环境变量复用已运行容器（需配合 withReuse(true)），但注意：多个测试共用一个容器时，数据库状态会污染，仅适合单测串行场景

真正麻烦的是跨团队协作时，有人本地开了 Docker Desktop，有人用 Colima，有人关了 Linux cgroup v2 —— 这些底层差异会让容器启动行为不一致，却很难在日志里直接看到原因。