注解基本概要：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface FieldMap {
    

1. 注解三要素：标识符 @interface + 两个必填项 @Target 和 @Retention
2. @Target 表示注解加在哪个范围
   a. 类或接口TYPE
   b. 属性FIELD
   c. 方法METHOD
   d. 构造方法CONSTRUCTOR
   e. 方法参数PARAMETER
3. @Retention 表示保持在哪个周期，其中大部分是在运行期。不标注 @Retention 默认在仅CLASS。
   a. 编译期SOURCE 如@Override和@SuppressWarnings
   b. 仅CLASS
   c. 运行期RUNTIME
4. @Documented：Javadoc工具会将此注解标记元素的注解信息包含在javadoc中。注解信息默认不会包含在Javadoc中，可以详见另一篇博文「@Documented 的作用」 我基本是推荐加上的。
5. @Target、@Retention、@Repeatable（重复注解）和 @Inherited（注解继承），被称为 元注解（meta annotation），可以修饰其他注解。
6. 注解类的属性中，value属性为通用属性，可以直接常量在括号里，省略 value =""。
7. 配置参数必须是常量，包括所有 基本类型、String、Class以及枚举（包括对应的数组）。

# javadoc 工具示例
javadoc -d /目录 org.xxx.包名 -encoding utf-8 -charset utf-8

什么是重复注解

允许在同一声明类型（类，属性，或方法）上多次使用同一个注解。这个注解在 jdk 1.8 中加入。

例如（自定义注解）：

@FieldMap(channel = "classroom1", value = "name")
@FieldMap(channel = "classroom2", value = "peopleName")
private String studentName;

这样可以在获取 两条注解 后，根据channel去判断该取哪个值；

步骤

1. 先建立一个普通注解类 FieldMap.class。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FieldMap {
    
    String channel() default "";
    String value(); // 如果不写default默认值，则该选项为必填项
}

2. 加入一行 @Repeatable(FieldMaps.class)。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(FieldMaps.class)
@Documented
public @interface FieldMap {
    
    String channel();
    String value();
}

3. 新建对应包裹类 FieldMaps，@Target 和 @Retention要和被包裹的注解相同。同时，属性为被包裹的注解数组 FieldMap[]。因为只含有一个数组属性，所以属性值就选默认的value()，并且不加默认值。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FieldMaps {
    
    FieldMap[] value();
}

使用

1. getAnnotation() 和 getAnnotationsByType()，一个获取单个注解，一个获取相同类型的注解数组。
2. 在判断属性是否含有该注解时，虽然用的是 @FieldMap 注解，但其实编译后是被 @FieldMaps 包裹。

• 普通的注解使用：

if (field.isAnnotationPresent(FieldMap.class)) {
    
	FieldMap annotation =  field.getAnnotation(FieldMap.class);
    String value = annotation.value();
}

• 重复注解使用：

if (field.isAnnotationPresent(FieldMaps.class)) {
     // 此处取得是 FieldMaps
    FieldMap[] annotationsByType = field.getAnnotationsByType(FieldMap.class);  // 此处用的是 getAnnotationsByType() 方法，返回的数组
    for (FieldMap annotation : annotationsByType) {
    
        if ("classroom1".equals(annotation.channel())) {
     // 通过annotation.channel() 获取到第一个进行判断
            String value = annotation.value();
            break;   // 为了防止有属性值相同的情况，直接中止循环
        }
    }
}

总结

1. 注解在 jdk 1.5 加入，其实原本有重复注解，需要用包装类当容器来存多个注解。所以 jdk 1.8 引入的 重复注解:@Repeatable，其实是语法糖。

/**
 * jdk 1.5
 */
@FieldMaps({
    @FieldMap("name"), @FieldMap("peopleName")})
private String studentName;

/**
 * jdk 1.8
 */
@FieldMap("name")
@FieldMap("peopleName")
private String studentName;

2. 注释类FieldMap 被 @Repeatable(FieldMaps.class) 注释着，而 FieldMaps 其实是一个容器，它持有 FieldMap, 只不过编译器选择了隐藏它的存在。所以 studentName 属性就可以被 FieldMap 注释两次。

3. 反射 API 提供一个新方法：getAnnotationsByType() 来返回重复注释的类型。

4. Filterable.class.getAnnotation(FieldMaps.class) 会返回编译器注入的 FieldMaps 实例。