你不知道的 Java 注解那些事!

戳上方蓝字 “程序猿杂货铺” 关注我 并 置顶星标

你的关注意义重大!

原文 | http://1t.click/JpS

注解对于开发人员来讲既熟悉又陌生,熟悉是因为只要你是做开发,都会用到注解(常见的 @Override),陌生是因为即使不使用注解也照常能够进行开发,注解不是必须的,但了解注解有助于我们深入理解某些第三方框架(比如 Android Support Annotations、JUnit、xUtils、ActiveAndroid 等),提高工作效率。

Java 注解又称为标注,是 Java 从 1.5 开始支持加入源码的特殊语法元数据:Java中的类、方法、变量、参数、包都可以被注解。这里提到的元数据是描述数据的数据,结合实例来说明:

<string name="app_name">AnnotionDemo</string>

这里的 "app_name" 就是描述数据 "AnnotionDemo" 的数据,这是在配置文件中写的,注解是在源码中写的,如下所示:

@Override
protected void onCreate(Bundle savedInstanceState){
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main_layout);
    new Thread(new Runnable(){
        @Override
        public void run(){
            setTextInOtherThread();
        }
    }).start();
}

在上面的代码中,在 MainActivity.java 中复写了父类 Activity.java 的 onCreate 方法,使用到了 @Override 注解。但即使不加上 @Override 注解标记代码,程序也能够正常运行。那这里的 @Override 注解有什么用呢?使用它有什么好处?事实上,@Override 是告诉编译器这个方法是一个重写方法,如果父类中不存在该方法,编译器会报错,提示该方法不是父类中的方法。如果不小心拼写错误,将 onCreate 写成了 onCreat,而且没有使用@Override 注解,程序依然能够编译通过,但运行结果和期望的大不相同。从示例可以看出,注解有助于阅读代码

使用注解很简单,根据注解类的 @Target 所修饰的对象范围,可以在类、方法、变量、参数、包中使用 “@+注解类名 + [属性值]” 的方式使用注解。比如:

@UiThread
private void setTextInOtherThread(@StringRes int resId){
    TextView threadTxtView = (TextView)MainActivity.this.findViewById(R.id.threadTxtViewId);
    threadTxtView.setText(resId);
}

特别说明:

  • 注解仅仅是元数据,和业务逻辑无关,所以当你查看注解类时,发现里面没有任何逻辑处理;
  • javadoc 中的 @author、@version、@param、@return、@deprecated、@hide、@throws、@exception、@see 是标记,并不是注解;

注解的作用

  • 格式检查:告诉编译器信息,比如被 @Override 标记的方法如果不是父类的某个方法,IDE 会报错;
  • 减少配置:运行时动态处理,得到注解信息,实现代替配置文件的功能;
  • 减少重复工作:比如第三方框架 xUtils,通过注解 @ViewInject 减少对 findViewById 的调用,类似的还有(JUnit、ActiveAndroid 等);

注解是如何工作的?

注解仅仅是元数据,和业务逻辑无关,所以当你查看注解类时,发现里面没有任何逻辑处理,eg:

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

    int value();

    /* parent view id */
    int parentId() default 0;
}

如果注解不包含业务逻辑处理,必然有人来实现这些逻辑。注解的逻辑实现是元数据的用户来处理的,注解仅仅提供它定义的属性(类/方法/变量/参数/包)的信息,注解的用户来读取这些信息并实现必要的逻辑。当使用java中的注解时(比如 @Override、@Deprecated、@SuppressWarnings)JVM 就是用户,它在字节码层面工作。如果是自定义的注解,比如第三方框架ActiveAndroid,它的用户是每个使用注解的类,所有使用注解的类都需要继承 Model.java,在 Model.java 的构造方法中通过反射来获取注解类中的每个属性:

public TableInfo(Class<? extends Model> type) {
    mType = type;

    final Table tableAnnotation = type.getAnnotation(Table.class);

    if (tableAnnotation != null) {
        mTableName = tableAnnotation.name();
        mIdName = tableAnnotation.id();
    }
    else {
        mTableName = type.getSimpleName();
    }

    // Manually add the id column since it is not declared like the other columns.
    Field idField = getIdField(type);
    mColumnNames.put(idField, mIdName);

    List<Field> fields = new LinkedList<Field>(ReflectionUtils.getDeclaredColumnFields(type));
    Collections.reverse(fields);

    for (Field field : fields) {
        if (field.isAnnotationPresent(Column.class)) {
            final Column columnAnnotation = field.getAnnotation(Column.class);
            String columnName = columnAnnotation.name();
            if (TextUtils.isEmpty(columnName)) {
                columnName = field.getName();
            }

            mColumnNames.put(field, columnName);
        }
    }

}

