android方法注释,android 注解的使用

前言

对注解，一开始是在学习java的时候接触到的，就是在《Thinking in Java》里草草看过。后来开发android，自己接了项目时，把

基础概况

注解是Java SE5中的重要特性，也被称为元数据。为我们在代码中添加信息提供一种形式化的方式，使我们可以在稍后某个时刻非常方便地使用这些数据。主要作用：

可以由编译器来测试和验证格式

存储有关程序的额外信息

可以用来生成描述符文件或新的类定义

减少编写样板代码的负担

分类

根据注解中成员个数(0个，1个，多个)把注解分为：标记注解，单值注解，完整注解

也可以根据把注解的来源分为jdk自带的，元注解，和我们自己定义的注解

1. Java SE5中自带了三种标准注解

@Override 表示当前的方法定义将覆盖超类中的方法

@Deprecated 表示废弃的意思，使用了该注解的方法或者对象，则会有提示。

@SuppressWarnings 关闭不当的编译器警告信息

java 8新特性：加入了 @Repeatable注解，允许多次使用同一个注解

@Repeatable(Authorities.class)

public @interface Num{

int value();

}

public class Opera{

@Num(value = 1)

@Num(value = 2)

public void add(){ }

}

2. Java SE5中还有四个元注解，元注解专职负责注解其他注解。在 java.lang.annotation下

元注解

作用

@Target

表示该注解可以用于什么地方，可能在ElementType参数包括

CONSTRUCTOR: 用于描述构造器FIELD: 用于描述域LOCAL_VARIABLE: 用于描述局部变量METHOD: 用于描述方法PACKAGE: 用于描述包PARAMETER: 用于描述参数TYPE: 用于描述类、接口(包括注解类型) 或enum声明

@Retention

表示需要在什么级别保存该注解信息。可选的RetentionPolicy参数包括：

SOURCE: 注解将被编译器丢弃CLASS: 注解在class文件中可用，但会被VM丢弃。RUNTIME: VM将在运行期也保留注解，因此可以通过反射机制读取注解的信息

@Document

将此注解包含在javadoc中

@Inhrited

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

java 8新特性：java 8之前注解只能是在声明的地方所使用，比如类，方法，属性；java 8里面，注解可以应用在任何地方，比如方法参数前面等。

3.自定义注解

先写几个简单的注解：

没有元素的标记注解

@Target(ElementType.METHOD)

@Retention(RetentionPolicy.RUNTIME)

public @interface Test {}

单值注解

@Target(ElementType.TYPE)

@Retention(RetentionPolicy.RUNTIME)

public @interface Num {

int value();

}

完整注解

@Target(ElementType.METHOD)

@Retention(RetentionPolicy.RUNTIME)

public @interface Event {

int[] value();

int[] parentId() default 0;

Class> type() default View.OnClickListener.class;

String setter() default "";

String method() default "";

}

自定义注解格式：

public @interface 注解名{注解体}。注解体中注解元素可以被public修饰，也可以什么也不写，元素类型可以是：

所有基本数据类型(int,float,boolean等)

String类型

Class类型

enum类型

Annotation类型(说明注解可以嵌套)

以上所有类型的数组

默认值的限定:

编译器对默认值过分的挑剔，要么有确定的默认值，要么在使用的时候提供元素的值。

基本类型的元素都有默认值，不用写default也可以，但是想String这类就必须要写，而且不能写null，因此在某些需要分清是null还是空字符串的地方要注意。

4. 注解的使用

@Event(value = R.id.btn_test1, type = View.OnClickListener.class)

private void onTestClick(View view) {

……

}

注解元素使用时变现为键值对的形式，如上的value=R.id.btn_test1，没有赋值的就用默认的值了。

当然为了简便，也可以直接写上值，特别是单值注解

@Num (2)

class Goods {

……

}

5. 注解处理器类库的使用

如果没有用来读取注解的工具，那注解也不会比注释更有用。使用注解的过程中很重要的一个部分就是创建与使用注解处理器。Java SE5扩展了反射机制的API，在java.lang.reflect 包下新增了AnnotatedElement接口，该接口代表程序中可以接受注解的程序元素，以下是源码，不要看到接口里的方法有具体实现感到惊讶(Java 8允许我们给接口添加一个非抽象的方法实现，只需要使用 default关键字即可，这个特征又叫做扩展方法)，原来的注释太长我去掉了，写上简单的汉字注释，java 8比起之前新增了两个方法。

