Java 注解类型完全指南：预定义、自定义与元注解

Java 注解类型

本教程涵盖 Java 注解 —— 预定义、自定义与元注解，配合清晰示例。

Java 注解是描述源代码元素的元数据。Java SE 平台提供一组标准注解，开发者也可创建针对项目的自定义注解。注解本身也可被注解，形成元注解。

注解分三类：

1. 预定义注解 —— Java 平台内置。
2. 自定义注解 —— 用户为特定需求定义。
3. 元注解 —— 应用于其他注解的注解。

---

预定义注解类型

1. @Deprecated

@Deprecated 标记类、方法、字段或其他元素已过时，有更好替代。编译器在使用过时元素时发出警告。

语法：

@Deprecated public void oldMethod() { ... }

Javadoc 提供 @deprecated 标签用于文档：

/** * @deprecated * Use {@link #newMethod()} instead. */ @Deprecated public void oldMethod() { ... }

示例

class Main { /** * @deprecated * This method is deprecated and has been replaced by newMethod() */ @Deprecated public static void deprecatedMethod() { System.out.println("Deprecated method"); } public static void main(String[] args) { deprecatedMethod(); } }

输出

Deprecated method

---

2. @Override

@Override 表明方法意在重写父类或接口方法。虽非强制，但能在编译期捕获签名不匹配等错误。

示例

class Animal { public void display() { System.out.println("I am an animal"); } } class Dog extends Animal { @Override public void display() { System.out.println("I am a dog"); } public void printMessage() { display(); } } class Main { public static void main(String[] args) { Dog dog1 = new Dog(); dog1.printMessage(); } }

输出

I am a dog

---

3. @SuppressWarnings

此注解指示编译器忽略特定警告类别。常见类别包括 deprecation 和 unchecked。

用法：

@SuppressWarnings("deprecation")

多类别：

@SuppressWarnings({"deprecation", "unchecked"})

示例

class Main { @Deprecated public static void deprecatedMethod() { System.out.println("Deprecated method"); } @SuppressWarnings("deprecation") public static void main(String[] args) { Main depObj = new Main(); depObj.deprecatedMethod(); } }

输出

Deprecated method

---

4. @SafeVarargs

应用于 final、static 或私有方法和构造器，@SafeVarargs 断言方法不对可变参数执行不安全操作。这消除与可变参数相关的未检查警告。

示例

import java.util.*; class Main { @SafeVarargs private static void displayList(List<String>... lists) { for (List<String> list : lists) { System.out.println(list); } } public static void main(String[] args) { List<String> universityList = Arrays.asList("Tribhuvan University", "Kathmandu University"); List<String> programmingLanguages = Arrays.asList("Java", "C"); displayList(universityList, programmingLanguages); } }

输出

[Tribhuvan University, Kathmandu University] [Java, C]

---

5. @FunctionalInterface

Java 8 引入，此注解将接口指定为函数式接口 —— 仅含单个抽象方法的接口。编译器验证此约束。

示例

@FunctionalInterface public interface MyFuncInterface { void firstMethod(); // 抽象 }

添加第二个抽象方法触发编译错误：

@FunctionalInterface public interface MyFuncInterface { void firstMethod(); void secondMethod(); // 编译时错误 }

允许多个默认或静态方法。

@FunctionalInterface public interface MyFuncInterface { void firstMethod(); default void secondMethod() { /* ... */ } default void thirdMethod() { /* ... */ } }

---

自定义注解

开发者可创建适应应用特定需求的注解。语法用 @interface，可包含带可选默认值的元素方法。

语法

@interface AnnotationName { ElementType elementName() default defaultValue; }

示例

@interface MyCustomAnnotation { String value() default "default value"; } class Main { @MyCustomAnnotation(value = "programiz") public void method1() { System.out.println("Test method 1"); } public static void main(String[] args) { new Main().method1(); } }

输出

Test method 1

---

元注解

元注解配置其他注解的行为。

1. @Retention

定义注解可见性范围：SOURCE、CLASS 或 RUNTIME。

@Retention(RetentionPolicy.RUNTIME) public @interface MyAnnotation { }

2. @Documented

确保注解出现在生成的 Javadoc 中。

@Documented public @interface MyAnnotation { }

3. @Target

限制注解适用的程序元素。

@Target(ElementType.METHOD) public @interface MyAnnotation { }

元素类型包括 ANNOTATION_TYPE、CONSTRUCTOR、FIELD、LOCAL_VARIABLE、METHOD、PACKAGE、PARAMETER、TYPE。

4. @Inherited

允许子类继承父类上的注解。

@Inherited public @interface MyAnnotation { }

5. @Repeatable

允许注解在同一元素上多次应用。需容器注解。

@Repeatable(Universities.class) public @interface University { String name(); } public @interface Universities { University[] value(); }

用法：

@University(name = "TU") @University(name = "KU") private String uniName;

---

运行时访问注解数据，使用反射 API 的 getAnnotationsByType() 或 getAnnotations() 方法。