Java注解（Annotation）从JDK 5开始进入标准语法，它不会直接参与业务逻辑计算，但可以通过编译器检查、IDE提示、文档生成和运行时反射等途径影响程序行为。标准库提供的注解并不是杂乱堆叠，而是围绕代码质量、API演化和元数据描述形成了清晰的层次。掌握这些内置注解的适用场景和限制，对阅读集合框架、并发包以及主流第三方库源码帮助很大。
一、直接作用于代码元素的普通注解
Java内置的普通注解主要解决方法签名校验、过时API提示和编译警告控制等问题。最常接触的是@Override，它只能用于方法，用来告诉编译器该方法必须重写父类方法或实现接口方法。如果父类或接口中找不到对应签名，编译会直接报错。这个注解最大的价值不是美化代码，而是防止开发者在重写equals、hashCode等方法时把参数类型写错。例如equals的合法参数是Object，一旦写成当前类类型，就变成了重载而不是重写，不加上@Override编译器不会提示任何错误。
class Parent {
public void show() {
System.out.println("parent");
}
}
class Child extends Parent {
@Override
public void show() {
System.out.println("child");
}
}
@Deprecated用于标记已经过时、不推荐继续使用的API。它可以标注类、方法、字段、构造器、接口、枚举以及参数等位置。当代码继续调用被标记的元素时，编译器会产生弃用警告，IDE通常会在引用处显示删除线。从Java 9开始，@Deprecated增加了since和forRemoval两个属性，前者说明从哪个版本开始弃用，后者表示该API未来是否会被彻底移除。这个信息对维护旧系统很有价值，可以提前规划替换方案。
public class LegacyService {
@Deprecated(since = "1.5", forRemoval = true)
public void oldExecute() {
// 旧逻辑
}
}
@SuppressWarnings用来抑制指定类型的编译警告。它的值是一个字符串数组，常见取值包括unchecked、rawtypes、deprecation、serial等。这个注解可以出现在类、方法、字段、局部变量等大部分元素上，但官方建议尽量缩小抑制范围，避免大范围隐藏警告。因为警告往往是潜在类型安全问题的信号，如果整类压制unchecked，很可能把真正的类型转换风险掩盖掉。理想做法是只在确认安全的局部变量或单条语句上使用。
@SuppressWarnings("unchecked")
public List<String> convert(Object data) {
return (List<String>) data;
}
Java 7引入的@SafeVarargs用于抑制泛型可变参数方法在声明和调用处出现的堆污染警告。可变参数本质上会编译成数组，而Java不允许直接创建不可具体化的泛型数组，因此编译器会发出警告。只有当方法内部不会对参数数组执行危险操作，例如不会把Object数组强制转换为T数组时，才可以使用这个注解。它只能标注static、final方法、构造器以及从Java 9开始的private实例方法。
public final class ArrayUtils {
@SafeVarargs
public static <T> List<T> asList(T... items) {
return Arrays.asList(items);
}
}
Java 8引入的@FunctionalInterface用于标记函数式接口。函数式接口只能有一个抽象方法，编译器会在编译期校验这个约束。接口中声明为default或static的方法不计数，覆盖Object公有方法也不计数。加上这个注解后，如果后续维护中不小心增加第二个抽象方法，编译器会立即报错，从而保证该接口可以继续被Lambda表达式和方法引用使用。
@FunctionalInterface
public interface Calculator {
int compute(int a, int b);
default void print(int result) {
System.out.println(result);
}
}
二、控制注解行为的元注解
元注解负责描述其他注解的特性，它们决定了注解的存活阶段、可标注位置、文档记录、继承关系以及是否可重复。标准库提供了五个元注解，理解它们是自定义注解的前提。
@Retention的取值来自RetentionPolicy枚举，分为SOURCE、CLASS和RUNTIME三种。SOURCE表示注解只保留在源码阶段，编译后就会被丢弃，典型代表是@SuppressWarnings；CLASS是默认策略，保留到字节码中，但运行时不可见；RUNTIME则会随类文件加载进JVM，可以通过反射读取。很多框架注解都要标注为RUNTIME，例如Spring的@Autowired，否则运行时容器无法识别。
@Target通过ElementType枚举限制注解可以出现的位置，常见值包括TYPE、FIELD、METHOD、PARAMETER、CONSTRUCTOR、LOCAL_VARIABLE、ANNOTATION_TYPE、PACKAGE等。Java 8还增加了TYPE_PARAMETER和TYPE_USE，让注解可以标注泛型参数和任意使用类型的位置。合理设置@Target可以在编译期阻止误用，例如只允许注解标注字段，就不该出现在方法参数上。
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface AuditLog {
String action();
}
@Documented表示该注解会出现在Javadoc文档中。如果希望使用者在查看API文档时看到某个注解标记，就需要添加这个元注解。@Inherited则控制注解是否能被子类继承。它的作用范围仅限于类继承，如果父类上带有@Inherited修饰的注解，子类通过getAnnotation也能读到；但接口实现、方法重写等场景不会继承注解，这一点经常被误用。
@Repeatable允许同一个注解在同一个位置重复出现。使用它必须提供一个容器注解，容器内包含注解数组。例如Java中的@Schedule可以重复标注一个定时任务方法，背后就是通过@Repeatable指定了Schedules容器。读取重复注解时，应使用getAnnotationsByType而不是getAnnotation，否则单值返回逻辑可能无法取到全部实例。
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Repeatable(Roles.class)
public @interface Role {
String value();
}
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Roles {
Role[] value();
}
三、实际使用中的几个关键细节
内置注解虽然简单，但在工程实践中仍然有不少容易踩坑的地方。首先是@Inherited的继承范围。很多开发者以为注解的继承和类的继承完全一致，实际上只有类继承会触发继承规则，接口继承、实现接口、方法重写都不会把父接口或父方法的注解带过去。因此，如果想在框架中通过接口注解控制所有实现类，@Inherited并不是有效手段，需要框架自己编写解析逻辑或使用组合扫描。
其次是@Repeatable与反射读取的匹配问题。声明为可重复的注解，编译后会被打包进容器注解里。反射调用getAnnotation(Role.class)通常会得到null，因为实际存在的是Roles容器。正确做法是调用getAnnotationsByType(Role.class)，这个API会同时检查直接注解和容器注解，使用起来更可靠。
再次是@SuppressWarnings的粒度。虽然把它加在类上最省事，但长期来看会隐藏类型安全问题。比较合理的策略是先在局部变量或短方法上使用，配合注释说明为什么这个警告可以被安全忽略。如果代码库中大量出现整类压制警告，往往意味着泛型设计或旧代码兼容层存在改进空间。
最后需要明确，注解本身不会在运行期主动执行逻辑，它们只是元数据。真正产生效果的是编译器、IDE或运行时框架对这些元数据的读取与处理。因此，选择RUNTIME保留策略会带来微弱的反射查询开销，但在大多数业务场景中可以忽略不计。对于只用于编译期检查的注解，尽量选择SOURCE或CLASS，让字节码保持干净。理解这些内置注解的职责边界之后，再阅读Spring、MyBatis等框架中大量出现的自定义注解，思路会清晰很多。