Lombok 注解（如 @RequiredArgsConstructor）本身无法直接关联 Javadoc；Javadoc 必须显式编写在生成的目标元素（如构造方法）上，而不能仅写在注解上方——这是由 Java 编译器机制和 Lombok 设计原则共同决定的。
lombok 注解（如 `@requiredargsconstructor`）本身无法直接关联 javadoc；javadoc 必须显式编写在生成的目标元素（如构造方法）上，而不能仅写在注解上方——这是由 java 编译器机制和 lombok 设计原则共同决定的。
在 Java 开发中，Javadoc 的绑定对象是源码中实际声明的程序元素（如类、方法、字段），而非注解本身。Lombok 通过注解处理器在编译期动态生成代码（例如构造方法），但这些生成的元素不继承其所在类或注解上方的 Javadoc。因此，以下写法无效：
/**
* 自定义构造方法，专用于 OrderMapper。
* @param totalValue 前端所需的核心数值
*/
@RequiredArgsConstructor
public class Order {
private final BigDecimal totalValue;
}尽管语法合法、编译无误，但生成的构造方法 public Order(BigDecimal totalValue) 不会携带上述 Javadoc，Javadoc 工具（如 javadoc 命令或 IDE 提示）也无法识别。
✅ 正确做法：显式编写构造方法（放弃 Lombok 自动生成）
若需完整、可文档化的构造方法，应手动实现并添加 Javadoc：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
/**
* 订单实体类。
*/
public class Order {
private final BigDecimal totalValue;
/**
* 专供 OrderMapper 使用的构造方法。
* <p>该构造方法仅接收前端必需的总金额字段，确保轻量且语义明确。</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/c1c2c2ed740f" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Java免费学习笔记（深入）</a>”；</p>
*
* @param totalValue 订单总金额（不可为 null）
* @see OrderMapper
*/
public Order(BigDecimal totalValue) {
this.totalValue = Objects.requireNonNull(totalValue, "totalValue must not be null");
}
// 可选：保留 Lombok 的其他能力（如 getter、builder）
@Getter
public static class Builder {
private BigDecimal totalValue;
public Builder totalValue(BigDecimal totalValue) {
this.totalValue = totalValue;
return this;
}
public Order build() {
return new Order(totalValue);
}
}
}✅ 优势：
- Javadoc 完全可控，支持 @param、@see、HTML 标签等全部标准特性；
- IDE 智能提示、文档生成工具（如 Gradle javadoc 任务）均可正确解析；
- 符合 Java 社区通用规范，团队协作无障碍。
⚠️ 注意事项与替代思路
- 不要依赖“注解上方 Javadoc 绑定到生成代码”：这在当前 Lombok（v1.18.x / v1.20.x）中完全不被支持，且官方明确表示暂无计划实现（参见 Lombok Issue #1269 及核心维护者说明）。
- 字段级 Javadoc 分割（实验性）不适用于构造方法：虽然 Lombok 支持用 -- GETTER -- / -- SETTER -- 分割字段 Javadoc 并分别应用到 getter/setter，但目前无 -- CONSTRUCTOR -- 语法支持，且即使未来加入，也会面临 @param 冗余、多行描述截断等设计难题。
- 权衡“ boilerplate vs. documentation”：Lombok 的本质是消除重复但无业务含义的样板代码。一旦你对构造方法有明确语义要求（如用途限定、参数约束、跨模块引用），它就已超出“纯 boilerplate”范畴——此时手写反而是更清晰、更可持续的选择。
? 总结
Javadoc 不是装饰，而是契约。
当构造方法需要承载明确的 API 含义时，请主动放弃 @RequiredArgsConstructor，转而手写带完整 Javadoc 的构造方法。这不是倒退，而是对可维护性与协作效率的尊重。Lombok 是利器，但不应以牺牲可读性与文档完整性为代价。真正专业的代码，永远在“简洁”与“明确”之间取得精准平衡。
