6、Lombok-速查手册：常用注解语法与生成代码对照表

使用说明：本手册按功能分类整理 Lombok 常用注解，包含完整参数说明、默认行为和生成代码示例，便于开发时快速查阅。

---

1. 基础 POJO、DTO、VO 注解

@Getter / @Setter

注解位置

• 类级别：作用于所有非静态字段
• 字段级别：作用于单个字段

参数说明

参数	类型	默认值	说明
value	AccessLevel	PUBLIC	生成方法的访问级别
onMethod_	Annotation[]	{}	为生成的方法添加注解（Java 8+ 语法）
onParam_	Annotation[]	{}	为 setter 参数添加注解

💡 AccessLevel 可选值：PUBLIC、PROTECTED、PACKAGE、PRIVATE、NONE

使用示例

// 类级别
@Getter
@Setter
public class User {private String name;private int age;
}// 字段级别 + 自定义访问级别
public class SecureUser {@Getter(AccessLevel.PROTECTED)@Setter(AccessLevel.PRIVATE)private String password;@Getter@Setterprivate String username;
}

生成代码

// User 类生成
public String getName() { return this.name; }
public void setName(String name) { this.name = name; }
public int getAge() { return this.age; }
public void setAge(int age) { this.age = age; }// SecureUser 类生成
protected String getPassword() { return this.password; }
private void setPassword(String password) { this.password = password; }
public String getUsername() { return this.username; }
public void setUsername(String username) { this.username = username; }

---

@ToString

参数说明

参数	类型	默认值	说明
includeFieldNames	boolean	true	是否包含字段名
exclude	String[]	{}	排除的字段名
of	String[]	{}	仅包含的字段（优先级高于 exclude）
callSuper	boolean	false	是否调用父类 toString()
doNotUseGetters	boolean	false	直接访问字段而非 getter

使用示例

@ToString(exclude = {"password", "secretKey"})
public class User {private String username;private String password;private String secretKey;private int loginCount;
}@ToString(of = {"id", "name"}, callSuper = true)
public class Employee extends Person {private Long id;private String name;private Double salary; // 不会出现在 toString 中
}

生成代码

// User 类生成
@Override
public String toString() {return "User(username=" + this.username + ", loginCount=" + this.loginCount + ")";
}// Employee 类生成
@Override
public String toString() {return super.toString() + "Employee(id=" + this.id + ", name=" + this.name + ")";
}

---

@EqualsAndHashCode

参数说明

参数	类型	默认值	说明
exclude	String[]	{}	排除的字段
of	String[]	{}	仅包含的字段
callSuper	boolean	false	是否包含父类字段
doNotUseGetters	boolean	false	直接访问字段
cacheStrategy	CacheStrategy	CACHE_NOTHING	缓存策略（高级用法）

使用示例

@EqualsAndHashCode(exclude = {"lastModified"})
public class Article {private Long id;private String title;private LocalDateTime lastModified;
}@EqualsAndHashCode(callSuper = true)
public class Dog extends Animal {private String breed;
}

生成代码

// Article 类生成
@Override
public boolean equals(Object o) {if (o == this) return true;if (!(o instanceof Article)) return false;Article other = (Article) o;if (!other.canEqual(this)) return false;final Object this$id = this.id;final Object other$id = other.id;if (this$id == null ? other$id != null : !this$id.equals(other$id)) return false;final Object this$title = this.title;final Object other$title = other.title;if (this$title == null ? other$title != null : !this$title.equals(other$title)) return false;return true;
}@Override
public int hashCode() {final int PRIME = 59;int result = 1;result = result * PRIME + (this.id == null ? 43 : this.id.hashCode());result = result * PRIME + (this.title == null ? 43 : this.title.hashCode());return result;
}// canEqual 方法（用于继承场景）
protected boolean canEqual(Object other) {return other instanceof Article;
}

---

2. 组合注解

@Data

等价注解组合

@Getter
@Setter
@ToString
@EqualsAndHashCode
@RequiredArgsConstructor

