深入理解Spring注解机制（三）：合并注解的合成

发表于 | 分类于
字数统计: 3.7k

前言

众所周知，spring 从 2.5 版本以后开始支持使用注解代替繁琐的 xml 配置，到了 springboot 更是全面拥抱了注解式配置。平时在使用的时候，点开一些常见的等注解，会发现往往在一个注解上总会出现一些其他的注解，比如 @Service：

1
2
3
4
5
6
7
8
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component // @Component
public @interface Service {
    @AliasFor(annotation = Component.class)
    String value() default "";
}

大部分情况下，我们可以将 @Service 注解等同于 @Component 注解使用，则是因为 spring 基于其 JDK 对元注解的机制进行了扩展。

在 java 中，元注解是指可以注解在其他注解上的注解，spring 中通过对这个机制进行了扩展，实现了一些原生 JDK 不支持的功能，比如允许在注解中让两个属性互为别名，或者将一个带有元注解的子注解直接作为元注解看待，或者在这个基础上，通过 @AliasFor 或者同名策略让子注解的值覆盖元注解的值。

本文将基于 spring 源码 5.2.x 分支，解析 spring 如何实现这套功能的。

这是系列的第三篇文章，将详细介绍 Spring 是如何在经过搜索与属性映射后，将处理后的注解合成为合并注解的。

相关文章：

一、合并注解

我们在前文了解用于搜索注解的合并注解聚合 MergedAnnotations与用于完成注解属性映射的 AnnotationTypeMappings 和AnnotationTypeMapping，现在我们需要知道在 MergedAnnotations 这个容器中，AnnotationTypeMappings 和AnnotationTypeMapping 是如何转为一个我们所需要的合并注解 MergedAnnotation 的。

与前文一样，我们以 AnnotatedElementUtils.findMergedAnnotations 方法作为入口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
public static <A extends Annotation> A findMergedAnnotation(AnnotatedElement element, Class<A> annotationType) {
    // 1、下述任意情况下直接获取元素上声明的注解：
    // a.查找的注解属于java、javax或者org.springframework.lang包
    // b.被处理的元素属于java包，或被java包中的对象声明，或者就是Ordered.class
    if (AnnotationFilter.PLAIN.matches(annotationType) ||
        AnnotationsScanner.hasPlainJavaAnnotationsOnly(element)) {
        return element.getDeclaredAnnotation(annotationType);
    }

    // 2、将元素上的全部注解合成MergedAnnotation
    return findAnnotations(element)
        // 3、从MergedAnnotation获取与该类型对应的MergedAnnotations
        .get(annotationType, null, MergedAnnotationSelectors.firstDirectlyDeclared())
        // 4、根据MergedAnnotation通过动态代理生成一个注解实例
        .synthesize(MergedAnnotation::isPresent).orElse(null);
}

