Lombok 不支持直接为 @RequiredArgsConstructor 等注解生成的构造器添加 JavaDoc；JavaDoc 必须显式写在构造器声明处，而 Lombok 不会将类上方的 JavaDoc 自动“转发”给生成的构造器。
lombok 不支持直接为 `@requiredargsconstructor` 等注解生成的构造器添加 javadoc；javadoc 必须显式写在构造器声明处，而 lombok 不会将类上方的 javadoc 自动“转发”给生成的构造器。
在 Java 开发中，为公共 API 编写清晰、规范的 JavaDoc 是提升可维护性与协作效率的关键实践。然而，当使用 Lombok 简化样板代码（如自动生成构造器）时，一个常见误区是试图通过在注解上方添加 JavaDoc 来描述其生成的构造器，例如：
/**
* Custom constructor used only in <code>OrderMapper</code>.
* @param totalValue single parameter necessary to pass on the information to frontend
*/
@RequiredArgsConstructor
public class Order {
private final BigDecimal totalValue;
}遗憾的是，这段 JavaDoc 不会被 Javadoc 工具识别为构造器文档——它实际绑定到 Order 类本身，而非 Lombok 自动生成的 public Order(BigDecimal totalValue) 构造器。
为什么 Lombok 不支持“注解上方 JavaDoc → 生成构造器 JavaDoc”？
Lombok 核心维护者明确指出，该行为在当前及可预见的未来均不可行，主要原因包括：
- ✅ 语义模糊性：一个注解（如 @Getter 在类上）可能生成多个成员（多个 getter 方法），无法无歧义地将单段 JavaDoc 分配给多个目标；
- ✅ 编译器时机限制：Javac 在早期解析阶段即绑定 JavaDoc 到 AST 节点，而 Lombok 的代码生成发生在后续注解处理阶段，强行桥接易引发兼容性问题与难以复现的 bug；
- ✅ 违背 Java 社区惯例：标准 Java 风格要求 JavaDoc 紧邻被文档化的元素（如 /** ... */ public void method() {}），而非置于修饰它的注解之前。若 Lombok 改变此约定，将造成静默行为变更（breaking change），且测试难以覆盖；
- ✅ 可发现性与可维护性差：即使引入特殊语法（如双 JavaDoc 块或分隔符），也会显著增加学习成本与误用风险，不符合 Lombok “隐形但可靠”的设计哲学。
正确可行的替代方案
✅ 方案一：放弃 Lombok，手写带 JavaDoc 的构造器（推荐用于关键 API）
当构造器需对外暴露明确契约（如 DTO 映射、框架集成点）时，它已超出“纯样板”范畴，应显式编写：
立即学习“Java免费学习笔记（深入）”；
/**
* Constructs an {@code Order} for frontend consumption via {@link OrderMapper}.
*
* @param totalValue the monetary value of this order, required and non-null
* @throws NullPointerException if {@code totalValue} is null
*/
public Order(BigDecimal totalValue) {
this.totalValue = Objects.requireNonNull(totalValue, "totalValue must not be null");
}✅ 优势：完全可控、符合 Javadoc 规范、IDE 可索引、生成文档精准；
⚠️ 注意：需同步移除 @RequiredArgsConstructor，避免编译冲突。
✅ 方案二：利用 Lombok 的 JavaDoc 拆分机制（实验性，有限支持）
Lombok 支持对字段级 JavaDoc 使用 -- SETTER -- / -- GETTER -- 等分隔符，实现多段文档分发。理论上可扩展至类级（如 -- CONSTRUCTOR --），但截至 Lombok 1.18.32，该特性尚未实现且无官方路线图支持。以下仅为概念示意（当前无效）：
/**
* Represents a customer order.
* -- CONSTRUCTOR --
* Creates an order with validated total value for frontend use.
* @param totalValue monetary amount; must be positive
*/
@RequiredArgsConstructor
public class Order { /* ... */ }? 结论：切勿依赖此写法——它不工作，也不在短期开发计划中。
✅ 方案三：补充说明性注释 + 外部文档
若构造器逻辑简单且非核心 API，可在类 JavaDoc 中明确说明构造器用途，并辅以 @see 指向相关类或文档：
/**
* Immutable order representation.
* <p>
* This class uses {@link RequiredArgsConstructor} to generate a constructor
* accepting all {@code final} fields. The generated constructor is intended
* exclusively for use by {@link OrderMapper}.
*
* @see OrderMapper
* @see <a href="https://projectlombok.org/features/constructor">Lombok @RequiredArgsConstructor</a>
*/
@RequiredArgsConstructor
public class Order {
private final BigDecimal totalValue;
}总结与最佳实践
| 场景 | 推荐做法 |
|---|---|
| 构造器是公开 API 的一部分（如被其他模块/框架直接调用） | ✅ 手写构造器 + 完整 JavaDoc，弃用 @RequiredArgsConstructor |
| 构造器仅用于内部/框架注入（如 Spring Bean 创建） | ✅ 保留 Lombok，用类级 JavaDoc 清晰说明用途，无需强制文档化构造器 |
| 追求 100% 自动生成 + 完整 JavaDoc | ❌ 当前技术不可行；需接受权衡：要么牺牲部分自动化，要么接受文档粒度降级 |
? 关键认知：Lombok 的定位是消除“机械重复”，而非替代“设计决策”。当文档成为契约的一部分，显式编码就是专业性的体现。
