Lombok 註解簡介

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 {
}