使用 Lombok 的 @Builder 和 @Singular 注解处理 Map 字段时，不应手动编写接收 Builder 的构造函数；Lombok 已自动生成 .build() 方法完成实例构建，手动构造不仅冗余，还会导致无法访问 @Singular 生成的中间 Map 结构。
使用 lombok 的 `@builder` 和 `@singular` 注解处理 `map` 字段时，不应手动编写接收 builder 的构造函数；lombok 已自动生成 `.build()` 方法完成实例构建，手动构造不仅冗余，还会导致无法访问 `@singular` 生成的中间 map 结构。
Lombok 的 @Builder 与 @Singular 组合是处理集合类字段（如 List、Set、Map）的推荐方式，但其设计哲学决定了构建逻辑必须完全交由 Lombok 生成的 build() 方法完成，而非通过自定义构造函数“手动提取” builder 中的字段。
在你的示例中：
@Getter
@Builder
public class WebServiceStatus {
private final String wsdl;
private final String operation;
@Singular
private final Map<String, String> params;
// ❌ 错误：手动构造函数试图直接读取 builder.params
public WebServiceStatus(WebServiceStatusBuilder builder) {
this.wsdl = builder.wsdl;
this.operation = builder.operation;
this.params = builder.params; // 编译失败！builder 中无 params 字段
}
}Lombok 对 @Singular Map<k></k> 的实现机制是分拆存储：它将键值对分别存为两个私有列表 params$key 和 params$value，并在 build() 调用时动态合并为 Map。因此，WebServiceStatusBuilder 类中确实不暴露 params 字段或 getter——这是有意为之的设计，目的是避免用户误操作（如中途修改未构建完成的 Map），同时提升内存与性能效率（延迟合并、避免中间 Map 实例化）。
✅ 正确用法：彻底移除自定义构造函数，直接使用标准 Builder 链式调用：
WebServiceStatus status = WebServiceStatus.builder()
.wsdl("http://example.com/service?wsdl")
.operation("getInfo")
.param("timeout", "3000") // ← @Singular 为 Map 自动生成的便捷方法
.param("retry", "3")
.build(); // ← 唯一且推荐的构建入口?
@Singular为Map<string string></string>自动生成了形如param(String key, String value)的方法（方法名默认为字段名去复数后缀，此处params→param），每次调用向内部键/值列表追加一对元素；最终build()内部统一组装为不可变LinkedHashMap（保持插入顺序）。
⚠️ 注意事项：
-
不要尝试为
@Singular Map添加自定义 getter（如getParams()或getParamsBuilder()）：这既无法绕过 Lombok 的分拆机制，又破坏封装性，还可能引发线程安全问题； - 若业务确需在构建中途访问或修改 Map 状态（例如条件性注入参数），说明场景已超出
@Singular的通用设计范畴，此时应放弃@Builder + @Singular组合，改用手写 Builder 模式，或使用@Builder(builderMethodName = "hiddenBuilder")配合自定义builder()工厂方法+手动维护 Map； - 可通过
lombok.delombok命令生成反编译代码，查看 Lombok 实际生成的 Builder 结构（含params$key/params$value字段及param()方法），加深理解。
总结：Lombok 的 @Builder 是“全有或全无”的契约——你信任它生成完整、安全、高效的构建流程，就绝不应介入中间状态；所谓“无法获取 params”，本质是设计上主动屏蔽了不安全的访问路径。删掉手写的构造函数，拥抱 .build()，既是最佳实践，也是与 Lombok 协同工作的前提。
