Hutool
  • 指南
  • 核心(hutool-core)
  • 注解(annotation)
Hutool
2026-01-03
目录

层级注解工具-AnnotatedElementUtil

# 📚介绍

提供对层级结构中AnnotatedElement上注解及元注解的访问支持。 并提供诸如基于@Alias的属性别名、基于父子注解间的属性值覆盖等特殊的属性映射机制支持。

# 🔍 搜索层级结构

工具类提供 get 以及 find 两种语义的搜索：

  • get：表示搜索范围仅限于指定的 {@link AnnotatedElement} 本身
  • find：表示搜索范围除了指定的 {@link AnnotatedElement} 本身外，若 {@link AnnotatedElement} 是类，则还会搜索其所有关联的父类和父接口；若 {@link AnnotatedElement} 是方法，则还会搜索其声明类关联的所有父类和父接口中，与该方法具有相同方法签名的方法对象

# 🔍 搜索元注解

在所有格式为 getXXX 或 findXXX 的静态方法中，若不带有 directly 关键字，则该方法支持搜索元注解，否则不支持搜索元注解。

# 🗺️ 注解属性映射

支持注解对象属性上的一些属性映射机制：

  • 基于{@link Alias}的属性别名：若注解属性通过{@link Alias}互相关联，则对其中任意属性赋值，则等同于对所有关联属性赋值
  • 基于父子注解的属性覆写：若子注解中存在属性，与其元注解的属性名称、类型皆相同，则子注解的属性值将会覆写其元注解的属性值

# 🔄 可重复注解支持

格式为 findAllXXX 或 getAllXXX 格式的方法，支持获得 {@link AnnotatedElement} 上的可重复注解。

# 💾 缓存

为了避免注解以及{@link AnnotatedElement}层级结构解析过程中的大量反射调用，工具类为{@link AnnotatedElement}及其元注解信息进行了缓存。

# 🍭使用

# 🔍 find 相关方法（层级结构搜索，支持元注解）

# ✅ isAnnotated

功能介绍：在element所处层级结构的所有AnnotatedElement上，是否存在该类型的注解或元注解。

使用场景：需要判断一个类及其父类、父接口中是否存在某个注解或元注解时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 判断Child类及其层级结构中是否存在MyAnnotation注解
boolean isAnnotated = AnnotatedElementUtil.isAnnotated(Child.class, MyAnnotation.class);
// 输出：true
Console.log(isAnnotated);

# 🔍 findAnnotation

功能介绍：从element所处层级结构的所有AnnotatedElement上，获取该类型的注解或元注解。

使用场景：需要从一个类及其父类、父接口中获取某个注解或元注解时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@MyAnnotation("parent")
class Parent {
}

class Child extends Parent {
}

// 从Child类及其层级结构中获取MyAnnotation注解
MyAnnotation annotation = AnnotatedElementUtil.findAnnotation(Child.class, MyAnnotation.class);
// 输出：parent
Console.log(annotation.value());

# 📋 findAllAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。

使用场景：需要获取层级结构中所有指定类型的注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("parent1")
@MyAnnotation("parent2")
class Parent {
}

class Child extends Parent {
}

// 获取Child类及其层级结构中所有MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.findAllAnnotations(Child.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 📋 findAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解。

使用场景：需要获取层级结构中所有注解（包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 获取Child类及其层级结构中所有注解
Annotation[] annotations = AnnotatedElementUtil.findAnnotations(Child.class);
// 输出：1
Console.log(annotations.length);

# 🔧 findResolvedAnnotation

功能介绍：从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中带属性解析的注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class Parent {
}

class Child extends Parent {
}

// 获取带属性解析的注解
MyAnnotation annotation = AnnotatedElementUtil.findResolvedAnnotation(Child.class, MyAnnotation.class);
// 输出：test
Console.log(annotation.alias());

# 🔧 findResolvedAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中所有带属性解析的注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class Parent {
}

class Child extends Parent {
}

// 获取所有带属性解析的注解
Annotation[] annotations = AnnotatedElementUtil.findResolvedAnnotations(Child.class);
// 输出：1
Console.log(annotations.length);

# 🔧 findAllResolvedAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中所有带属性解析的指定类型注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class Parent {
}

class Child extends Parent {
}