public interface AnnotatedElement {

//该元素是否被注解标记了

default boolean isAnnotationPresent(Class extends Annotation> annotationClass) {

return getAnnotation(annotationClass) != null;

}

//获取该元素指定注解类型的值

T getAnnotation(Class annotationClass);

//获取该元素所有的注解

Annotation[] getAnnotations();

//1.8新增，返回重复注解(@Repeatable)的类型

default T[] getAnnotationsByType(Class annotationClass) {

T[] result = getDeclaredAnnotationsByType(annotationClass);

if (result.length == 0 && // Neither directly nor indirectly present

this instanceof Class && // the element is a class

AnnotationType.getInstance(annotationClass).isInherited()) { // Inheritable

Class> superClass = ((Class>) this).getSuperclass();

if (superClass != null) {

// Determine if the annotation is associated with the

// superclass

result = superClass.getAnnotationsByType(annotationClass);

}

}

return result;

}

//返回直接存在于此元素上的所有注释，不考虑继承下来的

default T getDeclaredAnnotation(Class annotationClass) {

Objects.requireNonNull(annotationClass);

// Loop over all directly-present annotations looking for a matching one

for (Annotation annotation : getDeclaredAnnotations()) {

if (annotationClass.equals(annotation.annotationType())) {

// More robust to do a dynamic cast at runtime instead

// of compile-time only.

return annotationClass.cast(annotation);

}

}

return null;

}

//1.8新增，返回直接或者间接标记在该元素的注解类型，不考虑继承。

default T[] getDeclaredAnnotationsByType(Class annotationClass) {

Objects.requireNonNull(annotationClass);

return AnnotationSupport.

getDirectlyAndIndirectlyPresent(Arrays.stream(getDeclaredAnnotations()).

collect(Collectors.toMap(Annotation::annotationType, Function.identity(),

((first, second) -> first), LinkedHashMap::new)), annotationClass);

}

Annotation[] getDeclaredAnnotations();

}

该接口主要有如下几个实现类：

Class：类定义

Constructor：构造器定义

Field：累的成员变量定义

Method：类的方法定义

Package：类的包定义

通过反射获取成员名再获取注解值得一般写法，同样的可以通过反射获取方法等

Field fields[] = clazz.getDeclaredFields();

for (Field field : fields) {

if (field.isAnnotationPresent(Num.class)) {

Num num= field.getAnnotation(Num.class);

……

}

……

}

在网上找到了一张注解的提纲，非常详细，除了没有java 8里注解新特性，这里引用下：

注解提纲

讲了这么多，都是纯java和运行时注解的，下面开始结合Android Studio讲讲编译时注解

APT

讲编译时注解，先了解下注解处理器工具APT(Annotation Processing Tool)

APT(Annotation processing tool)是一种处理注释的工具，它对源代码文件进行检测找出其中的Annotation，使用Annotation进行额外的处理。可以在编译时进行注解处理，也可以在运行时通过反射API进行注解处理。编译时进行注解处理是根据源文件中的Annotation生成额外的源文件和其它的文件，将它们一起生成class文件。

使用APT主要的目的是简化开发者的工作量，因为APT可以编译程序源代码的同时，生成一些附属文件(比如源文件，类文件，程序发布描述文件等)，这些附属文件的内容也都是与源代码相关的，换句话说，使用APT可以代替传统的对代码信息和附属文件的维护工作。

下面将结合Android Studio实现编译时注解，主要内容来自这篇文章：THE 10-STEP GUIDE TO ANNOTATION PROCESSING IN ANDROID STUDIO。先看下项目的结构，如果是第一次尝试，包名最好先完全一样，省的哪里出错。

项目.png

新建一个android项目 AnnotationProcessor，包名为com.stablekernel.annotationprocessor，再建一个Java Library 的module，如下图所示

构建注解module

并且设置下app模块依赖processor模块

Paste_Image.png

设置兼容性

在app 模块的gradle里添加

