本文主要参考与借鉴 frank909 文章, 但更为简单, 详细.
Annotation 中文译过来就是注解, 标释的意思. Annotation 是一种应用于类, 方法, 参数, 变量, 构造器及包声明中的特殊修饰符. 它是一种由 JSR-175 标准选择用来描述元数据的一种工具. 在 Java 中注解是一个很重要的知识点, 注解目前非常的流行, 很多主流框架都支持注解, 而且自己编写代码的时候也会尽量的去用注解, 一是方便, 二是代码更加简洁.
注解语法
因为平常开发少见, 相信有不少的人员会认为注解的地位不高. 其实同 classs 和 interface 一样, 注解也属于一种类型. 它是在 Java SE 5.0 版本中开始引入的概念.
- package java.lang;
- import java.lang.annotation.*;
- /**
- * Indicates that a method declaration is intended to override a
- * method declaration in a supertype. If a method is annotated with
- * this annotation type compilers are required to generate an error
- * message unless at least one of the following conditions hold:
- *
- * <ul><li>
- * The method does override or implement a method declared in a
- * supertype.
- * </li><li>
- * The method has a signature that is override-equivalent to that of
- * any public method declared in {@linkplain Object}.
- * </li></ul>
- */
- @Target(ElementType.METHOD)
- @Retention(RetentionPolicy.SOURCE)
- public @interface Override {
- }
它的形式跟接口很类似, 不过前面多了一个 @ 符号. 上面的代码就创建了一个名字为 Override 的注解.
你可以简单理解为创建了一张名字为 Override 的标签.
**Annotations 仅仅是元数据, 和业务逻辑无关.** 理解起来有点困难, 但就是这样. 如果 Annotations 不包含业务逻辑, 那么必须有人来实现这些逻辑. 元数据的用户来做这个事情. Annotations 仅仅提供它定义的属性 (类 / 方法 / 包 / 域) 的信息. Annotations 的用户 (同样是一些代码) 来读取这些信息并实现必要的逻辑.
元注解
元注解是什么意思呢?
元注解是可以注解到注解上的注解, 或者说元注解是一种基本注解, 但是它能够应用到其它的注解上面.
如果难于理解的话, 你可以这样理解. 元注解也是一张标签, 但是它是一张特殊的标签, 它的作用和目的就是给其他普通的标签进行解释说明的.
元标签有 @Retention,@Documented,@Target(当一个注解被 @Target 注解时, 这个注解就被限定了运用的场景 ),@Inherited,@Repeatable 5 种.
@target | 表示该注解可以用于什么地方,可能的 ElementType 参数有: CONSTRUCTOR:构造器的声明 FIELD:域声明(包括 enum 实例) LOCAL_VARIABLE:局部变量声明 METHOD:方法声明 PACKAGE:包声明 PARAMETER:参数声明 TYPE:类、接口(包括注解类型)或 enum 声明 |
---|---|
@Retention | 表示需要在什么级别保存该注解信息。可选的 RetentionPolicy 参数包括: SOURCE:注解将被编译器丢弃; CLASS:注解在 class 文件中可用,但会被 VM 丢弃; RUNTIME:VM 将在运行期间保留注解,因此可以通过反射机制读取注解的信息。 |
@Document | 将注解包含在 Javadoc 中 |
@Inherited | 允许子类继承父类中的注解 |
@Repeatable | 可重复 (@Repeatable 是 Java 1.8) |
注解的属性
注解的属性也叫做成员变量. 注解只有成员变量, 没有方法. 注解的成员变量在注解的定义中以 "无形参的方法" 形式来声明, 其方法名定义了该成员变量的名字, 其返回值定义了该成员变量的类型. 需要注意的是, 在注解中定义属性时它的类型必须是 8 种基本数据类型外加 类, 接口, 注解及它们的数组.
注解中属性可以有默认值, 默认值需要用 default 关键值指定.
- @Target(ElementType.TYPE)
- @Retention(RetentionPolicy.RUNTIME)
- public @interface Person {
- int id() default -10998;
- String msg() default "no hello";
- }
上面代码定义了 Person 这个注解中拥有 id 和 msg 两个属性. 在使用的时候, 我们应该给它们进行赋值. 赋值的方式是在注解的括号内以 value="" 形式, 多个属性之前用 , 隔开. 一个注解内仅仅只有一个名字为 value 的属性时, 这个注解时可以直接接属性值填写到括号内. 还需要注意的一种情况是一个注解没有任何属性 括号可以省略..
- public @interface NoUse {
- }
- public @interface Chou {
- String value() default "You";
- }
- @Person(id = 10758, msg = "hello android")// 或者直接默认 @Person()
- public class Liming {
- @Chou("She")
- String beautiful;
- @NoUse
- public void say() {
- }
- }
Java 预置的注解
Java 语言本身已经提供了几个现成的注解.
@Deprecated
这个元素是用来标记过时的元素, 想必大家在日常开发中经常碰到. 编译器在编译阶段遇到这个注解时会发出提醒警告, 告诉开发者正在调用一个过时的元素比如过时的方法, 过时的类, 过时的成员变量.
- @Person(id = 10758, msg = "hello android")// 或者直接默认 @Person()
- public class Liming {
- @Chou("She")
- String beautiful;
- @NoUse
- public void say() {
- System.out.println("say is using");
- }
- @Deprecated
- public void speak() {
- System.out.println("speak is out of date");
- }
- }
Liming 类, 它有两个方法 say() 和 speak() , 其中 speak() 被 @Deprecated 注解. 然后我们在 IDE 中分别调用它们.
可以看到, speak() 方法上面被一条直线划了一条, 这其实就是编译器识别后的提醒效果.
@SuppressWarnings
阻止警告. 调用被 @Deprecated 注解的方法后, 编译器会警告提醒, 而有时候开发者会忽略这种警告, 他们可以在调用的地方通过 @SuppressWarnings 达到目的.
@SafeVarargs
参数安全类型注解. 它的目的是提醒开发者不要用参数做一些不安全的操作, 它的存在会阻止编译器产生 unchecked 这样的警告, 在 Java 1.7 的版本中加入.
上面的代码中, 编译阶段不会报错, 运行时会抛出 ClassCastException 这个异常.
@FunctionalInterface
函数式接口注解, 这个是 Java 1.8 版本引入的新特性.
函数式接口 (Functional Interface) 就是一个具有一个方法的普通接口.
- @FunctionalInterface
- public interface Runnable {
- /**
- * When an object implementing interface <code>Runnable</code> is used
- * to create a thread, starting the thread causes the object's
- * <code>run</code> method to be called in that separately executing
- * thread.
- * <p>
- * The general contract of the method <code>run</code> is that it may
- * take any action whatsoever.
- *
- * @see java.lang.Thread#run()
- */
- public abstract void run();
- }
我们进行线程开发中常用的 Runnable 就是一个典型的函数式接口, 上面源码可以看到它就被 @FunctionalInterface 注解.
可能有人会疑惑, 函数式接口标记, 函数式接口可以很容易转换为 Lambda 表达式.
注解与反射
注解通过反射获取. 首先可以通过 Class 对象的 isAnnotationPresent() 方法判断它是否应用了某个注解
public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass) {}
然后通过 getAnnotation() 方法来获取 Annotation 对象.
public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {}
或者是 getAnnotations() 方法.
public Annotation[] getAnnotations() {}
前一种方法返回指定类型的注解, 后一种方法返回注解到这个元素上的所有注解.
如果获取到的 Annotation 如果不为 null, 则就可以调用它们的属性方法了.
属性, 方法上的注解照样是可以的. 同样还是要借助于反射.
- public static void getAnnotation() {
- boolean hasAnnotation = MainActivity.class.isAnnotationPresent(Person.class);
- if (hasAnnotation) {
- Person testPerson = MainActivity.class.getAnnotation(Person.class);
- System.out.println("id is" + testPerson.id() + "msg is" + testPerson.msg());
- }
- }
- public static void getField() {
- try {
- Field a = Liming.class.getDeclaredField("beautiful");
- a.setAccessible(true);
- Chou chou = a.getAnnotation(Chou.class);
- if (chou != null) {
- System.out.println("check value:" + chou.value());
- }
- Method noUse = Liming.class.getDeclaredMethod("say");
- if (noUse != null) { // 获取方法中的注解
- Annotation[] ans = noUse.getAnnotations();
- for (int i = 0; i <ans.length; i++) {
- System.out.println("method noUse annotation:" + ans[i].annotationType().getSimpleName());
- }
- }
- } catch (NoSuchFieldException e) {
- e.printStackTrace();
- System.out.println("NoSuchFieldException");
- } catch (NoSuchMethodException e) {
- e.printStackTrace();
- System.out.println("NoSuchMethodException");
- }
- }
- say is using
- speak is out of date
- id is -10998 msg is this is not default
- check value:She
- method noUse annotation:NoUse
- Process finished with exit code 0
当开发者使用了 Annotation 修饰了类, 方法, Field 等成员之后, 这些 Annotation 不会自己生效, 必须由开发者提供相应的代码来提取并处理 Annotation 信息. 这些处理提取和处理 Annotation 的代码统称为 APT(Annotation Processing Tool).
注解是一系列元数据, 它提供数据用来解释程序代码, 但是注解并非是所解释的代码本身的一部分. 注解对于代码的运行效果没有直接影响.
注解有许多用处, 主要如下:
- 提供信息给编译器: 编译器可以利用注解来探测错误和警告信息
- 编译阶段时的处理: 软件工具可以用来利用注解信息来生成代码, html 文档或者做其它相应处理.
- 运行时的处理: 某些注解可以在程序运行的时候接受代码的提取
亲手自定义注解完成某个目的
需求: 自定义注解与实现, 检查 MaSaGei 类中的错误并反馈
- @Retention(RetentionPolicy.RUNTIME)
- public @interface CheckOut {
- }
- public class MaSaGei {
- @CheckOut
- public void testOne() {
- System.out.println("1 + 0 =" + ((1 + 1) / 2));
- }
- @CheckOut
- public void testTwo() {
- System.out.println("1 + 1 =" + (8 / 4));
- }
- @CheckOut
- public void testThree() {
- System.out.println("1 + 2 =" + (6 / 2));
- }
- @CheckOut
- public void testFour() {
- System.out.println("1 / 3 =" + (6 / 0));
- }
- }
- public class CheckOutTool {
- public static void checkAll() {
- MaSaGei maSaGei = new MaSaGei();
- Class clazz = maSaGei.getClass();
- Method[] method = clazz.getDeclaredMethods();
- StringBuilder log = new StringBuilder();
- // 记录异常的次数
- int errornum = 0;
- for (Method m : method) {
- if (m.isAnnotationPresent(CheckOut.class)) {
- m.setAccessible(true);
- try {
- m.invoke(maSaGei, null);
- } catch (IllegalAccessException e) {
- e.printStackTrace();
- } catch (InvocationTargetException e) {
- e.printStackTrace();
- errornum++;
- log.append(m.getName());
- log.append(" ");
- log.append("has error");
- log.append("\\n\\r caused by");
- log.append(e.getCause().getClass().getSimpleName());
- log.append("\n\r");
- log.append(e.getCause().getMessage());
- log.append("\n\r");
- }
- }
- }
- log.append(clazz.getSimpleName());
- log.append("has");
- log.append(errornum);
- log.append("error."); // 生成测试报告
- System.out.println(log.toString());
- }
- }
结果如下:
- testFour has error \n\r caused by ArithmeticException
- at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
- at java.lang.reflect.Method.invoke(Method.java:498)
- at com.heng.subhey.annotation.CheckOutTool.checkAll(CheckOutTool.java:18)
- at com.heng.subhey.MainActivity.main(MainActivity.java:22)
- Caused by: java.lang.ArithmeticException: / by zero
- / by zero
- at com.heng.subhey.annotation.MaSaGei.testFour(MaSaGei.java:21)
- ... 6 more
- MaSaGei has 1 error.
- Process finished with exit code 0
注解应用实例
- JUnit
- /**
- * Example local unit test, which will execute on the development machine (host).
- *
- * @see <a href="http://d.android.com/tools/testing">Testing documentation</a>
- */
- public class ExampleUnitTest {
- @Test
- public void addition_isCorrect() throws Exception {
- assertEquals(4, 2 + 2);
- }
- }
@Test 标记了要进行测试的方法 addition_isCorrect().
ButterKnife
ButterKnife 是 Android 开发中大名鼎鼎的 IoC 框架, 它减少了大量重复的代码.
- public class GoPayActivity extends BaseActivity {
- @BindView(R.id.title_tv)
- TextView title_tv;
- @Override
- protected void onCreate(Bundle savedInstanceState) {
- super.onCreate(savedInstanceState);
- title_tv.setText("支付");
- }
- @Override
- protected int getLayoutId() {
- return R.layout.activity_go_pay;
- }
- @OnClick({R.id.title_back, R.id.pay_confirm})
- public void onClick(View v) {
- switch (v.getId()) {
- case R.id.title_back:
- finish();
- break;
- case R.id.pay_confirm:
- ToastUtils.showLong("支付环境安全检测中...");
- title_tv.postDelayed(new Runnable() {
- @Override
- public void run() {
- ToastUtils.showShort("即将跳转至支付页面");
- Intent charge = new Intent(GoPayActivity.this, KeyWriteActivity.class);
- startActivity(charge);
- }
- }, 2 * 1000);
- break;
- }
- }
- }
Retrofit
Http 网络访问框架
- public interface GitHubService {
- @GET("users/{user}/repos")
- Call<List<Repo>> listRepos(@Path("user") String user);
- }
- Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .build(); GitHubService service = retrofit.create(GitHubService.class);
总结
注解难于理解, 注解为了解释代码.
注解的基本语法, 多了个 @ 符号.
注解的元注解.
注解的属性.
注解主要给编译器及工具类型的软件用的.
注解的提取需要借助于 Java 的反射技术, 反射比较慢, 所以注解使用时也需要谨慎计较时间成本.
来源: https://juejin.im/post/5c0783c56fb9a049fa0f8b58