// 获取所有带属性解析的MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.findAllResolvedAnnotations(Child.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 🔍 findDirectly 相关方法（层级结构搜索，不支持元注解）

# 🔍 findDirectlyAnnotation

功能介绍：从element所处层级结构的所有AnnotatedElement上获取该类型的注解（不搜索元注解）。

使用场景：需要从层级结构中获取直接注解（不包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 从层级结构中获取直接注解
MyAnnotation annotation = AnnotatedElementUtil.findDirectlyAnnotation(Child.class, MyAnnotation.class);
// 输出：parent
Console.log(annotation.annotationType().getSimpleName());

# 📋 findAllDirectlyAnnotations

功能介绍：从element上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。

使用场景：需要获取层级结构中所有直接指定类型的注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class Parent {
}

class Child extends Parent {
}

// 获取所有直接MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.findAllDirectlyAnnotations(Child.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 📋 findDirectlyAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上获取所有的注解（不搜索元注解）。

使用场景：需要获取层级结构中所有直接注解（不包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 获取层级结构中所有直接注解
Annotation[] annotations = AnnotatedElementUtil.findDirectlyAnnotations(Child.class);
// 输出：1
Console.log(annotations.length);

# 🔧 findDirectlyResolvedAnnotation

功能介绍：从element所处层级结构的所有AnnotatedElement上，获取所有的注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中带属性解析的直接注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class Parent {
}

class Child extends Parent {
}

// 获取带属性解析的直接注解
MyAnnotation annotation = AnnotatedElementUtil.findDirectlyResolvedAnnotation(Child.class, MyAnnotation.class);
// 输出：test
Console.log(annotation.alias());

# 🔧 findDirectlyResolvedAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上获取所有的注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中所有带属性解析的直接注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class Parent {
}

class Child extends Parent {
}

// 获取所有带属性解析的直接注解
Annotation[] annotations = AnnotatedElementUtil.findDirectlyResolvedAnnotations(Child.class);
// 输出：1
Console.log(annotations.length);

# 🔧 findAllDirectlyResolvedAnnotations

功能介绍：从element所处层级结构的所有AnnotatedElement上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。得到的注解支持基于{@link Alias}的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。

使用场景：需要获取层级结构中所有带属性解析的直接指定类型注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class Parent {
}

class Child extends Parent {
}

// 获取所有带属性解析的直接MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.findAllDirectlyResolvedAnnotations(Child.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 📦 get 相关方法（当前元素搜索，支持元注解）

# ✅ isAnnotationPresent

功能介绍：在element上，是否存在该类型的注解或元注解。

使用场景：需要判断一个元素上是否存在某个注解或元注解时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class MyClass {
}

// 判断元素上是否存在注解
boolean isPresent = AnnotatedElementUtil.isAnnotationPresent(MyClass.class, MyAnnotation.class);
// 输出：true
Console.log(isPresent);

# 📦 getAnnotation

功能介绍：从element上，获取该类型的注解或元注解。

使用场景：需要从元素上获取某个注解或元注解时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@MyAnnotation("test")
class MyClass {
}

// 从元素上获取注解
MyAnnotation annotation = AnnotatedElementUtil.getAnnotation(MyClass.class, MyAnnotation.class);
// 输出：test
Console.log(annotation.value());

# 📦 getAnnotations

功能介绍：从element上，获取所有的注解或元注解。

使用场景：需要获取元素上所有注解（包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class MyClass {
}

// 获取元素上所有注解
Annotation[] annotations = AnnotatedElementUtil.getAnnotations(MyClass.class);
// 输出：1
Console.log(annotations.length);

# 📦 getAllAnnotations

功能介绍：从element上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。

使用场景：需要获取元素上所有指定类型的注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class MyClass {
}

// 获取元素上所有MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.getAllAnnotations(MyClass.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 🔧 getResolvedAnnotation

功能介绍：从element上，获取所有的注解或元注解。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上带属性解析的注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class MyClass {
}

// 获取带属性解析的注解
MyAnnotation annotation = AnnotatedElementUtil.getResolvedAnnotation(MyClass.class, MyAnnotation.class);
// 输出：test
Console.log(annotation.alias());

# 🔧 getResolvedAnnotations

功能介绍：从element上，获取所有的注解或元注解。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上所有带属性解析的注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class MyClass {
}

