Java 注解介绍

定义

Java注解又称Java标注，是Java语言5.0版本开始支持加入源代码的特殊语法元数据（元数据 Metadata：描述数据的数据）。

Java语言中的类、方法、变量、参数和包等都可以被标注。和Javadoc不同，Java标注可以通过反射获取标注内容。在编译器生成类文件时，标注可以被嵌入到字节码中。Java虚拟机可以保留标注内容，在运行时可以获取到标注内容。 当然它也支持自定义Java标注

内置的注解

Java 5 定义了一套注解，共有 7 个，3 个在 java.lang 中，剩下 4 个在 java.lang.annotation 中。

作用在代码的注解（java.lang包中）

• @Override - 检查该方法是否是重载方法。如果发现其父类，或者是引用的接口中并没有该方法时，会报编译错误。
• @Deprecated - 标记过时方法。如果使用该方法，会报编译警告。
• @SuppressWarnings - 指示编译器去忽略注解中声明的警告。

作用在其他注解的注解(或者说 元注解，java.lang.annotation包中)

• @Retention - 标识这个注解怎么保存，是只在代码中，还是编入class文件中，或者是在运行时可以通过反射访问。
• @Documented - 标记这些注解是否包含在用户文档中。
• @Target - 标记这个注解应该是哪种 Java 成员。
• @Inherited - 标记这个注解是继承于哪个注解类(默认 注解并没有继承于任何子类)

从 Java 7 开始，额外添加了 3 个注解

• @SafeVarargs - Java 7 开始支持，忽略任何使用参数为泛型变量的方法或构造函数调用产生的警告。
• @FunctionalInterface - Java 8 开始支持，标识一个匿名函数或函数式接口。
• @Repeatable - Java 8 开始支持，标识某注解可以在同一个声明上使用多次。

功能

注解可以用于许多不同的目的，最常见的是：

• 给编译器提供信息：编译器可以使用注解来产生警告，甚至根据不同的规则产生错误。 这种用法的一个例子是Java 8 的 @FunctionalInterface 注解。 这使编译器验证注释类，并检查它是否是一个正确的功能接口。
• 文档化：软件应用程序可以使用注解来测量代码的质量，如FindBugs或PMD，或者像Jenkins，Jira或Teamcity一样自动生成报告。
• 代码生成：使用注解可以使用代码中存在的元数据信息自动生成代码或XML文件。 JAXB库就是一个很好的例子。
• 运行时处理：在运行时检查的注解可用于不同的目标，如单元测试（Junit），依赖注入（Spring），验证，日志记录（Log4J），数据访问（Hibernate）等。

实际例子

讲个 Java 官方提供的例子，用注解实现简单的测试框架。

@MyTest 注解

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

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface MyTest {

}

FooTest 测试类

public class FooTest {

    @MyTest
    public static void m1() {
    }

    public static void m2() {
    }

    @MyTest
    public static void m3() {
        throw new RuntimeException("Boom");
    }

    public static void m4() {
    }

    @MyTest
    public static void m5() {
    }

    public static void m6() {
    }

    @MyTest
    public static void m7() {
        throw new RuntimeException("Crash");
    }

    public static void m8() {
    }
}

RunMyTests 测试执行类

import java.lang.reflect.Method;

public class RunMyTests {
    public static void main(String[] args) throws Exception {
        int passed = 0;
        int failed = 0;

        if (args.length < 1) {
            System.out.println("please give test class.");
            System.exit(1);
        }

        for (Method method : Class.forName(args[0]).getMethods()) {
            if (method.isAnnotationPresent(MyTest.class)) {
                try {
                    method.invoke(null);
                    passed++;
                } catch (Throwable ex) {
                    System.out.printf("Test %s failed: %s %n", method, ex.getCause());
                    failed++;
                }
            }
        }
        System.out.printf("Passed: %d, Failed %d%n", passed, failed);
    }
}

编译、运行测试执行类

> javac FooTest.java MyTest.java RunMyTests.java
> java RunMyTests FooTest
Test public static void FooTest.m3() failed: java.lang.RuntimeException: Boom
Test public static void FooTest.m7() failed: java.lang.RuntimeException: Crash
Passed: 2, Failed 2

参考

• Java Annotations Tutorial – The ULTIMATE Guide (PDF Download)
• JSR 175 A metadata facility for the Java programming Language
• JSR 250 Common Annotations for the Java Platform
• Java 注解深入理解
• Lesson: Annotations