注意事项

• 不生成无参构造器！需要额外添加 @NoArgsConstructor
• 所有字段都参与 equals/hashCode/toString

使用示例

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Product {private Long id;private String name;private Double price;
}

生成代码

包含上述所有注解的生成内容，外加：

// 无参构造器
public Product() {}// 全参构造器
public Product(Long id, String name, Double price) {this.id = id;this.name = name;this.price = price;
}

---

@Value

特点

• 创建不可变类
• 所有字段自动变为 private final
• 只生成 getter，不生成 setter
• 生成全参构造器

使用示例

@Value
public class Point {int x;int y;
}

生成代码

public final class Point {private final int x;private final int y;public Point(int x, int y) {this.x = x;this.y = y;}public int getX() { return this.x; }public int getY() { return this.y; }// toString, equals, hashCode 方法...// 注意：没有 setter 方法！
}

---

3. 构造器注解

@NoArgsConstructor

参数说明

参数	类型	默认值	说明
access	AccessLevel	PUBLIC	构造器访问级别
force	boolean	false	强制生成（即使有 final 字段）

使用示例

@NoArgsConstructor
public class User {private String name;
}@NoArgsConstructor(force = true)
public class ImmutableUser {private final String id = "default";private final String name;
}

生成代码

// User 类
public User() {}// ImmutableUser 类（force = true）
public ImmutableUser() {// final 字段被强制初始化为默认值this.name = null; // 注意：这可能导致 NullPointerException
}

---

@AllArgsConstructor

参数说明

参数	类型	默认值	说明
access	AccessLevel	PUBLIC	构造器访问级别
staticName	String	""	生成静态工厂方法

使用示例

@AllArgsConstructor(staticName = "of")
public class Coordinate {private int x;private int y;
}

生成代码

// 常规构造器
public Coordinate(int x, int y) {this.x = x;this.y = y;
}// 静态工厂方法（staticName = "of"）
public static Coordinate of(int x, int y) {return new Coordinate(x, y);
}

---

@RequiredArgsConstructor

生成规则

为以下字段生成构造器：

• 所有 final 字段
• 所有标记 @NonNull 的字段

使用示例

@RequiredArgsConstructor
public class UserService {private final UserRepository userRepository;@NonNullprivate String defaultRole;
}

生成代码

public UserService(UserRepository userRepository, String defaultRole) {this.userRepository = userRepository;if (defaultRole == null) {throw new NullPointerException("defaultRole is marked non-null but is null");}this.defaultRole = defaultRole;
}

---

4. Builder 模式注解

@Builder

参数说明

参数	类型	默认值	说明
builderMethodName	String	"builder"	Builder 方法名
buildMethodName	String	"build"	build 方法名
toBuilder	boolean	false	生成 toBuilder 方法

使用示例

@Builder(builderMethodName = "newBuilder", buildMethodName = "create")
public class Order {private String orderId;private Double amount;
}

生成代码

