关于JAVA中源码级注解的编写及使用

一、注解简介：

1.1.什么是“注解”：

在我们编写代码时，一定看到过这样的代码：

class Student {

    private String name;

    @Override

    public String toString(String str) {//编译错误！

        return "Student name = " + name;

    }

}

其中的@Override，就是一个“注解”，@Override一般出现在重写equals()或者toString()方法的上边，意思是告诉编译器：下边的代码是重写父类方法的。这时编译器会按照“重写”的语法严格检查下面的方法，如果不符合重写语法，将会编译错误。

"注解"作为一种“标记”，被写在源码中，不会改变程序的执行流程。它通常由“注解解析工具”来解析，而“注解解析器”可以随Java编译器启动，也可以独立启动，来解析注解，并以此可以做一些事情。

1.2.注解的分类：

源码注解：

注解只在源码中，编译成class文件后就不存在了。

编译时注解：

注解在源码和.class文件中都存在（如：JDK内置系统注解）

运行时注解：

在运行阶段还起作用，甚至会影响运行逻辑的注解（如：JUnit的@Test）

1.3.注解的作用

注解的作用非常广泛，注解可以被用在类、属性、构造方法、成员方法、局部变量等位置，用于对这些元素进行说明。由“注解解析工具”解析后，可以生成文档、进行代码分析、编译检查等。

本例将会实现一个用作"编译检查“的注解，以及一个"注解解析器"。"注解解析器"将会随着javac编译器一同启动来对使用了注解的类进行编译，并检查类名、字段名、方法名是否以大写、小写字符开头，如果违反了规则，编译时将会报错。

二、自定义注解：

2.1.定义注解的基本语法

“注解”本质上是一个“类”，我们可以根据自己的需要定义自己的注解。

定义注解的语法很简单：

public @interface CheckWord{

	...

}

"注解”编译后会生成.class文件。但这是一个非常简单的注解，它可以被用在任何位置，而且编译器遇到这种注解也不做任何事情。例如：

@CheckWord

public class Student {

    @CheckWord

    public Student() {

    }

    @CheckWord

    private String name;

    @CheckWord

    public void study() {

    }

}

下面我们先使用“元注解”来规定这个注解可以被用在哪里。

2.2.元注解

“元注解”也是一种“注解”，它是已经实现好的。必须用在“注解”的定义上，它可以规定注解可以用在哪里，以及可以存在于源码中，或者class中，或者运行时。

常用的“元注解”有两个：

1).@Target : 规定注解可以用在哪里。常用的取值被定义在枚举java.lang.annotation.ElementType中：

ElementType.TYPE：类和接口上

ElementType.FIELD：用在成员变量上

ElementType.METHOD：用在方法上

ElementType.PARAMETER：用在参数上

ElementType.CONSTRUCTOR：用在构造方法上

ElementType.LOCAL_VARIABLE：用在局部变量上

2).@Retention : 规定注解可以存在于哪里。常用的取值被定义在枚举java.lang.annotation.RetentionPolicy中：

RetentionPolicy.SOURCE：规定注解只存在于Java源代码中，编译生成的字节码文件中就不存在了。

RetentionPolicy.CLASS：规定注解存在于Java源代码、编译以后的字节码文件中，但JVM运行时，不会被加载到内存。

RetentionPolicy.RUNTIME：规定注解存在于Java源代码中、编译以后的字节码文件中、运行时内存中，程序可以通过反射获取该注解。

例如：修改我们的注解，规定它只能用在"类","字段"，“方法”上，并且可以存在于“源码中”：

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})

@Retention(RetentionPolicy.SOURCE)

public @interface CheckWord {

}

如果再编译之前的Student类，会发现用在"构造方法"上的@CheckWord会编译错误，因为我们规定了它只能用在"类","字段","方法"上。

2.3.定义注解的属性：

1.“注解”中可以定义一些属性，“注解解析器”可以根据“属性”的不同，分别做不同的事情。

例如@Target注解中的ElementType.TYPE就是此注解的一个属性，它是一个"枚举"类型。

下面让我们来看看怎样定义属性，然后再解析这些属性。

注解中定义属性的语法：数据类型属性名() [deafult 值];

1.其中“数据类型”可以是：

1).所有基本类型;

2).String;

3).Class;

4).枚举;

5).注解；

6).以上任一类型的数组

2.属性名()：属性名可以自由设定，要遵循Java标识符的命名规则；其中的一对()是必须的。

3.[default 值]：为此属性设置的默认值。

2.本例中由于只检查大小写，为了规范取值，所以定义一个"枚举"类型的属性。

1).先定义枚举：

public enum StartsWith {

    UPPERCASE, LOWERCASE

}

此枚举定义了两个值：UPPERCASE表示：大写；LOWERCASE表示：小写。

2).修改"CheckWord"注解的代码：

@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})

@Retention(RetentionPolicy.SOURCE)

public @interface CheckWord {

    StartsWith value();

}

说明：

a.StartsWith表示"数据类型"，是一个"枚举"类型。

b.value表示"属性名"，在使用此注解时，此属性的可取值只有StartsWith.UPPERCASE和StartsWith.LOWERCASE两个。

c.此属性没有设置"默认值"，在使用此注解时必须要设置此属性的值。如下面的代码：

3).修改"Student"类的代码：

@CheckWord(StartsWith.UPPERCASE)

public class Student {

    @CheckWord(StartsWith.LOWERCASE)

    private String stuName;

    @CheckWord(StartsWith.LOWERCASE)

