Testcontainers-dotnet 扩展方法使用注意事项：构建器模式与不可变性设计

在 Testcontainers-dotnet 项目中，容器配置的构建过程采用了一种特殊的不可变设计模式。这种设计虽然提供了强大的灵活性和可重用性，但也可能让初次接触该库的开发者感到困惑。

构建器模式的核心机制

Testcontainers-dotnet 的构建器类（如 MsSqlBuilder）实现了一种函数式编程风格的不可变设计。当调用 With 开头的扩展方法（如 WithNetwork 或 WithNetworkAliases）时，这些方法并不会修改原有构建器实例的内部状态，而是会：

1. 创建一个新的构建器实例
2. 将新配置应用于这个新实例
3. 返回这个新实例

这种设计遵循了不可变对象的原则，确保了配置过程的安全性和可预测性。

典型使用场景分析

正确的使用方式应该是链式调用或显式赋值：

// 链式调用（推荐）
var container = new MsSqlBuilder()
    .WithNetwork(network)
    .WithNetworkAliases("test-mssql")
    .Build();

// 或者显式赋值
var builder = new MsSqlBuilder();
builder = builder.WithNetwork(network);
builder = builder.WithNetworkAliases("test-mssql");
var container = builder.Build();

设计优势解析

这种看似"不便"的设计实际上带来了几个重要优势：

1. 配置重用：可以轻松创建基础配置，然后派生出多个变体

   var baseConfig = new MsSqlBuilder().WithImage("mssql:2019");
   
   var devConfig = baseConfig.WithNetwork(devNetwork);
   var testConfig = baseConfig.WithNetwork(testNetwork);
   

2. 线程安全：由于配置过程不修改共享状态，可以安全地在多线程环境中使用

3. 调试友好：每个配置步骤都是独立的，便于跟踪和调试

常见误区与解决方案

开发者常犯的错误是忽略方法返回值：

// 错误示例：配置不会生效
var builder = new MsSqlBuilder();
builder.WithNetwork(network);  // 返回值被忽略

解决方案很简单：要么使用链式调用，要么确保接收每个配置方法的返回值。

最佳实践建议

1. 优先使用链式调用语法，既简洁又能避免错误
2. 当需要条件配置时，可以使用中间变量但要注意赋值

   var builder = new MsSqlBuilder();
   if (useNetwork) {
       builder = builder.WithNetwork(network);
   }
   

3. 复杂配置可以考虑使用配置工厂方法封装

理解这一设计模式后，开发者就能充分利用 Testcontainers-dotnet 提供的灵活配置能力，同时避免常见的配置失效问题。