合成注解相关功能重构，添加支持通过@Link及其子注解，实现注解中属性的互为镜像、可选覆盖以及强制覆盖三种模式的别名机制的新特性 · Pull Request !702 · chinabugotech/hutool

### 说明

1. 请确认你提交的PR是到'v5-dev'分支，否则我会手动修改代码并关闭PR。
2. 请确认没有更改代码风格（如tab缩进）
3. 新特性添加请确认注释完备，如有必要，请在src/test/java下添加Junit测试用例

### 修改描述(包括说明bug修复或者添加新特性)

1. [新特性] 为合成注解添加 `@Link` 注解，以及基于 `@Link` 扩展的子注解 `@AliasFor`、`@MirrorFor` 和 `@ForceAliasFor` 注解，允许通过注解在合成注解中指定两个字段互为镜像别名，或令子注解的值在为非默认值的情况下强制覆盖元注解指定属性的值。
2. [变更] 修复了合成注解和注解扫描器相关的一些内部类、方法和属性名错误的问题；
3. [变更] 将 `AnnotationUtil` 中获取合成注解的方法统一改为 `xxxSynthesizedAnnotation` 格式；
4. [修复] 完善了一些类的注释与测试用例；

我尝试提交到 v6-dev，不过 v6 和 v5 分支差别有点大，而且有些依赖的方法或者类只有 v5 有，我不确定它们是在 v6 被拆分到了其他类，还是暂时没有迁移，感觉有点无从下手，所以还是先提交到了 v5 ......

### 镜像别名

镜像别名可以让两个字段互为镜像，对其中一个属性的赋值将同步到另一属性。

假设现有注解 `TestAnnotation`，令其中 `value` 和 `name` 字段互为镜像，则有：

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestAnnotation {
    // 等同于 @Link(attribute = "name", type = RelationType.MIRROR_FOR)
    @MirrorFor(attribute = "name")
    String value() default "";
    // 等同于 @Link(attribute = "value"", type = RelationType.MIRROR_FOR)
    @MirrorFor(attribute = "value")
    String name() default "";
}
```

现将该注解注解在 `Foo.class` 上：

```
@TestAnnotation(value = "Foo")
static class Foo {}
```

这获取合成注解有：

```
// 对注解进行合成
AnnotationForMirrorTest annotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestAnnotation.class);
// 两字段值都保持一致
Assert.assertEquals("Foo", annotation.name());
Assert.assertEquals("Foo", annotation.value());
```

**规则**

互为镜像的两属性规则如下：

- 两属性的返回值类型必须一致；
- 若属性值都为默认值，或两字段都为非默认值，则要求返回值必须相等；
- 若两属性只有一个不为默认值，则获取任何一个属性的值时都优先返回该非默认值；

### 强制别名

强制别名可以使一个指定的注解属性覆盖另一个注解属性的值。

根据在 `@Alias` 在注解包下的实现可知，在 `hutool` 的语义中，若一个属性指定了别的属性作为别名，这别名属性的值将强制覆盖原字段的值。

基于此，提供了在子注解中强制覆盖元注解指定属性的功能，该功能等同于跨注解版的 `@Alias` 。

假设现有元注解 `TestMetaAnnotation`，和其子注解 `TestAnnotation`：

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestMetaAnnotation {
    String metaValue() default "";
}

@TestMetaAnnotation
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestAnnotation {
    // 等同于 @Link(attribute = "name", type = Relation.FORCE_ALIAS_FOR)
    @ForceAliasFor(attribute = "metaValue", annotation = TestMetaAnnotation.class)
    String childValue() default "";
}
```

现将该注解注解在 `Foo.class` 上：

```java
@TestAnnotation(childValue = "Foo")
static class Foo {}
```

则获取合成注解有：

```java
// 对注解进行合成
TestMetaAnnotation metaAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestMetaAnnotation.class);
AnnotationForMirrorTest childAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestAnnotation.class);
// 元注解的值被子注解覆写
Assert.assertEquals("Foo", metaAnnotation.metaValue());
Assert.assertEquals("Foo", childAnnotation.childValue());
```

**规则**

原始属性与其指定的强制别名属性遵守的规则如下：

- 两属性的返回值类型必须一致；
- 即使强制别名属性只有默认值，也会强制覆盖原始属性的值；
- 如果原始属性本身是一个镜像属性，则另一个与其互为镜像的属性也会被覆写；
- 如果原始属性本身也是一个强制别名/别名属性，则其覆写的属性也会被一起覆写；

### 可选别名

可选别名可以指定一个A属性成为B属性的别名，当A属性只有默认值时，B属性的值不会被覆盖，当A属性有非默认值时，B属性的值就会被覆盖。

