本文介绍如何在 Lombok Builder 模式下为同一字段（如 metric）提供多个构建器参数名（如 state），通过自定义 @Builder 构造函数实现灵活、类型安全的对象构建，无需依赖 JSON 序列化注解。
本文介绍如何在 lombok builder 模式下为同一字段（如 `metric`）提供多个构建器参数名（如 `state`），通过自定义 `@builder` 构造函数实现灵活、类型安全的对象构建，无需依赖 json 序列化注解。
在使用 Lombok 的 @Builder 时，字段名默认与构建器方法名严格绑定（如字段 metric → .metric(...)）。但实际开发中常需支持语义等价的别名（如 state 作为 metric 的同义构建入口），尤其在对接不同 API 命名规范或领域术语时。@JsonAlias 等 Jackson 注解仅作用于 JSON 序列化/反序列化，对 Builder 构建过程完全无效——这是初学者常见误区。
正确解法是：放弃对 Source 类整体使用 @Builder，转而为其显式声明一个带重载参数的构造函数，并用 @Builder 标注该构造函数。这样可自由定义多个参数名，由构造函数逻辑统一归一化赋值。
以下是完整、可运行的实现方案：
import lombok.Builder;
import lombok.Value;
public class BuilderWithAliasExample {
@Value
@Builder
public static class Input {
String name;
Source source;
}
@Value
public static class Source {
Metric metric;
// ✅ 关键：自定义构造函数，接受 metric 和 state 两个参数
// 两者互斥，优先使用非 null 的值
@Builder
public Source(Metric metric, Metric state) {
this.metric = (metric != null) ? metric : state;
}
}
@Value
@Builder
public static class Metric {
String ref;
}
// ✅ 两种构建方式均合法且类型安全
public static void main(String[] args) {
// 方式1：使用原始字段名 metric
Input input1 = Input.builder()
.name("state")
.source(Source.builder()
.metric(Metric.builder().ref("ref1").build())
.build())
.build();
// 方式2：使用别名 state（效果完全等同）
Input input2 = Input.builder()
.name("state")
.source(Source.builder()
.state(Metric.builder().ref("ref2").build()) // ← 别名生效！
.build())
.build();
System.out.println(input1); // Input(name=state, source=Source(metric=Metric(ref=ref1)))
System.out.println(input2); // Input(name=state, source=Source(metric=Metric(ref=ref2)))
}
}⚠️ 注意事项：
- Source 类不可再加 @Builder 类注解，否则会与构造函数上的 @Builder 冲突，导致编译错误或生成冗余 builder；
- 构造函数中需显式处理参数优先级（如 metric 优先于 state），避免 null 覆盖有效值；
- 所有别名参数必须与目标字段类型一致（此处均为 Metric），确保类型安全；
- 若需支持更多别名（如 value, payload），只需在构造函数中增加对应参数并更新合并逻辑即可。
该方案完全脱离序列化框架约束，在纯对象构建阶段即实现语义别名，兼具简洁性、可读性与健壮性，是 Lombok 高级 Builder 场景的标准实践。
