告别样板代码：深度解析 Lombok 核心注解 @Builder 与 @RequiredArgsConstructor

在现代 Java 开发中，尤其是结合 Spring Boot 3 和 AI 智能体框架（如 LangChain4j） 的开发中，我们追求的是代码的简洁性、可读性和不可变性。

手动编写构造函数、Setter 方法和复杂的对象初始化代码不仅低效，还容易出错。今天，我们深入探讨 Lombok 提供的两个关键注解：@Builder 和 @RequiredArgsConstructor，看看它们是如何改变我们的编码体验的。

一、 @Builder：像点餐一样优雅地创建对象

1. 核心痛点

假设你有一个复杂的 POJO 或 DTO 类，拥有 10 个以上的字段。

使用无参构造 + Setter：代码散乱，容易漏掉必填字段，且对象在初始化过程中是“不完整”的。
使用全参构造：你根本记不住第 5 个 String 参数是 name 还是 description，传错参数位置是大型翻车现场。

2. 什么是 @Builder？

@Builder 实现了设计模式中的 建造者模式（Builder Pattern）。它让你能以“链式调用”的方式创建对象，代码读起来就像自然语言。

代码示例：

@Builder
@Data
public class WorkflowStateData {
    private String sessionId;
    private List<ChatMessage> messages;
    private List<ToolSpecification> tools;
    
    @Builder.Default
    private Map<String, Object> context = new HashMap<>();
}

调用体验：

WorkflowStateData data = WorkflowStateData.builder()
    .sessionId("ax-789")
    .messages(myList)
    .tools(toolList)
    // 注意：我没写 context，它会使用下面提到的默认值
    .build();

3. 技术细节：@Builder.Default 的必要性

这是一个小白最容易踩的坑。

问题：如果你在类字段上直接写 = new HashMap<>()，Lombok 的 Builder 在构建对象时会忽略这个初始化值，直接给一个 null。
解决方案：必须在字段上加 @Builder.Default。它告诉 Lombok：如果调用者没有显式通过 .context(...) 赋值，请务必使用我定义的默认对象，而不是 null。

二、 @RequiredArgsConstructor：Spring 依赖注入的黄金搭档

1. 核心痛点

在 Spring Boot 中，我们提倡**构造器注入（Constructor Injection）**而不是 @Autowired 字段注入。
但手动写构造器很烦：

@Service
public class AgentService {
    private final ToolRegistry toolRegistry;
    private final AgentWorkflow agentWorkflow;

    public AgentService(ToolRegistry toolRegistry, AgentWorkflow agentWorkflow) {
        this.toolRegistry = toolRegistry;
        this.agentWorkflow = agentWorkflow;
    }
}

每增加一个依赖，你都要改三处代码：声明变量、改构造函数参数、改构造函数体内赋值。

2. 什么是 @RequiredArgsConstructor？

它会为类中所有标记为 final 的字段（或者标记了 @NonNull 的字段）自动生成一个构造函数。

优化后的代码：

@Service
@RequiredArgsConstructor
public class AgentService {
    // 只要标记为 final，Lombok 就会自动将其加入构造函数
    private final ToolRegistry toolRegistry;
    private final AgentWorkflow agentWorkflow;
    private final ObservationRegistry observationRegistry;
}

为什么它是 Spring 注入的最佳实践？

代码极简：配合 final 关键字，一行注解搞定。
不可变性：字段是 final 的，保证了 Bean 在启动后不会被篡改，更安全。
方便测试：不需要启动 Spring 容器也能轻松通过构造函数手动注入 Mock 对象。

三、进阶技巧：两者结合的火花

在 AgentX 框架开发中，我们经常会看到这样的组合：

@Data
@Builder
@RequiredArgsConstructor // 错误警告！
public class MyService { ... }

⚠️ 避坑提醒：
当你同时使用 @Builder 和其他构造器注解（如 @NoArgsConstructor）时，@Builder 会默认失效，因为它找不到合适的构造器。
黄金组合方案：
如果你需要 Builder 模式，同时又需要 Spring 注入或序列化支持，通常建议这样写：

@Data
@Builder
@AllArgsConstructor // 确保全参构造函数存在，供 Builder 使用
@NoArgsConstructor  // 确保无参构造函数存在，供 Jackson/JPA 使用
public class MyDto { ... }

四、总结：设计思想的转变

特性	`@Builder`	`@RequiredArgsConstructor`
主要用途	创建复杂的数据对象 (DTO/Entity)	处理逻辑组件的依赖注入 (Service/Controller)
核心优势	可读性强、防止参数错位	简化依赖注入、强制字段初始化
推荐场景	状态机 State、API 请求体 Request	Spring Bean 的声明与初始化

一句话建议：

如果是拿来装数据的类，请用 @Builder。
如果是拿来写逻辑的类（Spring Service），请用 @RequiredArgsConstructor。

💡 结语

合理利用 Lombok 注解不仅能让你的代码量减少 40% 以上，更重要的是它强制你遵循不可变性和单一职责的设计原则。在开发复杂的 AI Agent 系统时，这种整洁的架构将是你后期排查 Bug 的最后一道防线。

告别样板代码：深度解析 Lombok 核心注解 @Builder 与 @RequiredArgsConstructor