Java 注解（Annotation）详解：从基础到 APT 实战

前言注解是 Java 提供的一种元编程能力它像标签一样贴在代码的类、方法、字段上可以被编译器或运行时读取并处理。从 Java 5 引入至今注解已经彻底改变了 Java 生态 —— Spring、Lombok、JUnit 等框架的核心都离不开注解。但很多开发者对注解的理解停留在Override和Autowired的用法上不清楚注解的本质是什么也不知道如何编写自定义注解更不了解编译期注解处理器APT这种黑科技。本文将带你从零到一掌握注解并手写一个简单的Getter注解处理器生成 getter 方法。一、注解的本质是什么先看一个常见注解Override的源码javaTarget(ElementType.METHOD) Retention(RetentionPolicy.SOURCE) public interface Override { }使用interface关键字定义注解它本质上是一个继承自java.lang.annotation.Annotation接口的特殊接口。反编译后可以看到javapublic interface Override extends Annotation { }注解可以包含成员属性形式类似于方法javapublic interface MyAnnotation { String value() default ; int count() default 0; }使用时MyAnnotation(value hello, count 5)二、元注解 —— 注解的注解元注解作用Target限定注解可以贴在哪些位置类、方法、字段、参数等Retention注解保留到何时源码、字节码、运行时Documented是否被 Javadoc 收录Inherited子类是否可以继承父类上的该注解Repeatable(Java 8)允许在同一位置重复使用同一注解2.1 Retention 的三种策略策略生效时机典型场景SOURCE仅存在源码中编译后丢弃代码检查Override、LombokCLASS编译时保留在字节码中但运行时不可见字节码插桩工具RUNTIME运行时仍可通过反射读取Spring、JUnit运行时需要读取javaRetention(RetentionPolicy.RUNTIME) Target(ElementType.METHOD) public interface Test { }2.2 Target 常用取值javaElementType.TYPE // 类、接口、枚举 ElementType.FIELD // 字段 ElementType.METHOD // 方法 ElementType.PARAMETER // 方法参数 ElementType.CONSTRUCTOR // 构造器 ElementType.LOCAL_VARIABLE // 局部变量 ElementType.ANNOTATION_TYPE // 注解类型 ElementType.PACKAGE // 包三、自定义注解并运行时解析反射3.1 定义一个权限检查注解javaRetention(RetentionPolicy.RUNTIME) Target(ElementType.METHOD) public interface RequiresPermission { String value(); }3.2 使用注解javapublic class UserService { RequiresPermission(admin) public void deleteUser(Long userId) { System.out.println(删除用户: userId); } public void listUsers() { System.out.println(列出所有用户); } }3.3 通过反射读取注解并处理javapublic class SecurityAspect { public static void invokeWithPermissionCheck(Object obj, String methodName, Object... args) throws Exception { Method method obj.getClass().getMethod(methodName, getParameterTypes(args)); if (method.isAnnotationPresent(RequiresPermission.class)) { RequiresPermission anno method.getAnnotation(RequiresPermission.class); String required anno.value(); if (!admin.equals(getCurrentUserRole())) { throw new SecurityException(权限不足需要: required); } } method.invoke(obj, args); } private static String getCurrentUserRole() { // 模拟获取当前登录用户角色 return guest; } private static Class?[] getParameterTypes(Object[] args) { return Arrays.stream(args).map(Object::getClass).toArray(Class[]::new); } public static void main(String[] args) throws Exception { UserService service new UserService(); invokeWithPermissionCheck(service, deleteUser, 1L); // 抛出异常 } }运行时注解是 Spring AOP 的实现基石但反射有一定性能开销。四、编译期注解处理器APT—— Lombok 的秘密Lombok 的Getter、Data就是在编译期修改抽象语法树AST生成代码。我们来实现一个简化版Getter。4.1 定义注解保留到 SOURCEjavaRetention(RetentionPolicy.SOURCE) Target(ElementType.FIELD) public interface Getter { }4.2 编写注解处理器需要依赖javax.annotation.processing.*和com.sun.source.tree.*Maven 需添加 tools.jar。javaSupportedAnnotationTypes(com.example.Getter) SupportedSourceVersion(SourceVersion.RELEASE_8) public class GetterProcessor extends AbstractProcessor { Override public boolean process(Set? extends TypeElement annotations, RoundEnvironment roundEnv) { for (Element element : roundEnv.getElementsAnnotatedWith(Getter.class)) { if (element.getKind() ! ElementKind.FIELD) { processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, Getter only applies to fields, element); continue; } // 获取包含该字段的类 Element enclosingClass element.getEnclosingElement(); String fieldName element.getSimpleName().toString(); TypeMirror fieldType element.asType(); String methodName get capitalize(fieldName); // 生成 getter 方法的代码字符串 String code public fieldType methodName () { return fieldName ; }; // 通过 Filer 写入新文件过于复杂实际 Lombok 直接修改 AST // 这里简化演示输出信息 processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, Generated getter: code, element); } return true; } private String capitalize(String str) { return str.substring(0, 1).toUpperCase() str.substring(1); } }注意真正修改类字节码需要使用 Java 编译器 API 或 Lombok 的JavacAnnotationHandler机制。感兴趣的可以研究 Lombok 源码。但了解 APT 工作原理已经能帮你理解很多框架。4.3 注册注解处理器在resources/META-INF/services/javax.annotation.processing.Processor文件中写入处理器的全限定名。五、注解在主流框架中的应用框架注解示例用途SpringController,Autowired,TransactionalIoC、AOP、声明式事务JUnitTest,BeforeEach,ParameterizedTest单元测试生命周期LombokData,Slf4j编译期代码生成JacksonJsonProperty,JsonIgnore序列化/反序列化控制HibernateEntity,Column,OneToManyORM 映射FeignFeignClient,GetMapping,RequestParam声明式 HTTP 客户端SwaggerApiOperation,ApiParamAPI 文档生成六、最佳实践与常见坑6.1 ❌ 错误试图在 SOURCE 注解上使用反射javaRetention(RetentionPolicy.SOURCE) interface A {} // 运行时获取不到返回 null A a SomeClass.class.getAnnotation(A.class); // null6.2 ❌ 错误注解成员类型不受支持支持的成员类型基本类型、String、Class、枚举、注解、以及上述类型的数组。不能用普通对象或包装类。java// 编译错误 public interface Bad { Integer value(); // Integer 不允许应用 int }6.3 ✅ 使用默认值减少冗余javapublic interface Mapping { String path() default ; RequestMethod method() default RequestMethod.GET; }6.4 ✅ 注解作为元数据业务的逻辑应由代码实现注解不是魔法它是数据。真正干活的还是你的拦截器、AOP、处理器。七、面试高频题Q1: 注解可以被继承吗被Inherited标记的注解当贴在父类上时子类可以自动继承但仅限于类继承接口不行。反射获取时需要看是否有该元注解。Q2: 如何在同一属性上重复使用同一个注解Java 8 引入Repeatable定义容器注解javaRepeatable(Roles.class) interface Role { String value(); } interface Roles { Role[] value(); } // 使用 Role(admin) Role(user) public void doSomething() {}Q3: 运行时注解的性能影响每次getAnnotation都会遍历注解属性并生成动态代理对象频繁调用有明显损耗。建议在启动时缓存。总结保留策略可见性典型应用SOURCE编译后消失Lombok、代码检查CLASS字节码保留运行时不可见字节码框架ASMRUNTIME反射可见Spring、ORM、测试框架注解是 Java 元编程的入口掌握它意味着你能理解主流框架的设计思想甚至写出自己的代码生成工具。如果你对 APT 感兴趣强烈建议去读一下 Lombok 源码会让你对 Java 编译过程的理解跃升一个台阶。