Java-注释详解

   无论是做Java后台或者Android开发，我们经常使用注解，最常用的莫过于@Override，很多流程的框架都用到了注解这个功能机制，例如Java后台开发中常用的框架Spring、MyBatis等，Android的Retrofit，Butterknife等，都是注解框架。有关注解也常常在面试中被问到，但我们了解注解的本质是什么？有哪些类别？如何自定义及使用？其中工作原理是什么？本文将做全面介绍。

一、注解的定义

关于注解首先引入官方文档的一句话：Java 注解(Annotation)用于为 Java 代码提供元数据。作为元数据，注解不直接影响你的代码执行，但也有一些类型的注解实际上可以用于这一目的。Java 注解是从 Java5 开始添加到 Java 的。

日常开发中新建Java类，我们使用class、interface比较多，而注解和它们一样，也是一种类的类型，用的修饰符为 @interface

作用：标识 / 解释 Java 代码。

二、注解类型

1、元注解

元注解顾名思义我们可以理解为注解的注解，它是作用在注解中，方便我们使用注解实现想要的功能。元注解分别有@Retention、 @Target、 @Document、 @Inherited和@Repeatable（JDK1.8加入）五种。

@Retention 

@Retention(RetentionPolicy.RUNTIME)//使用该注解，只能选择其中一种属性，不能定义多个
public @interface MyAnnotation {
}

Retention英文意思有保留、保持的意思，它表示注解存在阶段是保留在源码（编译期），字节码（类加载）或者运行期（JVM中运行）。
在@Retention注解中使用枚举RetentionPolicy来表示注解保留时期
Retention策略 ：

@Retention(RetentionPolicy.SOURCE) ，注解仅存在于源码中，在class字节码文件中不包含
@Retention(RetentionPolicy.CLASS)， 默认的保留策略，注解会在class字节码文件中存在，但运行时无法获得
@Retention(RetentionPolicy.RUNTIME)， 注解会在class字节码文件中存在，在运行时可以通过反射获取到

@Target

@Target({ElementType.FIELD,ElementType.METHOD}) //多个的时候使用{}括起来，然后用逗号分隔开
public @interface MyAnnotation {
}

Target的英文意思是目标，这也很容易理解，使用@Target元注解表示我们的注解作用的范围就比较具体了，可以是类，方法，方法参数变量等，同样也是通过枚举类ElementType表达作用类型.

@Target(ElementType.TYPE) 作用接口、类、枚举、注解
@Target(ElementType.FIELD) 作用属性字段、枚举的常量
@Target(ElementType.METHOD) 作用方法
@Target(ElementType.PARAMETER) 作用方法参数
@Target(ElementType.CONSTRUCTOR) 作用构造函数
@Target(ElementType.LOCAL_VARIABLE)作用局部变量
@Target(ElementType.ANNOTATION_TYPE)作用于注解（@Retention注解中就使用该属性）
@Target(ElementType.PACKAGE) 作用于包
@Target(ElementType.TYPE_PARAMETER) 作用于类型泛型，即泛型方法、泛型类、泛型接口 （jdk1.8加入）
@Target(ElementType.TYPE_USE) 类型使用.可以用于标注任意类型除了 class （jdk1.8加入）
一般比较常用的是ElementType.TYPE类型.

@Documented

@Documented //添加文档注解
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation {
}

Document的英文意思是文档。它的作用是能够将注解中的元素包含到 Javadoc 中去。

@Inherited

@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface MyAnnotation {
}

Inherited的英文意思是继承，但是这个继承和我们平时理解的继承大同小异，一个被@Inherited注解了的注解修饰了一个父类，则它的子类也继承了父类的注解（子类可以同时被其他注解修饰）。

@MyAnnotation
public class FatherClass {
} 
public class SonClass extends FatherClass {
}
public class test {
   public static void main(String[] args){
      Class sonClass = SonClass.class;
      MyAnnotation annotation =sonClass.getAnnotation(MyAnnotation.class);
   }
}

上面的例子，父类加了可继承注解，子类没有被该注解修饰，但是子类获取Mynnotation注解成功，说明子类继承了父类中的MyAnnotation。

@Repeatable

Repeatable的英文意思是可重复的。顾名思义说明被这个元注解修饰的注解可以同时作用一个对象多次，但是每次作用注解又可以代表不同的含义。

Java 1.8后引进，使得作用的注解可以取多个值
下面通过例子说明其定义。

