Testcontainers中withNetwork与withNetworkMode区别及默认网络咨询

withNetwork 与 withNetworkMode 的区别及适用场景 #

核心区别 #

• withNetwork：Testcontainers 自身封装的网络管理 API，用于创建或复用 Testcontainers 管控的自定义网络。
  • 可通过 Network.newNetwork() 创建专属网络，再用 container.withNetwork(network) 将容器加入该网络
  • 网络生命周期由 Testcontainers 管理（默认随测试结束销毁，可配置持久化）
  • 容器间能通过容器名称直接通信（Testcontainers 自动维护 DNS 解析）
• withNetworkMode：直接对接 Docker 原生网络模式，完全遵循 Docker 自身的网络规则。
  • 参数为 Docker 原生网络模式字符串，如 bridge、host 等
  • 网络不由 Testcontainers 管控，生命周期遵循 Docker 自身逻辑

适用场景 #

• 选择 withNetwork 的场景：
  • 需在多个测试容器间建立隔离的专属通信环境，比如微服务集成测试中，让服务容器与数据库容器在私有网络内通信，避免和其他测试环境冲突
  • 希望容器间通过名称直接访问，无需手动配置端口映射或 IP
• 选择 withNetworkMode 的场景：
  • 需让测试容器直接使用宿主机网络栈（如 host 模式），绕过端口映射，适合测试需要绑定宿主机特定端口的服务
  • 要复用 Docker 已存在的自定义网络，而非让 Testcontainers 创建新网络
  • 需要将容器加入 Docker 默认的 bridge 网络，和宿主机上其他手动启动的容器通信

org.testcontainers.containers.Network.SHARED 的用途 #

这是 Testcontainers 内置的全局共享网络，所有 Testcontainers 容器默认都会加入该网络（除非显式指定其他网络）。

• 核心用途是跨测试类/测试套件共享容器：比如多个测试类都需要用到同一个 Redis 容器，无需为每个测试类创建新网络，只要让 Redis 容器和测试容器都使用 SHARED 网络，就能直接互相访问
• 省去了手动创建共享网络的步骤，简化跨测试的容器协作逻辑
• 注意：该网络是全局的，所有测试容器都会接入，需避免容器名称冲突

withNetworkMode 支持的默认网络类型及适用场景 #

1. bridge（Docker 默认桥接网络） #

• Docker 默认的网络模式，容器通过 NAT 方式与宿主机通信
• 适用场景：需要让测试容器和宿主机、或宿主机上其他非 Testcontainers 管理的容器通信，同时保持容器间的基本隔离

2. host（宿主机网络模式） #

• 容器直接使用宿主机的网络栈，无独立网络命名空间
• 适用场景：测试需要绑定宿主机特定端口的服务，或需要容器直接访问宿主机网络资源（如本地数据库），无需端口映射

3. none（无网络模式） #

• 容器无网络连接，完全隔离网络环境
• 适用场景：测试离线状态下的应用逻辑，比如应用在无网络时的降级处理

4. container:<container-name/id>（容器网络模式） #

• 目标容器与指定的已有容器共享同一个网络命名空间
• 适用场景：测试需要和另一个容器共享网络栈的场景，比如让测试容器直接访问目标容器的 localhost 服务（如监控容器采集另一个容器的进程 metrics）

内容的提问来源于stack exchange，提问作者curiousengineer