Spring注解属性别名
1、@AliasFor介绍
@AliasFor是用于为注解属性声明别名的注解，从Spring Framework 4.2开始，核心Spring中的几个注释已更新为使用@AliasFor配置其内部属性别名。
1.1、使用场景
- 注解中的显式别名：在同一个注解中，@AliasFor可以在一对属性上声明，以表示它们是彼此可以互换的别名。
- 元注解中属性的显式别名：如果@AliasFor的注解属性设置为与声明它的注解不同的注解，则该属性将解释为元注解中属性的别名（即显式元注解属性重写）。这使得能够对注解层次结构中重写的属性进行细粒度控制。实际上，使用AliasFor甚至可以为元注解的value属性声明别名。
- 注解中的隐式别名：如果将注解中的一个或多个属性声明为同一元注解属性的属性替代（直接或传递），则这些属性将被视为彼此的一组隐式别名，从而导致行为类似于注释中显式别名的行为。
1.2、使用要求
与Java中的任何注释一样，仅仅是@AliasFor本身的存在不会强制执行别名语义。要强制执行别名语义，必须通过AnnotationUtils中的方法加载注解。在幕后，Spring将通过将注释包装在一个动态代理中来合成注解，该代理透明地为使用@AliasFor注解的注解属性强制执行属性别名语义。类似地，当在注解层次结构中使用@AliasFor时，AnnotatedElementUtils支持显式元注解属性重写。通常，您不需要自己手动合成注解，因为当在Spring管理的组件上查找注解时，Spring将透明地为您合成注解。
到了Spring5.2则通过MergedAnnotations加载注解。
1.3、实现要求
注解中的显式别名：
- 组成别名对的每个属性都必须使用@AliasFor进行相互注解。
- 别名属性必须声明相同的返回类型。
- 别名属性必须声明一个默认值。
- 别名属性必须声明相同的默认值。
- 注解不应声明。
元注释中属性的显式别名：
- 作为元注解中的属性别名的属性必须使用@AliasFor进行注解，并且属性必须引用元注解中的属性。
- 别名属性必须声明相同的返回类型。
- 注解必须引用元注解。
- 引用的元注解必须在声明@AliasFor的注解类上是元存在（注解层次结构中存在）的。
注释中的隐式别名：
- 属于一组隐式别名的每个属性都必须使用@AliasFor进行注解，并且该属性必须在同一元注解中引用相同的属性（通过注解层次结构中的其他显式元注解属性直接覆盖或传递）。
- 别名属性必须声明相同的返回类型。
- 别名属性必须声明一个默认值。
- 别名属性必须声明相同的默认值。
- 注解必须引用适当的元注释。
- 引用的元注解必须在声明@AliasFor的注解类上是元存在（注解层次结构中存在）的。
2、@AliasFor使用的例子
2.1、注解中的显式别名
在@ContextConfiguration中，value和locations是彼此的显式别名。
public @interface ContextConfiguration {
@AliasFor("locations")
String[] value() default {};
@AliasFor("value")
String[] locations() default {};
// ...
}2.2、元注解中属性的显式别名
在@XmlTestConfig中，xmlFiles是@ContextConfiguration中locations的显式别名。 换句话说，xmlFiles覆盖@ContextConfiguration中的locations属性。
@ContextConfiguration
public @interface XmlTestConfig {
@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
String[] xmlFiles();
}2.3、注释中的隐式别名
在@MyTestConfig中，value，groovyScripts和xmlFiles都是@ContextConfiguration中locations属性的显式元注解属性替代。 因此，这三个属性也是彼此的隐式别名。
@ContextConfiguration
public @interface MyTestConfig {
@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
String[] value() default {};
@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
String[] groovyScripts() default {};
@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
String[] xmlFiles() default {};
}2.4、注解中的传递性隐式别名
在@GroovyOrXmlTestConfig中，groovy是@MyTestConfig中groovyScripts属性的显式替代。 xml是@ContextConfiguration中的locations属性的显式替代。 此外，groovy和xml是彼此的传递式隐式别名，因为它们都有效地覆盖了@ContextConfiguration中的locations属性。
@MyTestConfig
public @interface GroovyOrXmlTestConfig {
@AliasFor(annotation = MyTestConfig.class, attribute = "groovyScripts")
String[] groovy() default {};
@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
String[] xml() default {};
}3、@AliasFor注解语义的执行
3.1、MergedAnnotations介绍
提供对合并注解的集合的访问，这些注释通常从类或方法上获得。每个合并的注解表示一个视图，在该视图中可以从不同的源值“合并”属性值，通常是：
- 注解中一个或多个属性的显式和隐式@AliasFor声明
- 显式@AliasFor元注解声明
- 元注解的基于约定的属性别名
- 来自元注解声明
例如，假设@PostMapping注解的定义如下：
@Retention(RetentionPolicy.RUNTIME)
@RequestMapping(method = RequestMethod.POST)
public @interface PostMapping {
@AliasFor(attribute = "path")
String[] value() default {};
@AliasFor(attribute = "value")
String[] path() default {};
}如果使用@PostMapping("/home")注解方法，则它将包含针对@PostMapping和元注解@RequestMapping的合并注解。 @RequestMapping注解的合并视图将包含以下属性：
| Name | Value | Source |
| value | "/home" | 在@PostMapping中声明 |
| path | "/home" | 显示别名@AliasFor |
可以从任何Java AnnotatedElement获得MergedAnnotations。 它们也可以用于不使用反射的源（例如直接解析字节码的源）。
可以使用不同的搜索策略来查找包含要聚合的注解的相关来源元素。 例如，MergedAnnotations.SearchStrategy.TYPE_HIERARCHY将搜索超类和已实现的接口。
从MergedAnnotations实例，您可以获取单个注解，也可以流式传输所有注解或仅匹配特定类型的注释。 您还可以快速判断是否存在注释。
3.2、典型示例
// 是否存在该(元)注解
mergedAnnotations.isPresent(ExampleAnnotation.class);
// 获取ExampleAnnotation的合并的“值”属性（直接注解或元注解）
mergedAnnotations.get(ExampleAnnotation.class).getString("value");
// 获取所有元注释，但不包括直接注解
mergedAnnotations.stream().filter(MergedAnnotation::isMetaPresent);
// 获取所有ExampleAnnotation声明（包括任何元注释）并打印合并的“value”属性
mergedAnnotations.stream(ExampleAnnotation.class)
.map(mergedAnnotation -> mergedAnnotation.getString("value"))
.forEach(System.out::println);3.3、源码分析
MergedAnnotations接口提供了一组静态重载方法来实例化一个MergedAnnotations对象：
static MergedAnnotations from(AnnotatedElement element) {
return from(element, SearchStrategy.DIRECT);
}
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy) {
return from(element, searchStrategy, RepeatableContainers.standardRepeatables());
}
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy,
RepeatableContainers repeatableContainers) {
return TypeMappedAnnotations.from(element, searchStrategy, repeatableContainers, AnnotationFilter.PLAIN);
}
//创建一个新的MergedAnnotations实例，该实例包含指定元素的所有注解和元注解，
//并取决于MergedAnnotations.SearchStrategy，相关的继承元素。
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy,
RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) {
//调用子类静态方法，返回一个子类的实例对象
return TypeMappedAnnotations.from(element, searchStrategy, repeatableContainers, annotationFilter);
}MergedAnnotations内部定义了一个枚举类SearchStrategy，表示查找注解的搜索策略。
- DIRECT：仅查找直接声明的注释，而无需考虑@Inherited注释，也无需搜索超类或已实现的接口。
- INHERITED_ANNOTATIONS：查找所有直接声明的注解以及任何@Inherited超类注解。 该策略仅在与Class类型一起使用时才真正有用，因为所有其他带注解的元素都将忽略@Inherited注释。 此策略不搜索已实现的接口。
- SUPERCLASS：查找所有直接声明的注解和超类注解。 该策略与INHERITED_ANNOTATIONS相似，不同之处在于注解不需要使用@Inherited进行元注解。 此策略不搜索已实现的接口。
- TYPE_HIERARCHY：对整个类型层次进行完整搜索，包括超类和已实现的接口。 超类注解不需要使用@Inherited进行元注解。
- TYPE_HIERARCHY_AND_ENCLOSING_CLASSES：对来源和所有封闭的类执行整个类型层次结构的完整搜索。 该策略与TYPE_HIERARCHY相似，不同之处在于还搜索了封闭类。 超类注解不需要使用@Inherited进行元注解。 搜索方法源时，此策略与TYPE_HIERARCHY相同。
AnnotationFilter用于过滤调用指定注解类型的接口，内部定义了4个常用的AnnotationFilter对象的静态变量：
- PLAIN：与java.lang和org.springframework.lang包及其子包中的注解匹配。
- JAVA：与java和javax包及其子包中的注解匹配。
- ALL：始终匹配，可以在根本不存在任何相关注释类型时使用。
- NONE：永远不匹配，可以在不需要过滤时使用（允许存在任何注释类型）。
MergedAnnotations静态from方法调用子类TypeMappedAnnotations静态from方法：
static MergedAnnotations from(AnnotatedElement element, SearchStrategy searchStrategy,
RepeatableContainers repeatableContainers, AnnotationFilter annotationFilter) {
if (AnnotationsScanner.isKnownEmpty(element, searchStrategy)) {
return NONE;
}
return new TypeMappedAnnotations(element, searchStrategy, repeatableContainers, annotationFilter);
}下面是TypeMappedAnnotations#get(java.lang.Class)实现代码：
//获取指定类型的最接近的匹配注释或元注释；如果不存在，则获取MergedAnnotation.missing()
@Override
public MergedAnnotation get(Class annotationType) {
return get(annotationType, null, null);
}
@Override
public MergedAnnotation get(Class annotationType,
@Nullable Predicate> predicate) {
return get(annotationType, predicate, null);
}
@Override
public MergedAnnotation get(Class annotationType,
@Nullable Predicate> predicate,
@Nullable MergedAnnotationSelector selector) {
//如果filter命中注解类型，返回一个表示不存在注释的MergedAnnotation
if (this.annotationFilter.matches(annotationType)) {
return MergedAnnotation.missing();
}
MergedAnnotation result = scan(annotationType,
new MergedAnnotationFinder<>(annotationType, predicate, selector));
return (result != null ? result : MergedAnnotation.missing());
}scan方法参数中传递一个MergedAnnotationFinder对象，MergedAnnotationFinder是接口AnnotationsProcessor的实现类，内部定义了3个用于处理注解的三个方法。
@Nullable
private R scan(C criteria, AnnotationsProcessor processor) {
//如果调用了带有Annotation[]参数的TypeMappedAnnotations#from方法
if (this.annotations != null) {
R result = processor.doWithAnnotations(criteria, 0, this.source, this.annotations);
return processor.finish(result);
}
//调用了带有AnnotatedElement参数的方法
if (this.element != null && this.searchStrategy != null) {
return AnnotationsScanner.scan(criteria, this.element, this.searchStrategy, processor);
}
return null;
} 调用上面scan方法时，两个if分支的调用过程分别对应下图的两种实例化TypeMappedAnnotations对象。
通过对代码的跟踪发现，这两个分支最终都会调用TypeMappedAnnotations.MergedAnnotationFinder#process这个方法：
@Nullable
private MergedAnnotation process(
Object type, int aggregateIndex, @Nullable Object source, Annotation annotation) {
Annotation[] repeatedAnnotations = repeatableContainers.findRepeatedAnnotations(annotation);
if (repeatedAnnotations != null) {
return doWithAnnotations(type, aggregateIndex, source, repeatedAnnotations);
}
AnnotationTypeMappings mappings = AnnotationTypeMappings.forAnnotationType(
annotation.annotationType(), repeatableContainers, annotationFilter);
for (int i = 0; i < mappings.size(); i++) {
AnnotationTypeMapping mapping = mappings.get(i);
if (isMappingForType(mapping, annotationFilter, this.requiredType)) {
MergedAnnotation candidate = TypeMappedAnnotation.createIfPossible(
mapping, source, annotation, aggregateIndex, IntrospectionFailureLogger.INFO);
if (candidate != null && (this.predicate == null || this.predicate.test(candidate))) {
if (this.selector.isBestCandidate(candidate)) {
return candidate;
}
updateLastResult(candidate);
}
}
}
return null;
}而对@AliasFor别名的支持就在AnnotationTypeMappings中实现的，具体参考AnnotationTypeMappings和AnnotationTypeMapping源代码。