// 1. 定义 容器注解 @RoleContainer
//    容器注解本身也是一个注解，用于存放其他注解
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public   @interface RoleContainer {
    Role[] value();
} 
// 2. 定义@Role 
//   使用@Repeatable 注解 @Role
//   注：@Repeatable 括号中的类 = 容器注解
@Repeatable(RoleContainer.class)
@Retention(RetentionPolicy.RUNTIME)
public  @interface Role {
    String role() default "";
} 
// 3. 在使用@Role（被@Repeatable 注解 ）时，可以取多个值来解释Java代码
// 下面注解表示：Man有多个身份
@Role(role = "CEO")
@Role(role = "Father")
@Role(role = "husband")
@Role(role = "son")
public class Man {
}

2、Java内置注解

定义：即Java内部已经实现好的注解

Java中 内置的注解有5类，具体包括：

@Deprecated：过时注解，用于标记已过时 & 被抛弃的元素（类、方法等）

@Override：复写注解，用于标记该方法需要被子类复写

@SuppressWarnings：阻止警告注解，用于标记的元素会阻止编译器发出警告提醒

@SafeVarargs：参数安全类型注解，用于提醒开发者不要用参数做不安全的操作 & 阻止编译器产生 unchecked警告，Java 1.7 后引入

// 以下是官方例子
// 虽然编译阶段不报错，但运行时会抛出 ClassCastException 异常
// 所以该注解只是作提示作用，但是实际上还是要开发者自己处理问题
@SafeVarargs // Not actually safe!
    static void m(List... stringLists) {
    Object[] array = stringLists;
    List tmpList = Arrays.asList(42);
    array[0] = tmpList; // Semantically invalid, but compiles without warnings
    String s = stringLists[0].get(0); // Oh no, ClassCastException at runtime!
}

@FunctionalInterface：函数式接口注解,数式接口 (Functional Interface) = 1个具有1个方法的普通接口，Java 1.8 后引入的新特性

// 多线程开发中常用的 Runnable 就是一个典型的函数式接口（被 @FunctionalInterface 注解）
@FunctionalInterface
public interface Runnable {
    public abstract void run();
}

3、自定义注解

定义：开发者自定义注解
下一节介绍如何自定义注解，及学习注解属性和如何获取注解的属性。

三、注解的使用

1、定义注解

定义注解形式类似接口，只是在interface前面加@：

public  @interface Role {
    String role() default "";
}

2、注解属性

注解的本质就是一个Annotion接口。

/**Annotation接口源码*/
public interface Annotation {
 
    boolean equals(Object obj);
 
    int hashCode();
 
    Class annotationType();
}

通过以上源码，我们知道注解本身就是Annotation接口的子接口，也就是说注解中其实是可以有属性和方法，但是接口中的属性都是static final的，对于注解来说没什么意义，而我们定义接口的方法就相当于注解的属性，也就说为什么注解只有属性成员变量，其实他就是接口的方法，这就是为什么成员变量会有括号，不同于接口我们可以在注解的括号中给成员变量赋值。

public  @interface Role {
    //注解的属性，注解只有属性，没有方法，方法名=属性名，方法返回值 = 属性类型
    String role() default "";
    
    int id();
}

//注解括号内以 属性名=xx 形式赋值, 用,隔开多个属性

Role(role="father" ,id =1)

//若注解只有一个属性，则赋值时”value“可以省略
 

Role("father")

注解属性类型可以有以下列出的类型：

基本数据类型
String
枚举类型
注解类型
Class类型
以上类型的一维数组类型

3、使用注解

在类/成员变量/方法定义前 加上 “@注解名” 就可以使用该注解。

//表示Tony的角色是CEO
@Role(role = "CEO")
public class Tony {
}

4、获取注解

前面介绍Java自带的注解和如何自定义注解，如何使用，接下来学习如何获取注解，这是使用注解的关键，而使用注解的目的是为了获取注解属性值。
如何获取注解？当然是Java的反射技术了。

用于Java反射会带来一定的耗时，因此使用运行注解需要考虑对性能的影响。

