@AliasFor的使用方法

谁借莪１个温暖的怀抱￠ 2023-10-04 22:57 40阅读 0赞

**目录**

一、@AliasFor注解概览

1、对于@AliasFor注释的翻译说明：

Explicit aliases within an annotation.

Explicit alias for attribute in meta-annotation.

Implicit aliases within an annotation.

二、@AliasFor源码属性说明

1、value属性

2、attribute属性

3、annotation属性

三、@AliasFor的使用场景

四、使用举例

1、指定别名，属性互换

①、代码举例

②、使用说明

③、 Spring中的@RequestMapping注解

2、在注解中隐示标明属性的别名

①、代码举例

3、在注解上声明了另一个注解，对另一个注解的属性进行别名覆盖

①、代码举例

②、使用说明

③、Spring中的@Configuration注解

4、组合多个注解，达到通过一个注解使用多个注解的效果

①、代码举例

②、Spring中的@SpringBootApplication注解

五、使用@AliasFor的好处

--------------------

## 一、@AliasFor注解概览 ##

### 1、对于@AliasFor注释的翻译说明： ###

#### Explicit aliases within an annotation. ####

> within a single annotation, @AliasFor can be declared on a pair of attributes to signal that they are interchangeable aliases for each other.

意思是注解中的属性可以互相为别名进行使用。

#### Explicit alias for attribute in meta-annotation. ####

> if the annotation attribute of @AliasFor is set to a different annotation than the one that declares it, the attribute is interpreted as an alias for an attribute in a meta-annotation (i.e., an explicit meta-annotation attribute override). This enables fine-grained control over exactly which attributes are overridden within an annotation hierarchy. In fact, with @AliasFor it is even possible to declare an alias for the value attribute of a meta-annotation.

意思是注解中使用了元注解时，可以对元注解的值进行重写，目的是为了能达到和类继承中override相似的功能。

#### Implicit aliases within an annotation. ####

> if one or more attributes within an annotation are declared as attribute overrides for the same meta-annotation attribute (either directly or transitively), those attributes will be treated as a set of implicit aliases for each other, resulting in behavior analogous to that for explicit aliases within an annotation.

意思是注解中使用了元注解时，可以对元注解的值进行重写，并且可用多个不同的别名进行重写，达到组合使用的效果。

## 二、@AliasFor源码属性说明 ##

package org.springframework.core.annotation;
    
    import java.lang.annotation.Annotation;
    import java.lang.annotation.Documented;
    import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    
    @Retention(RetentionPolicy.RUNTIME)
    @Target({ElementType.METHOD})
    @Documented
    public @interface AliasFor {
        @AliasFor("attribute")
        String value() default "";
    
        @AliasFor("value")
        String attribute() default "";
    
        Class<? extends Annotation> annotation() default Annotation.class;
    }

### 1、value属性 ###

用于声明别名关系的目标注解属性名称。例如，如果我们在一个注解中使用@AliasFor注解，同时将value属性设置为另一个注解的属性名称，则这两个属性将被视为别名。

### 2、attribute属性 ###

该属性与value属性类似，用于声明别名关系的目标注解属性名称。通常情况下，attribute属性与value属性的作用是相同的。

### 3、annotation属性 ###

该属性用于用于指定别名的注解类型。如果没有指定`annotation`属性，则默认为当前注解的类型。

## 三、@AliasFor的使用场景 ##

*  在注解中一对属性上通过声明@AliasFor，进行属性互换。
 *  在注解中隐示标明属性的别名。
 *  在注解上声明了另一个注解，对另一个注解的属性进行别名覆盖（也可以理解为将一个注解上的属性值传递给另一个注解）。
 *  组合多个注解，达到通过一个注解使用多个注解的效果。

> 在注解中一对属性上通过声明@AliasFor，进行属性互换构成别名对的每个属性都应该用@AliasFor注释，并且属性或值必须引用该对中的另一个属性。单从技术上看的话，从Spring Framework 5.2.1开始，允许只注释别名对中的一个属性，但是，建议在别名对中对这两个属性进行注释，以获得更好的文档以及与Spring Framework早期版本的兼容性。

## 四、使用举例 ##

### 1、指定别名，属性互换 ###

#### ①、代码举例 ####

