Lombok 注解简介

Posted 2021-02-01 zhuxudong

Lombok

• @AllArgsConstructor

/**
 * 生成一个包含所有属性的构造函数
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface AllArgsConstructor {
    /**
     * 如果设置了该属性，则生成的构造函数将被设置为 private，并增加一个静态的方法来创建实例，
     * 静态方法将包含构造函数的所有属性，静态方法的名称为 staticName 的属性值。
     */
    String staticName() default "";

    AnyAnnotation[] onConstructor() default {};

    /**
     * 生成构造函数的访问级别，默认是 PUBLIC
     */
    AccessLevel access() default lombok.AccessLevel.PUBLIC;

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}
}

• @RequiredArgsConstructor

/**
 * 生成一个包含所有 final 属性或有约束的属性【@NonNull】的构造函数
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface RequiredArgsConstructor {
    /**
     * 如果设置了该属性，则生成的构造函数将被设置为 private，并增加一个静态的方法来创建实例，
     * 静态方法将包含构造函数的所有属性，静态方法的名称为 staticName 的属性值。
     */
    String staticName() default "";

    AnyAnnotation[] onConstructor() default {};

    /**
     * 生成构造函数的访问级别，默认是 PUBLIC
     */
    AccessLevel access() default lombok.AccessLevel.PUBLIC;

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}
}

• @NoArgsConstructor

/**
 * 尝试生成一个无参数的构造函数
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface NoArgsConstructor {
    /**
     * 如果设置了该属性，则生成的构造函数将被设置为 private，并增加一个静态的方法来创建实例，
     * 静态方法将包含构造函数的所有属性，静态方法的名称为 staticName 的属性值。
     */
    String staticName() default "";

    AnyAnnotation[] onConstructor() default {};

    /**
     * 生成构造函数的访问级别，默认是 PUBLIC
     */
    AccessLevel access() default lombok.AccessLevel.PUBLIC;

    /**
     * 如果存在 final 属性，则无法生成无参数的构造函数【编译失败】，如果将 force 设置为 true，
     * 则所有的 final 属性将被初始化为默认值【0 / null / false】.
     */
    boolean force() default false;

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}
}

• @Getter

/**
 * 如果该注解放置在目标属性上，则会为该属性生成一个标准的 get 方法，
 * 如果该注解放置在类上，则会为类中的每一个非静态属性生成一个标准的  get 方法。
 */
@Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface Getter {
    /**
     * 生成 get 方法的访问级别，默认是 PUBLIC
     */
    lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC;

    AnyAnnotation[] onMethod() default {};

    boolean lazy() default false;

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}
}

• @Setter

/**
 * 如果该注解放置在目标属性上，则会为该属性生成一个标准的 set 方法，
 * 如果该注解放置在类上，则会为类中的每一个非静态属性生成一个标准的  set 方法。
 */
@Target({ElementType.FIELD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface Setter {
    /**
     * 生成 set 方法的访问级别，默认是 PUBLIC
     */
    lombok.AccessLevel value() default lombok.AccessLevel.PUBLIC;

    AnyAnnotation[] onMethod() default {};

    AnyAnnotation[] onParam() default {};

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}
}

• @EqualsAndHashCode

/**
 * 为所有的相关属性生成 hashCode 和 equals 方法
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface EqualsAndHashCode {
    /**
     * 生成 hashCode 和 equals 方法时，需要排除的属性列表
     */
    String[] exclude() default {};

    /**
     * 显式列出需要包含的属性列表，通常非静态 static 和非瞬态 transient 的属性都作为比较目标
     */
    String[] of() default {};

    /**
     * 计算 hashCode 值之前，首先调用父类的 hashCode 方法
     */
    boolean callSuper() default false;

    /**
     * 默认情况下，将调用 get 方法来读取属性值
     */
    boolean doNotUseGetters() default false;

    AnyAnnotation[] onParam() default {};

    @Deprecated
    @Retention(RetentionPolicy.SOURCE)
    @Target({})
    @interface AnyAnnotation {}

    /**
     * 只包含使用 @EqualsAndHashCode.Include 注解标记的所有属性
     */
    boolean onlyExplicitlyIncluded() default false;

    /**
     * 不包含此单个属性值
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.SOURCE)
    public @interface Exclude {}

    /**
     * 包含此单个属性值
     */
    @Target({ElementType.FIELD, ElementType.METHOD})
    @Retention(RetentionPolicy.SOURCE)
    public @interface Include {
        /** Defaults to the method name of the annotated member. If on a method and the name equals the name of a default-included field, this member takes its place. */
        String replaces() default "";
    }
}

• @ToString

/**
 * 为所有的相关属性生成 toString() 方法
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface ToString {
    /**
     * toString() 方法返回的字符串中是否包含属性名称
     */
    boolean includeFieldNames() default true;

    /**
     * 生成 toString() 方法时，需要排除的属性列表
     */
    String[] exclude() default {};

    /**
     * 生成 toString() 方法时，需要包含的属性列表
     */
    String[] of() default {};

    /**
     * 生成 toString() 方法时，是否优先调用父类的 toString()
     */
    boolean callSuper() default false;

    /**
     * 默认情况下，将调用 get 方法来读取属性值
     */
    boolean doNotUseGetters() default false;

    /**
     * 只包含使用 @ToString.Include 注解标记的所有属性
     */
    boolean onlyExplicitlyIncluded() default false;

    /**
     * 显式排除此属性
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.SOURCE)
    public @interface Exclude {}

    /**
     * 显式包含此属性
     */
    @Target({ElementType.FIELD, ElementType.METHOD})
    @Retention(RetentionPolicy.SOURCE)
    public @interface Include {
        /** 更高的 rank 优先打印，相同 rank 的属性按照源代码中的声明顺序打印 */
        int rank() default 0;

        /** 输出的属性名称 */
        String name() default "";
    }
}