获取注解的方法：

 /**是否存在对应 Annotation 对象*/
  public boolean isAnnotationPresent(Class annotationClass) {
        return GenericDeclaration.super.isAnnotationPresent(annotationClass);
    }
 

 /**获取 Annotation 对象*/
    public  A getAnnotation(Class annotationClass) {
        Objects.requireNonNull(annotationClass);
 
        return (A) annotationData().annotations.get(annotationClass);
    }
 /**获取所有 Annotation 对象数组*/   
 public Annotation[] getAnnotations() {
        return AnnotationParser.toArray(annotationData().annotations);
    }  

获取注解及注解属性的示例：

@Retention(RetentionPolicy.RUNTIME)
public  @interface Role {
    String role() default "";
    int id();
}

@Role(role = "CEO", id = 1)
public class Tony {
    @Role(role = "teacher", id = 2)
    public String son;
 
    @Role(role = "doctor", id = 3)
    public String getDaughter() {
        return "daughter is doctor";
    }
}

public class TestAnnotation {
   public static void test() {
       //判断是否被注解修饰
        boolean isRoleAnnotation = Tony.class.isAnnotationPresent(Role.class);
        Log.d(TAG, "tony is decorated by RoleAnnotation:" + isRoleAnnotation);
 
        //获取类注解属性
        Role roleAnnotation = Tony.class.getAnnotation(Role.class);
        if (roleAnnotation != null) {
            Log.d(TAG, "tony role is " + roleAnnotation.role());
        }
 
        //获取方法注解属性
        Class tony = Tony.class;
        try {
            Field field = tony.getField("son");
            roleAnnotation = field.getAnnotation(Role.class);
            if (roleAnnotation != null) {
                Log.d(TAG, "field role is " + roleAnnotation.role());
            }
 
            Method method = tony.getDeclaredMethod("getDaughter");
            roleAnnotation = field.getAnnotation(Role.class);
            if (roleAnnotation != null) {
                Log.d(TAG, "method role is " + roleAnnotation.role());
            }
        } catch (Exception e) {
 
        }
    }
}
//打印结果：
//D/TestAnnotation: tony is decorated by RoleAnnotation:true
//D/TestAnnotation: tony role is CEO
//D/TestAnnotation: field role is teacher
//D/TestAnnotation: method role is teacher

四、注解的应用

按照注解的Retention属性其应用分为3个场景：

1  提供信息给编译器： 编译器可以利用注解来检测出错误或者警告信息，打印出日志。
2  编译阶段时的处理： 软件工具可以用来利用注解信息来自动生成代码、文档或者做其它相应的自动处理。
3 运行时处理： 某些注解可以在程序运行的时候接受代码的提取，自动做相应的操作。

应用举例

应用场景1：测试代码

如出名的测试框架JUnit = 采用注解进行代码测试。

public class ExampleUnitTest {
    @Test
    public void Method() throws Exception {
          ...
    }
}
// @Test 标记了要进行测试的方法Method() 

应用场景2：解耦&简化代码，提高开发效率

Android 开发中大名鼎鼎的 IOC 框架ButterKnife，它减少了大量重复的代码。

public class TestActivity extends AppCompatActivity {
 
    @BindView(R.id.tvTest)
    TextView tvTest;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_test);
 
        ButterKnife.bind(this);
    }
 

很牛逼的 Http 网络访问框架Retrofit，采用注解描述网络请求参数：

public interface UserService {
   @GET("users/all")
   Call> listUsers();
}
 
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://xxx.com/")
    .build();
 
UserService userService = retrofit.create(UserService.class)
Call>> call = userService.listUsers();

 

五、注解的工作原理

编译时处理——APT

编译时处理需要使用到APT技术，该技术提供了一套编译期的注解处理流程。

在编译期扫描.java文件的注解，并传递到注解处理器，注解处理器可根据注解生成新的.java文件，这些新的.java问和原来的.java一起被javac编译。

注解处理器是一个在javac编译期处理注解的工具，你可以创建注解处理器并注册，在编译期你创建的处理器以Java代码作为输入，生成文件.java文件作为输出。注解处理器不能修改已有的Java类，只能生成新的Java类。

运行时处理
通过反射技术处理运行时注解，这里参考一下反射的原理，运行时注解就是通过反射技术获取带有注解修饰的属性、方法。

六、总结

注解在我们开发中很常见，会使用注解是我们必须掌握的技能。本文结合例子全面总结了注解的定义、类型，如何自定义及使用注解，注解的工作原理，及应用场景。巧用注解可以提高开发效率，写出优雅的代码，但也要注意到运行注解会带来性能问题，需要我们深入理解注解的原理，权衡使用。