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
    @Setter
    private 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;
    
    @NonNull
    private 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;
    
    @Singular
    private 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 {
    @Cleanup
    FileInputStream 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 是工具，理解生成的代码才能用好它！