// 获取所有带属性解析的注解
Annotation[] annotations = AnnotatedElementUtil.getResolvedAnnotations(MyClass.class);
// 输出：1
Console.log(annotations.length);

# 🔧 getAllResolvedAnnotations

功能介绍：从element上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上所有带属性解析的指定类型注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class MyClass {
}

// 获取所有带属性解析的MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.getAllResolvedAnnotations(MyClass.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 📦 getDirectly 相关方法（当前元素搜索，不支持元注解）

# 📦 getDirectlyAnnotation

功能介绍：从element上获取该类型的注解（不搜索元注解）。

使用场景：需要从元素上获取直接注解（不包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class MyClass {
}

// 从元素上获取直接注解
MyAnnotation annotation = AnnotatedElementUtil.getDirectlyAnnotation(MyClass.class, MyAnnotation.class);
// 输出：MyAnnotation
Console.log(annotation.annotationType().getSimpleName());

# 📦 getAllDirectlyAnnotations

功能介绍：从element上直接声明的注解、这些注解包含的可重复注解中获取指定类型注解。

使用场景：需要获取元素上所有直接指定类型的注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class MyClass {
}

// 获取元素上所有直接MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.getAllDirectlyAnnotations(MyClass.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# 📦 getDirectlyAnnotations

功能介绍：从element上获取所有的注解（不搜索元注解）。

使用场景：需要获取元素上所有直接注解（不包括元注解）时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class MyClass {
}

// 获取元素上所有直接注解
Annotation[] annotations = AnnotatedElementUtil.getDirectlyAnnotations(MyClass.class);
// 输出：1
Console.log(annotations.length);

# 🔧 getDirectlyResolvedAnnotation

功能介绍：从element上，获取所有的注解（不搜索元注解）。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上带属性解析的直接注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class MyClass {
}

// 获取带属性解析的直接注解
MyAnnotation annotation = AnnotatedElementUtil.getDirectlyResolvedAnnotation(MyClass.class, MyAnnotation.class);
// 输出：test
Console.log(annotation.alias());

# 🔧 getDirectlyResolvedAnnotations

功能介绍：从element上，获取所有的注解（不搜索元注解）。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上所有带属性解析的直接注解时使用。

使用示例：

// 定义带别名的注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@MyAnnotation("test")
class MyClass {
}

// 获取所有带属性解析的直接注解
Annotation[] annotations = AnnotatedElementUtil.getDirectlyResolvedAnnotations(MyClass.class);
// 输出：1
Console.log(annotations.length);

# 🔧 getAllDirectlyResolvedAnnotations

功能介绍：从element上直接声明的注解、这些注解包含的可重复注解中获取指定类型注解。得到的注解支持基于{@link Alias}的别名机制。

使用场景：需要获取元素上所有带属性解析的直接指定类型注解（包括可重复注解）时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    @Alias("alias")
    String value() default "";
    @Alias("value")
    String alias() default "";
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test1")
@MyAnnotation("test2")
class MyClass {
}

// 获取所有带属性解析的直接MyAnnotation注解
MyAnnotation[] annotations = AnnotatedElementUtil.getAllDirectlyResolvedAnnotations(MyClass.class, MyAnnotation.class);
// 输出：2
Console.log(annotations.length);

# ⚙️ to Element 相关方法（元素转换）

# 🔄 toHierarchyMetaElement

功能介绍：扫描element所处层级结构中的AnnotatedElement，并将其全部转为MetaAnnotatedElement后，再把所有对象合并为HierarchicalAnnotatedElements。得到的对象可访问element所处层级结构中所有AnnotatedElement上的注解及元注解。

使用场景：需要将层级结构转换为可访问所有注解的元素时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 转换为层级元元素
AnnotatedElement element = AnnotatedElementUtil.toHierarchyMetaElement(Child.class, false);
// 获取注解
MyAnnotation annotation = element.getAnnotation(MyAnnotation.class);
// 输出：true
Console.log(annotation != null);

# 🔄 toHierarchyRepeatableMetaElement

功能介绍：扫描element所处层级结构中的AnnotatedElement，并将其全部转为RepeatableMetaAnnotatedElement后，再把所有对象合并为HierarchicalAnnotatedElements。得到的对象可访问element所处层级结构中所有AnnotatedElement上的直接声明的注解，这些注解包含的可重复注解，以及上述注解的所有元注解。

