Java 注解与反射实战：自定义注解的定义与应用

如果把 @Log 标注在字段上，编译器会直接报错，因为超出了允许的范围。

@Retention：指定注解的生命周期

@Retention 决定注解保留到哪个阶段（源码、字节码、运行时）。必须指定 RetentionPolicy 枚举：

• SOURCE：仅存在于源码中，编译后丢弃（如 @Override）
• CLASS：保留到字节码中，但 JVM 运行时不加载（默认值）
• RUNTIME：保留到运行时，JVM 加载，可通过反射获取

要让注解在运行时被反射读取，关键是将保留策略设为 RUNTIME：

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)
public @interface Permission {
    String value();
}

这是注解与反射结合的核心前提，因为只有 RUNTIME 级别的注解才能被反射读取。

@Documented：让注解出现在 API 文档中

默认情况下，javadoc 生成的文档不会包含注解信息。@Documented 修饰的注解会被包含在文档中。

@Inherited：让注解可被继承

@Inherited 表示注解具有继承性：如果父类被该注解标注，子类会自动继承该注解（仅对类注解有效，方法/字段注解不继承）。

import java.lang.annotation.Inherited;

@Inherited
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface InheritedAnnotation {}

class Parent {
    @InheritedAnnotation
}

class Child extends Parent {}

通过反射验证，Child.class.isAnnotationPresent(InheritedAnnotation.class) 会返回 true。

结合反射让注解生效

注解本身只是标记，必须通过反射获取注解信息并执行逻辑，才能真正发挥作用。反射提供了 getAnnotation、getAnnotations、isAnnotationPresent 等核心方法。

下面通过一个实战案例演示：用注解实现方法权限校验。

需求：定义 @RequiresPermission 注解，标记方法需要的权限；通过反射调用方法前检查当前用户是否有权限，无权限则抛出异常。

首先定义注解，限定仅用于方法且保留到运行时：

import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequiresPermission {
    String[] value();
}

接着使用注解标注方法：

public class UserService {
    @RequiresPermission("user:query")
    public void queryUser() {
        System.out.println("查询用户成功");
    }

    @RequiresPermission({"user:add", "admin"})
    public void addUser() {
        System.out.println("新增用户成功");
    }
}

最后编写反射 + 注解实现权限校验的逻辑：

import java.lang.reflect.Method;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

public class PermissionChecker {
    private static final Set<String> CURRENT_USER_PERMISSIONS = new HashSet<>(Arrays.asList("user:query"));

    public static void invokeWithCheck(Object obj, String methodName) throws Exception {
        Method method = obj.getClass().getMethod(methodName);

        if (method.isAnnotationPresent(RequiresPermission.class)) {
            RequiresPermission annotation = method.getAnnotation(RequiresPermission.class);
            String[] requiredPermissions = annotation.value();

            boolean hasPermission = false;
            for (String permission : requiredPermissions) {
                if (CURRENT_USER_PERMISSIONS.contains(permission)) {
                    hasPermission = true;
                    break;
                }
            }

            if (!hasPermission) {
                throw new SecurityException("权限不足，需要：" + Arrays.toString(requiredPermissions));
            }
        }
        method.invoke(obj);
    }

    public static void main(String[] args) throws Exception {
        UserService service = new UserService();
        invokeWithCheck(service, "queryUser"); // 成功
        invokeWithCheck(service, "addUser");   // 失败：抛出 SecurityException
    }
}

运行结果会显示查询成功，而新增操作因权限不足抛出异常。这种模式在实际项目中非常常见，比如 Spring AOP 的实现原理就与此类似。

底层实现机制简述

理解底层有助于更好地使用注解。当 JVM 加载被注解的类时，会通过动态代理生成注解接口的实现类实例，保存注解属性值。反射通过 getAnnotation() 方法从类/方法的元数据中获取代理实例，从而读取属性值。

简单来说，@interface 编译后会生成一个继承 java.lang.annotation.Annotation 的接口，例如：

public interface MyAnnotation extends Annotation {
    String value();
    int age() default 18;
}

常见应用场景

注解 + 反射的组合在框架中被广泛使用：

• 日志记录：通过注解标记需要记录日志的方法，反射拦截并打印日志。
• ORM 映射：用注解关联 Java 类与数据库表（如 JPA 的@Entity、@Column）。
• 依赖注入：标记需要注入的对象（如 Spring 的@Autowired）。
• AOP 切面：通过注解定义切入点（如 Spring 的@Before、@After）。
• 参数校验：验证方法参数合法性（如 Jakarta 的@NotNull、@Size）。

总结

自定义注解是 Java 中'声明式编程'的核心体现，结合反射能极大简化代码逻辑、提高灵活性。掌握元注解的作用（尤其是@Target 和@Retention）是定义有效注解的前提，而反射则是让注解从'标记'变为'可执行逻辑'的桥梁。

在实际项目中应用注解处理重复逻辑，能显著提升代码的灵活性与可维护性。建议尝试在现有模块中引入自定义注解来优化代码结构。