compileOptions {

sourceCompatibility JavaVersion.VERSION_1_7

targetCompatibility JavaVersion.VERSION_1_7

}

如下图所示：

Paste_Image.png

在processor 模块的gradle里添加

sourceCompatibility = 1.7

targetCompatibility = 1.7

如下图所示：

Paste_Image.png

在processor 模块里创建注解

Paste_Image.png

CustomAnnotation是自定义的注解，源码很简单:

package com.stablekernel.annotationprocessor.processor;

public @interface CustomAnnotation {

}```

4. 在processor 模块里创建注解处理器CustomAnnotationProcessor是注解处理器，源码如下：

```java

@SupportedAnnotationTypes("com.stablekernel.annotationprocessor.processor.CustomAnnotation")

@SupportedSourceVersion(SourceVersion.RELEASE_7)

public class CustomAnnotationProcessor extends AbstractProcessor {

@Override

public boolean process(Set extends TypeElement> annotations, RoundEnvironment roundEnv) {

StringBuilder builder = new StringBuilder()

.append("package com.stablekernel.annotationprocessor.generated;\n\n")

.append("public class GeneratedClass {\n\n") // open class

.append("\tpublic String getMessage() {\n") // open method

.append("\t\treturn \"");

// for each javax.lang.model.element.Element annotated with the CustomAnnotation

for (Element element : roundEnv.getElementsAnnotatedWith(CustomAnnotation.class)) {

String objectType = element.getSimpleName().toString();

// this is appending to the return statement

builder.append(objectType).append(" says hello!\\n");

}

builder.append("\";\n") // end return

.append("\t}\n") // close method

.append("}\n"); // close class

try { // write the file

JavaFileObject source = processingEnv.getFiler()

.createSourceFile("com.stablekernel.annotationprocessor.generated.GeneratedClass");

Writer writer = source.openWriter();

writer.write(builder.toString());

writer.flush();

writer.close();

} catch (IOException e) {

// Note: calling e.printStackTrace() will print IO errors

// that occur from the file already existing after its first run, this is normal

}

return true;

}

}

稍微解释下，注解器需要继承AbstractProcessor ，并且实现process方法，CustomAnnotationProcessor 类上面两个注解@SupportedAnnotationTypes 和@SupportedSourceVersion 分别表示支持的注解的类型和支持的版本，在process里面的StringBuilder 就是在编译时要创建的新文件里面的内容了，里面一个for循环是遍历了所有使用该CustomAnnotation.class注解的元素，取出其名字。最下面的try catch 里是将该文件写入source下， 编译成功后，具体位置如下图：

Paste_Image.png

创建resources

Paste_Image.png

在processor 的main文件夹下 新建文件夹resources ，新建文件夹META-INF ，新建文件javax.annotation.processing.Processor。该文件里面的内容就是注解处理器的路径，如果有多个注解处理器，记得换行，每行写一个。

Paste_Image.png

在全局的gradle里添加android-apt依赖，再在app 模块的gradle中添加插件。

Paste_Image.png

Paste_Image.png

设置构建依赖：

Paste_Image.png

或者

dependencies {

compile files('libs/processor.jar')

……

}

然后写个任务，使得processor.jar复制到app的lib下，和预构建的任务

task processorTask(type: Copy) {

from '../processor/build/libs/processor.jar'

into 'libs/'

}

processorTask.dependsOn(':processor:build')

preBuild.dependsOn(processorTask)

app的gralde最终变成这样，供参考：

Paste_Image.png

到这里其实就已经结束了，最后为了验证下，在MainActivity中调用下就可以

@CustomAnnotation

public class MainActivity extends AppCompatActivity {

@CustomAnnotation

@Override

protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

setContentView(R.layout.activity_main);

showAnnotationMessage();

}

private void showAnnotationMessage() {

GeneratedClass generatedClass = new GeneratedClass();

String message = generatedClass.getMessage();

// android.support.v7.app.AlertDialog

new AlertDialog.Builder(this)

.setPositiveButton("Ok", null)

.setTitle("Annotation Processor Messages")

.setMessage(message)

.show();

}

}

为了加深对编译时注解的理解，再推荐下这篇文章：ButterKnife源码分析