注解和配置文件的区别

通过上面的描述可以发现,其实注解干的很多事情,通过配置文件也可以干,比如为类设置配置属性;但注解和配置文件是有很多区别的,在实际编程过程中,注解和配置文件配合使用在工作效率、低耦合、可拓展性方面才会达到权衡。

配置文件:

使用场合:

  • 外部依赖的配置,比如 build.gradle 中的依赖配置;
  • 同一项目团队内部达成一致的时候;
  • 非代码类的资源文件(比如图片、布局、数据、签名文件等);

优点:

  • 降低耦合,配置集中,容易扩展,比如 Android 应用多语言支持;
  • 对象之间的关系一目了然,比如 strings.xml;
  • xml 配置文件比注解功能齐全,支持的类型更多,比如 drawable、style等;

缺点:

  • 繁琐;
  • 类型不安全,比如 R.java 中的都是资源 ID,用 TextView 的 setText 方法时传入 int 值时无法检测出该值是否为资源 ID,但 @StringRes 可以;

注解:

使用场合:

  • 动态配置信息;
  • 代为实现程序逻辑(比如 xUtils 中的 @ViewInject 代为实现 findViewById);
  • 代码格式检查,比如 Override、Deprecated、NonNull、StringRes 等,便于 IDE 能够检查出代码错误;

优点:

  • 在 class 文件中,提高程序的内聚性;
  • 减少重复工作,提高开发效率,比如 findViewById。

缺点:

  • 如果对 annotation 进行修改,需要重新编译整个工程;
  • 业务类之间的关系不如 XML 配置那样一目了然;
  • 程序中过多的 annotation,对于代码的简洁度有一定影响;
  • 扩展性较差;

自定义注解

通过阅读注解类的源码可以发现,任何一个注解类都有如下特征:

  • 注解类会被 @interface 标记;
  • 注解类的顶部会被 @Documented、@Retention、@Target、@Inherited 这四个注解标记(@Documented、@Inherited可选,@Retention、@Target必须要有);

@UiThread 源码:

@Documented
@Retention(CLASS)
@Target({METHOD,CONSTRUCTOR,TYPE})
public @interface UiThread {
}

元注解

上文提到的四个注解:@Documented、@Retention、@Target、@Inherited就是元注解,它们的作用是负责注解其它注解,主要是描述注解的一些属性,任何注解都离不开元注解(包括元注解自身,通过元注解可以自定义注解),元注解的用户是 JDK,JDK 已经帮助我们实现了这四个注解的逻辑。这四个注解在 JDK 的java.lang.annotation 包中。对每个元注解的详细说明如下:

@Target

作用:用于描述注解的使用范围,即被描述的注解可以用在什么地方;

取值:

1、CONSTRUCTOR:构造器;

2、FIELD:实例;

3、LOCAL_VARIABLE:局部变量;

4、METHOD:方法;

5、PACKAGE:包;

6、PARAMETER:参数;

7、TYPE:类、接口(包括注解类型) 或enum声明。

示例:

/***
 *
 * 实体注解接口
 */
@Target(value = {ElementType.TYPE})
@Retention(value = RetentionPolicy.RUNTIME)
public @interface Entity {
    /***
     * 实体默认firstLevelCache属性为false
     * @return boolean
     */
    boolean firstLevelCache() default false;
    /***
     * 实体默认secondLevelCache属性为false
     * @return boolean
     */
    boolean secondLevelCache() default true;
    /***
     * 表名默认为空
     * @return String
     */
    String tableName() default "";
    /***
     * 默认以""分割注解
     */
    String split() default "";
}

@Retention

作用:表示需要在什么级别保存该注解信息,用于描述注解的生命周期,即被描述的注解在什么范围内有效;

取值:

1、SOURCE:在源文件中有效,即源文件保留;

2、CLASS:在class文件中有效,即class保留;

3、RUNTIME:在运行时有效,即运行时保留;

示例:

/***
 * 字段注解接口
 */
