Java 注解详解：类型、放置位置与实战示例

Java 注解详解

发现 Java 注解是什么、如何分类、如何有效应用，配合清晰的真实案例。

注解是嵌入源代码的元数据，向编译器并在需要时向运行时系统传达额外信息。它们不成为执行字节码的一部分，但可影响编译、代码生成和反射。

注解总以 @ 符号开头。最常见语法：

@AnnotationName

@Override 注解实战

@Override 注解表明方法意在重写父类方法。虽非强制，但使用它可让编译器标记签名不匹配等错误。

示例 1：@Override 注解

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

输出

I am a dog. 

此例中 displayInfo() 存在于 Animal 和 Dog。Dog 中重写的方法被执行，演示多态。

注解格式

注解可包含成员（属性）。分为三大类：

1. 标记注解

不包含元素，仅作标记。括号可选。

@AnnotationName

2. 单元素注解

包含一个元素，惯例命名为 value。仅有一元素时可省略元素名。

@AnnotationName("elementValue")

3. 多元素注解

包含多个元素，逗号分隔。

@AnnotationName(element1 = "value1", element2 = "value2")

注解放置位置

注解可置于任何声明之前：类、方法、字段、接口等。Java 8 起也可注解类型。

1. 声明上方

典型位置：直接置于目标声明上方。

示例 2：@SuppressWarnings 注解

import java.util.*; class Main { @SuppressWarnings("unchecked") static void wordsList() { ArrayList wordList = new ArrayList<>(); // 这会导致未检查警告 wordList.add("programiz"); System.out.println("Word list => " + wordList); } public static void main(String args[]) { wordsList(); } } 

输出

Word list => [programiz] 

无 @SuppressWarnings("unchecked")，编译器会发出未检查操作警告。示例也展示泛型如何消除此警告：

ArrayList<String> wordList = new ArrayList<>();

2. 类型注解（Java 8+）

类型注解允许注解类型的任何出现，增强静态分析与空安全。

// 构造器调用 new @Readonly ArrayList<>(); // 类型定义 @NonNull String str; @NonNull List<String> newList; List<@NonNull String> newList; // 类型转换 newStr = (@NonNull String) str; // Extends/implements class Warning extends @Localized Message // Throws 子句 public String readMethod() throws @Localized IOException 

这些注解赋能工具强制更强类型检查，预防 NullPointerException 等运行时错误。

注解类型

1. 预定义注解
   • @Deprecated
   • @Override
   • @SuppressWarnings
   • @SafeVarargs
   • @FunctionalInterface
2. 元注解
   • @Retention
   • @Documented
   • @Target
   • @Inherited
   • @Repeatable
3. 自定义注解

   为项目定义领域特定注解。参考 Java 注解类型教程 指导。

注解的实用用途

• 编译器指令 —— 提供编译期检查和警告。常见：@Deprecated、@Override、@SuppressWarnings。
• 构建时指令 —— 让构建工具基于注解元数据生成辅助文件（XML、字节码等）。
• 运行时行为 —— 某些注解保留至运行时，通过 Java 反射访问，允许框架动态注入行为。