    public void show() {

    }

}

2.4注解解析器：

1."注解解析器"通常是随着注解一起定义的，用于解析"注解"，并做一些事情。本例的"注解解析器"用于与javac编译器一起启动，编译Student类时，检查各元素的名称是否按要求以指定的大写、小写字母开头。

2.自定义"注解解析器"需要继承AbstractProcessor类，并重写process()方法，完整的"注解解析器"代码如下：

import javax.annotation.processing.AbstractProcessor;

import javax.annotation.processing.RoundEnvironment;

import javax.annotation.processing.SupportedAnnotationTypes;

import javax.annotation.processing.SupportedSourceVersion;

import javax.lang.model.SourceVersion;

import javax.lang.model.element.Element;

import javax.lang.model.element.TypeElement;

import javax.tools.Diagnostic;

import java.util.Set;

@SupportedAnnotationTypes("CheckWord")

@SupportedSourceVersion(SourceVersion.RELEASE_8)

public class MyProcessor extends AbstractProcessor {

    @Override

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

        //获取所有使用了@CheckWord注解的元素

        Set<? extends Element> annoEle = roundEnv.getElementsAnnotatedWith(CheckWord.class);

        // 遍历这些元素

        for (Element e : annoEle) {

            //获取元素名称，可能是：类名、属性名、方法名

            String name = e.getSimpleName().toString();

            //获取这个名字的第一个字母

            char c = name.charAt(0);

            //获取这个元素上的@CheckWord注解对象

            CheckWord anno = e.getAnnotation(CheckWord.class);

            //获取这个注解的value属性的值，它是一个StartsWith枚举类型

            StartsWith sw = anno.value();

            //判断属性值是否设置为：StartsWith.UPPERCASE，但名字的首字母是小写

            if (sw == StartsWith.UPPERCASE && Character.isLowerCase(c)) {

                //向控制台打印异常信息

                this.processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "名称：" + name + " 首字母应该大写！");

                return false;

            }

            //判断属性值是否设置为：StartsWith.LOWERCASE，但名字的首字母是大写

            if (sw == StartsWith.LOWERCASE && Character.isUpperCase(c)) {

                this.processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "名称：" + name + " 首字母应该小写！");

                return false;

            }

        }

        return true;

    }

}

此代码的细节大家可以根据注释一点一点研究。一些类：TypeElement，RoundEnvironment，Element等的一些方法大家可以在API手册中查找。

其它说明：

@SupportedAnnotationTypes("CheckWord") : 表示只处理CheckWord注解。

@SupportedSourceVersion(SourceVersion.RELEASE_8) ：表示支持JDK1.8。

2.5.编译和测试：

1.在编译前，我们看一下完整的代码清单：请确保以下的四个类在同一个目录下

1).枚举类：

public enum StartsWith {

    UPPERCASE, LOWERCASE

}

2).自定义注解类：

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})

@Retention(RetentionPolicy.SOURCE)

public @interface CheckWord {

    StartsWith value();

}

3).使用了CheckWord注解的Student类：

@CheckWord(StartsWith.UPPERCASE)

public class Student {

    @CheckWord(StartsWith.LOWERCASE)

    private String StuName;

    @CheckWord(StartsWith.LOWERCASE)

    public void show() {

    }

}

4).注解解析器类：

import javax.annotation.processing.AbstractProcessor;

import javax.annotation.processing.RoundEnvironment;

import javax.annotation.processing.SupportedAnnotationTypes;

import javax.annotation.processing.SupportedSourceVersion;

import javax.lang.model.SourceVersion;

import javax.lang.model.element.Element;

import javax.lang.model.element.ElementKind;

import javax.lang.model.element.TypeElement;

import javax.tools.Diagnostic;

import java.util.Set;

@SupportedAnnotationTypes("CheckWord")

@SupportedSourceVersion(SourceVersion.RELEASE_8)

public class MyProcessor extends AbstractProcessor {

    @Override

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

        Set<? extends Element> annoEle = roundEnv.getElementsAnnotatedWith(CheckWord.class);

        for (Element e : annoEle) {

            String name = e.getSimpleName().toString();

            char c = name.charAt(0);

            CheckWord anno = e.getAnnotation(CheckWord.class);

            StartsWith sw = anno.value();

            if (sw == StartsWith.UPPERCASE) {

                if (Character.isLowerCase(c)) {

                    this.processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "名称：" + name + " 首字母应该大写！");

                    return false;

                }

            }

            if (sw == StartsWith.LOWERCASE) {

                if (Character.isUpperCase(c)) {

                    this.processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "名称：" + name + " 首字母应该小写！");

                    return false;

                }

            }

        }

        return true;

    }

}

2.启动命令行，使用javac依次进行编译：

javac StartsWith.java

javac CheckWord.java

javac MyProcessor.java（如果报错：编码GBK的不可映射字符，是因为代码中的中文，可以使用javac -encoding UTF-8 MyProcessor.java进行编译）

接下来使用MyProcessor解析器编译Student:

javac -processor MyProcessor Student.java

执行命令后，会有错误提示：

错误: 名称：StuName 首字母应该小写！

1 个错误

三、总结：

源码级注解的应用非常广泛，例如：进行代码检查、生成新类、生成文件。本文实现了基本的代码检查，用于检查类中的元素是否按照要求进行首字母大写或者小写。也可以根据需要，验证是否全部大写，或者全部小写。希望大家通过本案例能够了解源码级注解的编写及使用。