// Builder 内部类
public static class OrderBuilder {private String orderId;private Double amount;OrderBuilder() {}public OrderBuilder orderId(String orderId) {this.orderId = orderId;return this;}public OrderBuilder amount(Double amount) {this.amount = amount;return this;}public Order create() { // buildMethodName = "create"return new Order(orderId, amount);}
}// Builder 方法
public static OrderBuilder newBuilder() { // builderMethodName = "newBuilder"return new OrderBuilder();
}

---

@Singular（集合字段支持）

支持的集合类型

• List<T> → element(T) 和 elements(Collection<T>)
• Set<T> → element(T) 和 elements(Collection<T>)
• Map<K,V> → entry(K, V) 和 entries(Map<K,V>)

使用示例

@Builder
public class ShoppingCart {@Singular("product")private List<String> products;@Singularprivate Map<String, Integer> quantities;
}

使用方式

ShoppingCart cart = ShoppingCart.builder().product("Laptop")           // 添加单个元素.product("Mouse")            // 继续添加.products(Arrays.asList("Keyboard", "Monitor")) // 批量添加.entry("Laptop", 1)          // Map 单个条目.entries(Map.of("Mouse", 2, "Keyboard", 1))     // Map 批量.build();

---

5. 日志注解

@Slf4j

生成代码

// 源码
@Slf4j
public class MyService {public void doSomething() {log.info("Doing something");}
}// 生成
public class MyService {private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(MyService.class);public void doSomething() {log.info("Doing something");}
}

其他日志框架支持

注解	生成的日志实例类型
@Log	java.util.logging.Logger
@Log4j	org.apache.log4j.Logger
@Log4j2	org.apache.logging.log4j.Logger
@CommonsLog	org.apache.commons.logging.Log
@JBossLog	org.jboss.logging.Logger

---

6. 高级功能注解

@SneakyThrows

参数说明

参数	类型	默认值	说明
value	Class<? extends Throwable>[]	Exception.class	要 sneaky 抛出的异常类型

使用示例

@SneakyThrows
public String readFile(String path) {return Files.readString(Paths.get(path)); // IOException
}@SneakyThrows({IOException.class, SQLException.class})
public void doDatabaseOperation() {// 可能抛出两种检查异常
}

生成代码

public String readFile(String path) {try {return Files.readString(Paths.get(path));} catch (IOException e) {throw lombok.Lombok.sneakyThrow(e);}
}

---

@Cleanup

参数说明

参数	类型	默认值	说明
value	String	"close"	清理方法名

使用示例

public byte[] readFile(String path) throws IOException {@CleanupFileInputStream fis = new FileInputStream(path);return fis.readAllBytes();
}public void customResource() {@Cleanup("destroy")MyResource resource = new MyResource();// 使用 resource
} // 自动调用 resource.destroy()

生成代码

public byte[] readFile(String path) throws IOException {FileInputStream fis = new FileInputStream(path);try {return fis.readAllBytes();} finally {if (fis != null) {fis.close();}}
}

---

@With

使用示例

@With
public class Point {private final int x;private final int y;
}

生成代码

public Point withX(int x) {return this.x == x ? this : new Point(x, this.y);
}public Point withY(int y) {return this.y == y ? this : new Point(this.x, y);
}

---

7. 快速参考表

注解	主要用途	关键参数	注意事项
@Getter/@Setter	生成访问器	value(AccessLevel)	可控制访问级别
@ToString	生成 toString	exclude, of, callSuper	敏感字段务必排除
@EqualsAndHashCode	生成相等性方法	exclude, of, callSuper	继承时设 callSuper=true
@Data	POJO 万能注解	无	不生成无参构造器
@Value	不可变对象	无	字段自动 final
@NoArgsConstructor	无参构造器	force	JPA/JSON 必需
@AllArgsConstructor	全参构造器	staticName	可生成静态工厂
@RequiredArgsConstructor	必需字段构造器	无	Spring 构造器注入推荐
@Builder	Builder 模式	builderMethodName, toBuilder	复杂对象创建首选
@Singular	集合 Builder 支持	无	配合 @Builder 使用
@Slf4j	日志实例	无	推荐 SLF4J
@SneakyThrows	绕过检查异常	value	谨慎使用
@Cleanup	自动资源管理	value(方法名)	替代 try-with-resources
@With	不可变副本	无	函数式编程友好

---

8. 使用建议

✅ 推荐组合

// DTO 标准写法
@Data
@NoArgsConstructor
@AllArgsConstructor
@ToString(exclude = "password")
public class UserDTO {// ...
}// 不可变配置类
@Value
@Builder
public class DatabaseConfig {// ...
}

❌ 避免组合

// 危险：JPA 实体不要用 @Data
@Data
@Entity
public class User { /* ... */ }// 冗余：@Data 已包含 @Getter/@Setter
@Data
@Getter
@Setter
public class Product { /* ... */ }

💡 记住：Lombok 是工具，理解生成的代码才能用好它！