当前位置：首页 > news >正文

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

news 2025/9/29 6:26:40

使用说明：本手册按功能分类整理 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 { /* ... */ }