• @NonNull

/**
 * 如果该注解放置在参数上，则在构造函数或方法体执行前将会增加目标参数的 null 校验。
 * 如果该注解放置在属性上，则对该属性的写操作都将添加 null 校验。
 */
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE, ElementType.TYPE_USE})
@Retention(RetentionPolicy.CLASS)
@Documented
public @interface NonNull {
}

• @Data

/**
 * 等价于 @Getter @Setter @RequiredArgsConstructor @ToString @EqualsAndHashCode.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface Data {
    /**
     * 如果设置了该属性，则生成的构造函数将被设置为 private，并增加一个静态的方法来创建实例，
     * 静态方法将包含构造函数的所有属性，静态方法的名称为 staticName 的属性值。
     */
    String staticConstructor() default "";
}

• @Value

/**
 * 等价于 @Getter @FieldDefaults(makeFinal=true, level=AccessLevel.PRIVATE)
 * @AllArgsConstructor @ToString @EqualsAndHashCode
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface Value {
    /**
     * 如果设置了该属性，则生成的构造函数将被设置为 private，并增加一个静态的方法来创建实例，
     * 静态方法将包含构造函数的所有属性，静态方法的名称为 staticName 的属性值。
     */
    String staticConstructor() default "";
}

• @Builder

/**
 * fluent build API
 */
@Target({TYPE, METHOD, CONSTRUCTOR})
@Retention(SOURCE)
public @interface Builder {
    /**
     * 设置属性的默认值
     */
    @Target(FIELD)
    @Retention(SOURCE)
    public @interface Default {}

    /** 创建 builder 实例的方法名称 */
    String builderMethodName() default "builder";

    /** 构建目标实例的方法名称 */
    String buildMethodName() default "build";

    /**
     * builder 类的名称
     */
    String builderClassName() default "";

    /**
     * 将此类的实例转换为 builder
     */
    boolean toBuilder() default false;

    /**
     * 只有 toBuilder 为 true 时才有效。
     * 用于从目标实例中读取值，可以放置在属性、构造方法参数、静态方法上
     */
    @Target({FIELD, PARAMETER})
    @Retention(SOURCE)
    public @interface ObtainVia {
        /**
         * @return Tells lombok to obtain a value with the expression {@code this.value}.
         */
        String field() default "";

        /**
         * @return Tells lombok to obtain a value with the expression {@code this.method()}.
         */
        String method() default "";

        /**
         * @return Tells lombok to obtain a value with the expression {@code SelfType.method(this)}; requires {@code method} to be set.
         */
        boolean isStatic() default false;
    }
}

• @Singular

/**
 * 与 Builder 注解共同使用，用于将单个元素添加到集合属性中【放置在集合属性上】
 */
@Target({FIELD, PARAMETER})
@Retention(SOURCE)
public @interface Singular {
    /** 添加单个元素的方法名称 */
    String value() default "";
}

public class Lombok {
    @Test
    public void all() {
        final User user = User.builder().addName("hello").addName("world").build();
        assertEquals(2, user.names.size());
    }
}
@Builder
class User{
    @Singular("addName")
    public List<String> names;
}

• @Cleanup

/**
 * 通过 try-final 方式自动释放资源
 */
@Target(ElementType.LOCAL_VARIABLE)
@Retention(RetentionPolicy.SOURCE)
public @interface Cleanup {
    /** 释放资源的无参方法名称 */
    String value() default "close";
}

• @SneakyThrows

/**
 * 将方法显示抛出的指定异常封装为 RuntimeException
 */
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.SOURCE)
public @interface SneakyThrows {
    /** 需要转换的异常类型列表 */
    Class<? extends Throwable>[] value() default java.lang.Throwable.class;
}

public class Lombok {
    @Test
    public void all() {
        final String hello = "hello";
        final String of = of(hello.getBytes(), "UTF-8");
        assertEquals(of, hello);
    }

    @SneakyThrows
    private static String of(byte[] bytes,String charsetName) {
        return new java.lang.String(bytes, charsetName);
    }
}

• @Synchronized

/**
 * 使用 synchronized 关键字修饰目标方法
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Synchronized {
    /**
     * 需要锁定的目标字段名称，不指定时默认使用 this【实例方法】或此类的 Class 实例【静态方法】
     */
    String value() default "";
}

• @val

/**
 * 使用在局部变量定义处，变量的类型根据赋值表达式进行推断，该变量被 final 修饰。
 */
public @interface val {
}

public class Lombok {
    @Test
    public void all() {
        val name = "hello";
        assertEquals(name.getClass(), String.class);

        val list = Lists.newArrayList();
        assertEquals(list.getClass(), ArrayList.class);
    }
}

• @FieldDefaults

/**
 * 往此类中的每个字段添加修饰符
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface FieldDefaults {
    AccessLevel level() default AccessLevel.NONE;
    boolean makeFinal() default false;
}

• @UtilityClass

/**
 * 用于创建工具类的注解：
 * 1）类将被标记为 final
 * 2）类中不能有显式声明的构造函数否则编译出错，同时添加一个私有无参构造函数，此构造函数将抛出 UnsupportedOperationException 异常
 * 3）所有的属性、方法、内部类都被 static 修饰
 */
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface UtilityClass {
}