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 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
/**
* 订单实体类。
*/
public class Order {
private final BigDecimal totalValue;
/**
* 专供 OrderMapper 使用的构造方法。
* <p>该构造方法仅接收前端必需的总金额字段，确保轻量且语义明确。</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 是利器，但不应以牺牲可读性与文档完整性为代价。真正专业的代码，永远在“简洁”与“明确”之间取得精准平衡。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