我们在上文顺着 MergedAnnotations.get 一路找到 TypeMappedAnnotations.MergedAnnotationFinder 的 process 方法，在这里我们目睹了一个普通的注解的元注解被解析为 AnnotationTypeMappings 与 AnnotationTypeMapping 的过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
private MergedAnnotation<A> process(
    Object type, int aggregateIndex, @Nullable Object source, Annotation annotation) {

    Annotation[] repeatedAnnotations = repeatableContainers.findRepeatedAnnotations(annotation);
    if (repeatedAnnotations != null) {
        return doWithAnnotations(type, aggregateIndex, source, repeatedAnnotations);
    }
    // 将该注解上的元注解解析为由多个AnnotationTypeMapping聚合的AnnotationTypeMappings
    AnnotationTypeMappings mappings = AnnotationTypeMappings.forAnnotationType(
        annotation.annotationType(), repeatableContainers, annotationFilter);
    for (int i = 0; i < mappings.size(); i++) {
        // 获取元注解对应的AnnotationTypeMapping
        AnnotationTypeMapping mapping = mappings.get(i);
        if (isMappingForType(mapping, annotationFilter, this.requiredType)) {
            // 使用AnnotationTypeMapping创建一个合并注解
            MergedAnnotation<A> 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;
}

其他部分在上文已经详细的分析了，因此此处我们仅需关注 TypeMappedAnnotation.createIfPossible 这一个方法：

1
2
3
4
5
6
7
static <A extends Annotation> TypeMappedAnnotation<A> createIfPossible(
    AnnotationTypeMapping mapping, @Nullable Object source, Annotation annotation,
    int aggregateIndex, IntrospectionFailureLogger logger) {

    return createIfPossible(mapping, source, annotation,
                            ReflectionUtils::invokeMethod, aggregateIndex, logger);
}

该方法是 AnnotationTypeMapping 转为 MergedAnnotation 的关键。

1、合并注解的创建

TypeMappedAnnotation 是 MergedAnnotation 一个通用实现，在大部分情况下，我们所说的合并注解其实指的就是这个类。

通过它的构造方法我们得以了解其创建过程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
private TypeMappedAnnotation(AnnotationTypeMapping mapping, @Nullable ClassLoader classLoader,
                             @Nullable Object source, @Nullable Object rootAttributes, ValueExtractor valueExtractor,
                             int aggregateIndex, @Nullable int[] resolvedRootMirrors) {

    // 当前合并注解对应的AnnotationTypeMapping
    this.mapping = mapping;
    // 类加载器
    this.classLoader = classLoader;
    // 当前注解的数据源
    this.source = source;
    // AnnotationTypeMapping对应的root注解
    this.rootAttributes = rootAttributes;
    // 通过属性方法对象获得属性值的方法，一般是ReflectionUtils::invokeMethod
    this.valueExtractor = valueExtractor;
    // 该注解对应的聚合索引
    this.aggregateIndex = aggregateIndex;
    // 是否使用映射过的属性值
    this.useMergedValues = true;
    // 属性过滤器
    this.attributeFilter = null;
    // 通过MirrorSets解析得到的确认属性
    this.resolvedRootMirrors = (resolvedRootMirrors != null ? resolvedRootMirrors :
                                mapping.getRoot().getMirrorSets().resolve(source, rootAttributes, this.valueExtractor));
    this.resolvedMirrors = (getDistance() == 0 ? this.resolvedRootMirrors :
                            mapping.getMirrorSets().resolve(source, this, this::getValueForMirrorResolution));
}

可以看得出，TypeMappedAnnotation 基本可以认为是 AnnotationTypeMapping 的包装类，它以一个 AnnotationTypeMapping 实例作为数据源，从而提供一些关于映射后的属性的相关功能。

它本身并没有很多特殊的逻辑，我们仅需要关注通过它合成注解的代理对象，以及后续调用代理对象时，是如何从映射过的属性获取值的。

2、合并注解的合成

回到 AnnotatedElementUtils.findMergedAnnotations，我们可以看到，在通过 MergedAnnotations 获得了一个 MergedAnnotation 对象——实际上是 TypeMappedAnnotation 对象——之后，又调用了 MergedAnnotation.synthesize 方法，将 MergedAnnotation 转成了一个调用方指定类型的注解对象。

该方法先调用了 AbstractMergedAnnotation 的 synthesize 方法：

1
2
3
4
5
public Optional<A> synthesize(Predicate<? super MergedAnnotation<A>> condition)
    throws NoSuchElementException {

    return (condition.test(this) ? Optional.of(synthesize()) : Optional.empty());
}

随后再调用了实现类 TypeMappedAnnotation 的 synthesize 方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
public A synthesize() {
    if (!isPresent()) {
        throw new NoSuchElementException("Unable to synthesize missing annotation");
    }
    // 如果已经合成过就直接返回缓存的实例
    A synthesized = this.synthesizedAnnotation;
    if (synthesized == null) {
        // 合成注解
        synthesized = createSynthesized();
        this.synthesizedAnnotation = synthesized;
    }
    return synthesized;
}

继续点开 createSynthesized ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
protected A createSynthesized() {
    // 满足下述条件时，直接返回根注解：
    // 1.若当前注解的属性与根注解相同
    // 2.且该合成注解还没有被合成过
    // 3.该注解存在映射后的属性
    if (getType().isInstance(this.rootAttributes) && !isSynthesizable()) {
        return (A) this.rootAttributes;
    }
    // 使用动态代理创建一个代理注解
    return SynthesizedMergedAnnotationInvocationHandler.createProxy(this, getType());
}

private boolean isSynthesizable() {
    // Already synthesized?
    if (this.rootAttributes instanceof SynthesizedAnnotation) {
        return false;
    }
    return this.mapping.isSynthesizable();
}

而 SynthesizedMergedAnnotationInvocationHandler 是一个用于 JDK 动态代理的 InvocationHandler，我们不需要完全站看，仅需看看它的构造函数与 InvocationHandler.invoke 就能明白它的运作机制了：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
final class SynthesizedMergedAnnotationInvocationHandler<A extends Annotation> implements InvocationHandler {

    // 合并注解实例
    private final MergedAnnotation<?> annotation;

    // 代理注解的类型
    private final Class<A> type;

    // 代理注解的注解方法
    private final AttributeMethods attributes;

    // 注解属性的值缓存
    private final Map<String, Object> valueCache = new ConcurrentHashMap<>(8);

    // hashcode
    @Nullable
    private volatile Integer hashCode;

    // toString的值
    @Nullable
    private volatile String string;


    private SynthesizedMergedAnnotationInvocationHandler(MergedAnnotation<A> annotation, Class<A> type) {
        Assert.notNull(annotation, "MergedAnnotation must not be null");
        Assert.notNull(type, "Type must not be null");
        Assert.isTrue(type.isAnnotation(), "Type must be an annotation");
        this.annotation = annotation;
        this.type = type;
        this.attributes = AttributeMethods.forAnnotationType(type);
    }
}

至此，合并注解的合成机制已经很明确了：

  • 先通过 AnnotationTypeMapping 创建 TypeMappedAnnotation；
  • 通过 TypeMappedAnnotation.synthesize 创建一个对应的类型的注解对象；
  • 如果该 TypeMappedAnnotation 无需合成，则直接返回对应的原始注解对象，否则返回基于该合并注解生成的JDK动态代理对象；

二、合并注解的取值

承接上文，当我们使用 MergedAnnotation.synthesize 方法时，我们可能会得到两种对象：

  • 第一种就是原始的注解对象，这个没什么好说的；
  • 第二种就是通过 SynthesizedMergedAnnotationInvocationHandler 生成的注解代理对象；

而通过注解代理对象取值时，这些方法会被代理到 SynthesizedMergedAnnotationInvocationHandler 中存放的 MergedAnnotation 对象上，从而让这个代理对象通过原始注解的属性，获得与原始注解不一样的属性值。

1、方法代理

当我们调用代理对象的属性值时，它会在 SynthesizedMergedAnnotationInvocationHandler 中，通过 invoke 代理到对应的方法上：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@Override
public Object invoke(Object proxy, Method method, Object[] args) {
    // 代理 equals 方法
    if (ReflectionUtils.isEqualsMethod(method)) {
        return annotationEquals(args[0]);
    }
    // 代理 hashCode 方法
    if (ReflectionUtils.isHashCodeMethod(method)) {
        return annotationHashCode();
    }
    // 代理 toString 方法
    if (ReflectionUtils.isToStringMethod(method)) {
        return annotationToString();
    }
    // 代理 isAnnotationTypeMethod 方法
    if (isAnnotationTypeMethod(method)) {
        return this.type;
    }
    // 代理获取注解属性的方法
    if (this.attributes.indexOf(method.getName()) != -1) {
        return getAttributeValue(method);
    }
    throw new AnnotationConfigurationException(String.format(
        "Method [%s] is unsupported for synthesized annotation type [%s]", method, this.type));
}

2、注解属性的获取

这里我们代理对象是如何获取注解属性值的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
private Object getAttributeValue(Method method) {
    // 缓存属性值
    Object value = this.valueCache.computeIfAbsent(method.getName(), attributeName -> {
        // 获取代理方法的返回值类型
        Class<?> type = ClassUtils.resolvePrimitiveIfNecessary(method.getReturnType());
        // 从 MergedAnnotation 获取对应属性值
        return this.annotation.getValue(attributeName, type).orElseThrow(
            () -> new NoSuchElementException("No value found for attribute named '" + attributeName +
                                             "' in merged annotation " + this.annotation.getType().getName()));
    });

    // Clone non-empty arrays so that users cannot alter the contents of values in our cache.
    if (value.getClass().isArray() && Array.getLength(value) > 0) {
        value = cloneArray(value);
    }

    return value;
}

这里的 MergedAnnotation.getValue 最终在经过多次跳转后，调到 TypeMappedAnnotation.getAttributeValue 上：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
protected <T> T getAttributeValue(String attributeName, Class<T> type) {
    // 获取方法在AttributeMethods中的下标
    int attributeIndex = getAttributeIndex(attributeName, false);
    // 若方法存在，则通过下标调用
    return (attributeIndex != -1 ? getValue(attributeIndex, type) : null);
}

private <T> T getValue(int attributeIndex, Class<T> type) {
    // 获取属性对应的方法
    Method attribute = this.mapping.getAttributes().get(attributeIndex);
    // 获取属性值，若有必要则进行属性映射
    Object value = getValue(attributeIndex, true, false);
    if (value == null) {
        // 如果没有值则尝试获得默认值
        value = attribute.getDefaultValue();
    }
    // 进行类型适配
    return adapt(attribute, value, type);
}

而这边的 getValue 方法就是真正要获取属性值的地方。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
private Object getValue(int attributeIndex, boolean useConventionMapping, boolean forMirrorResolution) {
    AnnotationTypeMapping mapping = this.mapping;
    // 是否要获取合并后的属性
    if (this.useMergedValues) {
        // 如果有必要，属性是否会被来自根注解的属性覆盖
        int mappedIndex = this.mapping.getAliasMapping(attributeIndex);
        // 如果不会被来自根注解的属性覆盖，并且允许使用子注解属性覆盖该属性
        if (mappedIndex == -1 && useConventionMapping) {
            mappedIndex = this.mapping.getConventionMapping(attributeIndex);
        }
        // 如果上述两情况只要有任意一点符合，则令attributeIndex变为根/子注解中覆盖属性的下标
        if (mappedIndex != -1) {
            mapping = mapping.getRoot();
            attributeIndex = mappedIndex;
        }
    }
    // 若有必要，且当前属性下标对应的属性在注解内还存在别名属性，则通过MirrorSets获得唯一确定的属性的下标
    if (!forMirrorResolution) {
        attributeIndex =
            (mapping.getDistance() != 0 ? this.resolvedMirrors : this.resolvedRootMirrors)[attributeIndex];
    }
    if (attributeIndex == -1) {
        return null;
    }
    // 如果自己就是根节点，则从自己身上获取
    if (mapping.getDistance() == 0) {
        Method attribute = mapping.getAttributes().get(attributeIndex);
        Object result = this.valueExtractor.extract(attribute, this.rootAttributes);
        return (result != null ? result : attribute.getDefaultValue());
    }
    // 如果自己不是根节点，则从元注解上获取
    return getValueFromMetaAnnotation(attributeIndex, forMirrorResolution);
}

@Nullable
private Object getValueFromMetaAnnotation(int attributeIndex, boolean forMirrorResolution) {
    Object value = null;
    if (this.useMergedValues || forMirrorResolution) {
        value = this.mapping.getMappedAnnotationValue(attributeIndex, forMirrorResolution);
    }
    if (value == null) {
        Method attribute = this.mapping.getAttributes().get(attributeIndex);
        value = ReflectionUtils.invokeMethod(attribute, this.mapping.getAnnotation());
    }
    return value;
}

Object getMappedAnnotationValue(int attributeIndex, boolean metaAnnotationsOnly) {
    int mappedIndex = this.annotationValueMappings[attributeIndex];
    if (mappedIndex == -1) {
        return null;
    }
    AnnotationTypeMapping source = this.annotationValueSource[attributeIndex];
    if (source == this && metaAnnotationsOnly) {
        return null;
    }
    return ReflectionUtils.invokeMethod(source.attributes.get(mappedIndex), source.annotation);
}

这一步有点复杂，主要是根据不同的情况，通过 AnnotationTypeMapping 中的几个属性映射数组，包括 aliasMappings、conventionMappings，annotationValueMappings 与 annotationValueSource 来确定最终用于取值的 AnnotationTypeMapping 对象与调用的方法在 AttributeMethods 中的下标：

  • 如果要合并属性值，则：
    1. 若该属性被 root 中的同名属性覆盖，即 aliasMappings 数组对应下标不为 -1，则记录该 root 属性下标；
    2. 若该属性不被 root 中同名属性覆盖，则确定是否被子注解中的同名属性覆盖，即 conventionMappings 数组对应下标不为 -1，则记录该覆盖属性下标；
  • 若允许别名，则在上述基础上，继续进行处理：
    1. 若当前注解已经是根注解，则从 resolvedRootMirrors 上，获得该属性在同一注解下关联的别名属性中，唯一确定的有效属性的下标；
    2. 若当前注解不是根注解，则从 resolvedRootMirrors 上，获得该属性在同一注解下关联的别名属性中，唯一确定的有效属性的下标；
  • 若当前注解是根注解，则使用从根注解对象 rootAttributes 上根据属性下标获取对应方法，然后通过反射调用获取属性值；
  • 若当前注解不是根注解，则：
    1. 若不支持属性覆盖以及别名，则直接和获取该注解属性下标对应方法，并通过反射调用获取属性值；
    2. 若支持属性覆盖以及别名，则通过属性下标从 annotationValueSource 找到对应的注解对象，再通过 annotationValueMappings 找到要在该注解中调用的属性下标，然后在通过属性下标找到对应的属性方法后，通过反射调用获取属性值；

至此，获取属性值的方法流程也走完了。

总结

在这一章，我们了解了当通过 MergedAnnotations 获得注解并解析得到 AnnotationTypeMapping 后，AnnotationTypeMapping 是如何再转为我们所需的 MergedAnnotation ，以及在此之后，MergedAnnotation 又是如何生成我们最终所需要的代理注解的。

简而言之，当解析注解的元注解获得所需的 AnnotationTypeMapping 后，MergedAnnotation 会判断 AnnotationTypeMapping 是否发生过属性映射，如果没有则返回该映射对象对应的原始注解，否则就通过 SynthesizedMergedAnnotationInvocationHandler 生成一个对应类型的 JDK 动态代理对象。

当我们通过代理对象去调用注解的方法，获取注解的属性的时候，SynthesizedMergedAnnotationInvocationHandler 会把方法代理到对应的内部方法中，而获取属性时，还会通过 MergedAnnotation.getValue ，最终绕到 AnnotationTypeMapping 中获取被映射后的属性值。

题外话

至此，关于 Spring 注解机制的三篇文章已经全部写完了，在了解了它是实现原理的同时，笔者也深刻的认识到了其功能的强大，尤其是 MergeAnnotation 真切的弥补了 java 注解不支持继承所带来的的一些痛点，这点笔者在自己的项目尝试了全面拥抱 spring 的增强注解后深有感触。

出于巩固知识，也出于为想要在非 Spring 环境下享受这个功能的同学考虑，作者决定搞一套类似的开源项目，目前也已经有了一些成果：

  • 笔者尝试为常用的开源工具类库 hutool 提了一个 PR ，也有幸被作者大佬采纳了，有需要的同学可以在 Hutool-5.8.5 及以上版本使用该功能；
  • 由于考虑有些项目并没有引入 Hutool，以及跟作者沟通后觉得这个特性并不适合搬到即将发布的 Hutool-6.x ，因此笔者单独将作为一个注解工具类库开源了，有兴趣的同学可以了解一下 powerful-annotation ；
0%