@Target(value = {ElementType.FIELD})//注解可以被添加在实例上
@Retention(value = RetentionPolicy.RUNTIME)//注解保存在JVM运行时刻,能够在运行时刻通过反射API来获取到注解的信息
public @interface Column {
    String name();//注解的name属性
}

@Documented

作用:用于描述其它类型的 annotation 应该被作为被标注的程序成员的公共 API,因此可以被例如 javadoc 此类的工具文档化。

取值:它属于标记注解,没有成员;

示例:

@Documented
@Retention(CLASS)
@Target({METHOD,CONSTRUCTOR,TYPE})
public @interface UiThread {
}

@Inherited

作用:用于描述某个被标注的类型是可被继承的。如果一个使用了 @Inherited 修饰的 annotation 类型被用于一个 class,则这个 annotation 将被用于该class的子类。

取值:它属于标记注解,没有成员;

示例:

/**
 * @author wangsheng
 **/  
@Inherited  
public @interface Greeting {  
    public enum FontColor{ BULE,RED,GREEN};  
    String name();  
    FontColor fontColor() default FontColor.GREEN;  
}

如何自定义注解

使用 @interface 自定义注解时,自动继承了 java.lang.annotation.Annotation 接口,由编译程序自动完成其他细节。在定义注解时,不能继承其他的注解或接口。@interface 用来声明一个注解,其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称,返回值类型就是参数的类型(返回值类型只能是基本类型、Class、String、enum)。可以通过 default 来声明参数的默认值。

自定义注解格式

元注解
    public @interface 注解名{
        定义体;
    }

注解参数可支持的数据类型

1、所有基本数据类型(int,float,boolean,byte,double,char,long,short);

2、String 类型;

3、Class 类型;

4、enum 类型;

5、Annotation 类型;

6、以上所有类型的数组。

特别说明:

1、注解类中的方法只能用 public 或者默认这两个访问权修饰,不写 public 就是默认,eg:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {
    public enum Color{ BULE,RED,GREEN};
    Color fruitColor() default Color.GREEN;
}

2、如果注解类中只有一个成员,最好把方法名设置为"value",比如:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}

3、注解元素必须有确定的值,要么在定义注解的默认值中指定,要么在使用注解时指定,非基本类型的注解元素的值不可为 null。因此, 使用空字符串或0作为默认值是一种常用的做法。

实例演示

ToDo.java:注解类

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@interface Todo {
    public enum Priority {LOW, MEDIUM, HIGH}
    public enum Status {STARTED, NOT_STARTED}    
    String author() default "Yash";
    Priority priority() default Priority.LOW;
    Status status() default Status.NOT_STARTED;
}

BusinessLogic:使用注解的类

public class BusinessLogic {
    public BusinessLogic() {
        super();
    }

    public void compltedMethod() {
        System.out.println("This method is complete");
    }    

    @Todo(priority = Todo.Priority.HIGH)
    public void notYetStartedMethod() {
        // No Code Written yet
    }

    @Todo(priority = Todo.Priority.MEDIUM, author = "Uday", status = Todo.Status.STARTED)
    public void incompleteMethod1() {
        //Some business logic is written
        //But its not complete yet
    }

    @Todo(priority = Todo.Priority.LOW, status = Todo.Status.STARTED )
    public void incompleteMethod2() {
        //Some business logic is written
        //But its not complete yet
    }
}

TodoReport.java:解析注解信息

public class TodoReport {
    public TodoReport() {
        super();
    }

    public static void main(String[] args) {
        getTodoReportForBusinessLogic();
    }

    /**
     * 解析使用注解的类,获取通过注解设置的属性
     */
    private static void getTodoReportForBusinessLogic() {
        Class businessLogicClass = BusinessLogic.class;
        for(Method method : businessLogicClass.getMethods()) {
            Todo todoAnnotation = (Todo)method.getAnnotation(Todo.class);
            if(todoAnnotation != null) {
                System.out.println(" Method Name : " + method.getName());
                System.out.println(" Author : " + todoAnnotation.author());
                System.out.println(" Priority : " + todoAnnotation.priority());
                System.out.println(" Status : " + todoAnnotation.status());
                System.out.println(" --------------------------- ");
            }
        }
    }
}

执行结果如下图所示:

推荐阅读

原文发布于微信公众号 - 程序猿杂货铺(zhoudl_l)

原文发表时间:2019-08-19

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券