这里定义了一个@MyAnnotation注解，其中value属性和name属性相互为别名，desc属性为普通属性。使用该注解时，可以使用value属性或者name属性设置注解的值。

@Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface MyAnnotation {
     
        @AliasFor("name")
        String value() default "";
     
        @AliasFor("value")
        String name() default "";
     
        String desc() default "";
    }

@MyAnnotation(name = "myName", desc = "myDescription")
    public class MyClass {
        // ...
    }

在这个例子中，@MyAnnotation(name = "myName", desc = "myDescription")和@MyAnnotation(value = "myName", desc = "myDescription")是等价的。

#### ②、使用说明 ####

*  必须以属性别名对的形式出现，即要求有两个属性，且这两个属性的名字分别为对方别名。
 *  这两个属性的必须拥有相同的返回值类型。
 *  这两个属性必须拥有相同的默认值。
 *  @AliasFor中的annotation()不应该被指定值。

#### ③、 Spring中的@RequestMapping注解 ####

@Target({ElementType.TYPE, ElementType.METHOD})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    @Mapping
    public @interface RequestMapping {
        String name() default "";
    
        @AliasFor("path")
        String[] value() default {};
    
        @AliasFor("value")
        String[] path() default {};
    
        RequestMethod[] method() default {};
    
        String[] params() default {};
    
        String[] headers() default {};
    
        String[] consumes() default {};
    
        String[] produces() default {};
    }

### 2、在注解中隐示标明属性的别名 ###

#### ①、代码举例 ####

比如，Spring中的@Bean注解，我们在使用时这个注解时，可以直接填写内容，而不用主动指定"name"和"value"属性，从而达到了隐示表明属性别名的效果。

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    public @interface Bean {
        @AliasFor("name")
        String[] value() default {};
    
        @AliasFor("value")
        String[] name() default {};
    
        /** @deprecated */
        @Deprecated
        Autowire autowire() default Autowire.NO;
    
        boolean autowireCandidate() default true;
    
        String initMethod() default "";
    
        String destroyMethod() default "(inferred)";
    }

@Configuration
    public class MyConfiguration {
    
        @Bean("myBean")
        public MyBean myBean() {
            return new MyBean();
        }
    }

### 3、在注解上声明了另一个注解，对另一个注解的属性进行别名覆盖 ###

#### ①、代码举例 ####

我们有一个注解`@MyAnnotation`，我们想要为它定义一个别名注解`@MyAliasAnnotation`，可以这样定义：

@Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @MyAnnotation
    public @interface MyAliasAnnotation {
    
        @AliasFor(annotation = MyAnnotation.class, attribute = "value")
        String name() default "";
    }

在这个例子中，`@MyAliasAnnotation`被标记为别名注解，它使用了`@MyAnnotation`的属性`value`作为自己的`name`属性的别名。其中`annotation`属性指定了原注解的类型，`attribute`属性指定了要使用的属性名称。

#### ②、使用说明 ####

*  在需要override的注解的属性上使用：@AliasFor(annotation="元注解",attribute="元注解的属性")。
 *  被标记@AliasFor的属性和atttibute所指向的元注解属性必须有相同的返回值类型。
 *  @AliasFor中annotation指向的元注解必须作用于正在定义的注解上（就是要标记在新注解上）。

#### ③、Spring中的@Configuration注解 ####

