Java注解

学习前提，对 Java 反射技术有一定了解。

一些常用注解

javadoc注释标签语法

@author 对类的说明标明开发该类模块的作者
@version 对类的说明 标明该类模块的版本
@see 对类、属性、方法的说明 参考转向，也就是相关主题
@param 对方法的说明对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说明

J2SE5.0中预定义的注释

@Deprecated 过期方法标记，版本更新之后，一些方法过时，标记表示不希望被使用
@Override 这个注释的作用是标识某一个方法是否覆盖了它的父类的方法，不会出去罚站。
@SuppressWarnings (value={“unchecked”,“fallthrough”})压制警告，非无可奈何的情况，应该避免使用，比如List不使用泛型，安卓里Handler错误使用等等

AnnotatedElement概述

这个接口定义了注解的相关使用，Class、Method、Field 等对象都继承自这个接口，该如何使用注解，看 AnnotatedElement 的文档就行了，什么样的对象能用注解，看 AnnotatedElement 子类就知道了。

可用注解的位置

下面这些位置能用注解，就像类一样，一个大类能包含小类，注解也是可以的，大注解包含小注解。

// 声明一个注解
@interface Example {
}

// 注解能在这些位置使用
@Example
public class Test2 {

    @Example
    private String str;

    @Example
    public Test2() {
    }

    @Example
    public void pr(@Example String param) {

    }
}

可用注解的位置，这些位置都有对应的对象，并且都继承自 AnnotatedElement：

Class：类
Constructor：构造器
Field：成员变量
Method：方法
Parameter: 参数
Package：包定义，日常的代码用不上，用了也会报错，这类注解要用在package-info.java中，用途是提供包级的文档说明。

元注解

四个元注解，为什么叫元注解？因为要声明一个注解，需要用到这些注解。

一共四个元注解：@Target,@Retention,@Documented,@Inherited。

@Target

表示该注解用于什么地方，包括：

ElemenetType.CONSTRUCTOR 构造器声明
ElemenetType.FIELD 域声明（包括 enum 实例）
ElemenetType.LOCAL_VARIABLE 局部变量声明
ElemenetType.METHOD 方法声明
ElemenetType.PACKAGE 包声明
ElemenetType.PARAMETER 参数声明
ElemenetType.TYPE 类，接口（包括注解类型）或enum声明

@Retention

像是 @author 注解，用来写代码作者的名字，这个注解对于软件运行没任何意义，因此希望编译之后，把这些内容去掉。
@Retention 用于说明注解的级别：

1. RetentionPolicy.SOURCE 编译之后就会被丢弃。
   例如：POI的@Beta注解，用于说明文档存在一定问题，未来会进行改进

2. RetentionPolicy.CLASS 注解在 class 文件中可用，但会被 VM 丢弃。
   例如：jetbrains的@NotNull，用于说明参数非空，起到规范代码的作用

3. RetentionPolicy.RUNTIME 运行时注解，软件运行过程中依然可以读取内容

@Documented

将此注解包含在 javadoc 中 ，它代表着此注解会被javadoc工具提取成文档，例如： @see, @param 等。

@Inherited

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

实战

import java.lang.annotation.*;
import java.lang.reflect.Method;

@Inherited
@Target({ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@interface Example {

    // 普通字段
    String value() default "";

    // 数组
    String[] arr() default {};
}

public class Test2 {

    // value 字段是特殊的，可以简写，正常情况要写成 value="a"
    @Example("a")
    public void pr(@Example String param) {
    }

    public static void main(String[] args) throws NoSuchMethodException {
        // 获取方法实体
        Method method = Test2.class.getDeclaredMethod("pr", String.class);
        // 获取注解值
        System.out.println(method.getAnnotation(Example.class).value());
    }
}