可选别名的用法类似 spring 的 `@AliasFor`，假设现有元注解 `TestMetaAnnotation`，和其子注解 `TestAnnotation`：

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestMetaAnnotation {
    String metaValue() default "Meta";
}

@TestMetaAnnotation
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestAnnotation {
    // 等同于 @Link(attribute = "name", type = Relation.ALIAS_FOR)
    @AliasFor(attribute = "metaValue", annotation = TestMetaAnnotation.class)
    String childValue() default "Child";
}
```

**在子注解指定了非默认值时，将覆盖元注解的值**

假如现 `Foo.class` 上存在注解：

```java
@TestAnnotation(childValue = "Foo")
static class Foo {}
```

则获取合成注解有：

```java
// 对注解进行合成
TestMetaAnnotation metaAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestMetaAnnotation.class);
AnnotationForMirrorTest childAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestAnnotation.class);
// 元注解的值被子注解覆写
Assert.assertEquals("Foo", metaAnnotation.metaValue());
Assert.assertEquals("Foo", childAnnotation.childValue());
```

**在子注解为指定默认值时，将不覆盖元注解的值**

假如现 `Foo.class` 上存在注解：

```java
@TestAnnotation
static class Foo {}
```

则获取合成注解有：

```java
// 对注解进行合成
TestMetaAnnotation metaAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestMetaAnnotation.class);
AnnotationForMirrorTest childAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestAnnotation.class);
// 元注解的值不会被子注解覆写
Assert.assertEquals("Meta", metaAnnotation.metaValue());
Assert.assertEquals("Child", childAnnotation.childValue());
```

**规则**

原始属性与其指定的可选别名属性遵守的规则如下：

- 两属性的返回值类型必须一致；
- 当别名属性只有默认值时，不会覆盖原始属性的值，若别名属性为默认值时，将会覆盖元素属性的值；
- 如果原始属性本身是一个镜像属性，则另一个与其互为镜像的属性也会被覆写；
- 如果原始属性本身也是一个强制别名/别名属性，则其覆写的属性也会被一起覆写，覆写规则遵循第二点；

### 隐式别名

当元注解和子注解中存在名称和类型均一致属性时，两个属性会构成隐形的别名关系。元注解的值也会被子注解的值所覆盖：

假设现有元注解 `TestMetaAnnotation`，和其子注解 `TestAnnotation`：

```java
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestMetaAnnotation {
    @MirrorFor(attribute = "name")
    String name() default "";
    @MirrorFor(attribute = "value")
    String value() default "";
}

@TestMetaAnnotation(value = "Meta")
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD, ElementType.TYPE })
@interface TestAnnotation {
    String value() default "";
}
```

现将该注解注解在 `Foo.class` 上：

```java
@TestAnnotation(value = "Foo")
static class Foo {}
```

则合成后有：

```java
// 对注解进行合成
TestMetaAnnotation metaAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestMetaAnnotation.class);
AnnotationForMirrorTest childAnnotation = AnnotationUtil.getSyntheticAnnotation(Foo.class, TestAnnotation.class);
// 父注解的值会被覆写
Assert.assertEquals("Foo", metaAnnotation.value());
Assert.assertEquals("Foo", childAnnotation.value());
// 但是该值不会随着镜像属性传递
Assert.assertEquals("Meta", metaAnnotation.name());
```

**规则**

原始属性与其隐式别名属性遵守的规则如下：

- 父子注解中的属性只有返回值类型与名称完全一致才会形成别名；
- 即使别名属性只有默认值时，也会强制覆盖原始属性的值；
- 隐式别名的关系不会随着原始注解的镜像别名、强制别名以及可选别名关系传递到关联的属性上。

### [@alias ](https://gitee.com/alias)兼容

在合成注解体系中，仍然兼容 `@Alias` 注解，该注解的效果等同于 `@ForceAliasFor`，但是仅能针对同一注解使用。

`@Alias` 注解的优先级高于 `@Link` 以及 `@Link` 的扩展注解。

### 合成注解的解析规则

包括`@MirrorFor`，`@AliasFor`，`@ForceAliasFor` 在内的合成注解可以在同一个属性上添加多个，但是只有声明在最上方的注解会生效，

比如：

```java
@interface TestMetaAnnotation {
    
    @ForceAliasFor(attribute = "name")
    @AliasFor(attribute = "name")
    @MirrorFor(attribute = "name")
    String value() default "";
    
    @MirrorFor(attribute = "value")
    String name() default "";
    
}
```

上述情况下 `value` 属性同时有三个注解，但是在合成时仅有声明在最上方的 `@ForceAliasFor(attribute = "name")` 会生效。

这一次提交涉及到的东西比较多，这里简单画了一下合成注解的运行流程：

![image-20220713174128393](https://img.xiajibagao.top/image-20220713174128393.png)

GVPchinabugotech/hutool

搜索帮助

GVP chinabugotech/hutool