使用场景：需要将层级结构转换为可访问所有可重复注解的元素时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test")
class Parent {
}

class Child extends Parent {
}

// 转换为可重复层级元元素
AnnotatedElement element = AnnotatedElementUtil.toHierarchyRepeatableMetaElement(Child.class, false);
// 获取注解数组
MyAnnotation[] annotations = element.getAnnotationsByType(MyAnnotation.class);
// 输出：1
Console.log(annotations.length);

# 🔄 toHierarchyElement

功能介绍：扫描element所处层级结构中的AnnotatedElement，再把所有对象合并为HierarchicalAnnotatedElements。得到的对象可访问element所处层级结构中所有AnnotatedElement上的注解。

使用场景：需要将层级结构转换为可访问所有元素的注解时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class Parent {
}

class Child extends Parent {
}

// 转换为层级元素
AnnotatedElement element = AnnotatedElementUtil.toHierarchyElement(Child.class);
// 获取注解
MyAnnotation annotation = element.getAnnotation(MyAnnotation.class);
// 输出：true
Console.log(annotation != null);

# 🔄 toMetaElement

功能介绍：将AnnotatedElement转为MetaAnnotatedElement，得到的对象可访问element上所有的注解及元注解。

使用场景：需要将元素转换为可访问元注解的元素时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
}

@MyAnnotation
class MyClass {
}

// 转换为元元素
AnnotatedElement element = AnnotatedElementUtil.toMetaElement(MyClass.class, false);
// 获取注解
MyAnnotation annotation = element.getAnnotation(MyAnnotation.class);
// 输出：true
Console.log(annotation != null);

# 🔄 toRepeatableMetaElement

功能介绍：将AnnotatedElement转为RepeatableMetaAnnotatedElement，得到的对象可访问AnnotatedElement上的直接声明的注解，这些注解包含的可重复注解，以及上述注解的所有元注解。

使用场景：需要将元素转换为可访问可重复注解的元素时使用。

使用示例：

// 定义可重复注解
@Repeatable(MyAnnotations.class)
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotations {
    MyAnnotation[] value();
}

@MyAnnotation("test")
class MyClass {
}

// 转换为可重复元元素
AnnotatedElement element = AnnotatedElementUtil.toRepeatableMetaElement(MyClass.class, false);
// 获取注解数组
MyAnnotation[] annotations = element.getAnnotationsByType(MyAnnotation.class);
// 输出：1
Console.log(annotations.length);

# 🔄 asElement

功能介绍：将一组注解中的非null注解对象合并为一个AnnotatedElement。

使用场景：需要将多个注解合并为一个AnnotatedElement时使用。

使用示例：

// 定义注解
@Target(ElementType.TYPE_USE)
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
    String value();
}

// 创建注解实例
MyAnnotation annotation1 = new MyAnnotation() {
    @Override
    public String value() {
        return "test1";
    }

    @Override
    public Class<? extends Annotation> annotationType() {
        return MyAnnotation.class;
    }
};

// 合并注解为元素
AnnotatedElement element = AnnotatedElementUtil.asElement(annotation1);
// 获取注解
MyAnnotation annotation = element.getAnnotation(MyAnnotation.class);
// 输出：test1
Console.log(annotation.value());

# ⚪ emptyElement

功能介绍：获取一个不包含任何注解的AnnotatedElement。

使用场景：需要一个空的AnnotatedElement实例时使用。

使用示例：

// 获取空元素
AnnotatedElement element = AnnotatedElementUtil.emptyElement();
// 获取注解数量
Annotation[] annotations = element.getAnnotations();
// 输出：0
Console.log(annotations.length);

# 🛠️ 其他工具方法

# 🧹 clearCaches

功能介绍：清空相关缓存，包括AnnotatedElementUtil中的AnnotatedElement及AnnotationMapping缓存、AnnotationUtil中的AnnotatedElement上直接声明的注解缓存、RepeatableAnnotationCollector中单例的注解属性缓存。

使用场景：需要主动清空注解缓存时使用。

使用示例：

// 清空缓存
AnnotatedElementUtil.clearCaches();
// 缓存已清空
Console.log("Caches cleared");
注解工具-AnnotationUtil
简介

← 简介→

Theme by Vdoing | Copyright © 2025-2026 Hutool | Apache-2.0