package org.springframework.context.annotation;
    
    import java.lang.annotation.Documented;
    import java.lang.annotation.ElementType;
    import java.lang.annotation.Retention;
    import java.lang.annotation.RetentionPolicy;
    import java.lang.annotation.Target;
    import org.springframework.core.annotation.AliasFor;
    import org.springframework.stereotype.Component;
    
    @Target({ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    @Component
    public @interface Configuration {
        @AliasFor(
            annotation = Component.class
        )
        String value() default "";
    }

可以看出对于value这个属性来说，@Configuration注解中的值会重写@Component的value属性值，这有点像类之间的继承，子类可以重父类的方法。我们也可以将@Configuration注解看成@Component的子注解。

当然，你也可以理解为将一个注解上的属性值传递给另一个注解，我个人更习惯采用这种理解，因为后续可以通过一个注解组合多个注解进行使用，通过一个注解将值传递给多个注解，而这与java的继承的概念并不相同。

### 4、组合多个注解，达到通过一个注解使用多个注解的效果 ###

#### ①、代码举例 ####

假设我们有三个注解：

@Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyAnnotation1 {
        String value();
    }
    
    @Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyAnnotation2 {
        String name();
    }
    
    @Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    public @interface MyAnnotation3 {
        String desc();
    }

我们可以使用@AliasFor注解来定义一个新注解，将这三个注解组合起来，具体代码如下：

@Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @MyAnnotation1
    @MyAnnotation2
    @MyAnnotation3
    public @interface MyCombinedAnnotation {
        @AliasFor(annotation = MyAnnotation1.class, attribute = "value")
        String value() default "";
    
        @AliasFor(annotation = MyAnnotation2.class, attribute = "name")
        String name() default "";
    
        @AliasFor(annotation = MyAnnotation3.class, attribute = "desc")
        String desc() default "";
    }

在这个新注解中，我们使用了@AliasFor注解，将MyAnnotation1中的value()方法和MyAnnotation2中的name()方法都映射到MyCombinedAnnotation中的value()方法中，同时将MyAnnotation3中的desc()方法映射到MyCombinedAnnotation中的desc()方法中。

这样，我们就可以通过一个注解来使用这三个注解的属性了。例如：

@MyCombinedAnnotation(value = "hello", name = "world", desc = "this is a combined annotation")
    public class MyClass {
        //...
    }

上面的代码等价于以下的代码：

@MyAnnotation1("hello")
    @MyAnnotation2(name = "world")
    @MyAnnotation3(desc = "this is a combined annotation")
    public class MyClass {
        //...
    }

注意，我们需要在MyCombinedAnnotation中加上@MyAnnotation1、@MyAnnotation2、@MyAnnotation3三个注解，表示这个新注解中包含了这三个注解的所有属性，可以通过@MyCombinedAnnotation来代替这三个注解的使用。同时，在MyCombinedAnnotation中定义的属性，需要使用@AliasFor注解来映射到MyAnnotation1、MyAnnotation2、MyAnnotation3中的对应属性。

#### ②、Spring中的@SpringBootApplication注解 ####

@Target({ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Documented
    @Inherited
    @SpringBootConfiguration
    @EnableAutoConfiguration
    @ComponentScan(
        excludeFilters = {@Filter(
        type = FilterType.CUSTOM,
        classes = {TypeExcludeFilter.class}
    ), @Filter(
        type = FilterType.CUSTOM,
        classes = {AutoConfigurationExcludeFilter.class}
    )}
    )
    public @interface SpringBootApplication {
        @AliasFor(
            annotation = EnableAutoConfiguration.class
        )
        Class<?>[] exclude() default {};
    
        @AliasFor(
            annotation = EnableAutoConfiguration.class
        )
        String[] excludeName() default {};
    
        @AliasFor(
            annotation = ComponentScan.class,
            attribute = "basePackages"
        )
        String[] scanBasePackages() default {};
    
        @AliasFor(
            annotation = ComponentScan.class,
            attribute = "basePackageClasses"
        )
        Class<?>[] scanBasePackageClasses() default {};
    
        @AliasFor(
            annotation = ComponentScan.class,
            attribute = "nameGenerator"
        )
        Class<? extends BeanNameGenerator> nameGenerator() default BeanNameGenerator.class;
    
        @AliasFor(
            annotation = Configuration.class
        )
        boolean proxyBeanMethods() default true;
    }

## 五、使用@AliasFor的好处 ##

使用@AliasFor注解可以为注解元素之间建立关联，提高注解的可读性和可维护性。具体好处如下：

1.  简化注解定义：通过@AliasFor注解，可以简化注解定义中的元素声明，减少了重复代码，提高了代码的可读性和可维护性。
2.  避免冗余：通过@AliasFor注解，可以将重复的注解元素关联起来，避免了冗余的元素声明，使代码更加简洁。
3.  保持一致性：通过@AliasFor注解，可以将注解元素之间的关系明确化，保持注解的一致性，提高代码的可读性和可维护性。
4.  明确注解元素的作用：通过@AliasFor注解，可以明确注解元素之间的关系，帮助开发人员更好地理解注解的作用和用法，提高开发效率和代码质量。