Java 注解（Annotation）的简介与使用实例

注解和注释的联系与区别

注解和注释都有对目标（类、方法、参数等）进行补充说明的作用，它们的区别在于：

• 注释只存在于类文件中，不参与编译；注解可以参与编译，也可以不参与编译。
• 注释内容仅供开发者和用户在编写程序时查看，对程序本身不会造成任何影响；注解可以在程序运行时利用反射读取，可以对程序本身造成影响。

java.lang中定义的三种注解

java.lang中定义了三种常用的注解：

• @Override：表示当前的方法定义将覆盖超类中的方法。如果把方法的名字拼错，或是参数列表与超类不一致（变成了重载），编译器就会发出错误提示。
• @Deprecated：表示该方法已经被废弃。如果在代码中使用被@Deprecated注解的方法，编译器会发出警告。
• @SuppressWarnings：关闭不当的编译器警告信息。

标记注解

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface DBTable {

}

上面的代码段中就定义了一个最简单的自定义注解。这个注解中没有任何元素，因此被称为标记注解。可以看出，注解的定义和接口很像，仅仅是在interface关键字前面加上了一个@。与类和接口的不同的是，在创建注解时需要加上两个元注解：@Target与@Retention。元注解是Java系统提供的，负责新注解的创建。

@Target

@Target用于定义该注解将应用于什么地方，可以是类、方法、域、参数等等。它的取值（存在于枚举类ElementType中）有以下几种：

• TYPE：类、接口（包括注解）、枚举
• FIELD：域、枚举实例
• METHOD：方法
• PARAMETER：参数声明
• CONSTRUCTOR：构造器
• LOCAL_VARIABLE：局部变量
• ANNOTATION_TYPE：注解
• PACKAGE：包
• （Java 8）TYPE_PARAMETER：类型变量的声明。例：String str= new @NotNull String();
• （Java 8）TYPE_USE：使用类型的任何语句（声明语句、泛型和强制转换语句中的类型）。例：myString = (@NonNull String) str;

@DBTable被@Target(ElementType.TYPE)标注，因此它可以被用在类、接口、枚举上。

@Retention

@Retention用于定义注解在哪个级别可用。它的取值（存在于RetentionPolicy枚举类中）有以下几种：

• SOURCE：注解会被编译器抛弃
• CLASS：注解在class文件中可用，但会在运行时被VM抛弃
• RUNTIME：注解在运行期也将被保留，可以利用反射读取

@DBTable被@Retention(RetentionPolicy.RUNTIME)标注，因此它可以存在于运行期。

注解的简单使用

@DBTable
public class Table {
    ...
}

这样就给Table类加上了@DBTable注解。可以看出，注解的使用几乎和其他修饰符（public、static等）相同。
现在，这个注解还没有任何意义，后面会演示它的作用。

为注解添加元素

注解中可以添加以下类型的元素：

• 所有基本类型（int、long）
• String
• Class
• enum
• Annotation
• 以上类型的数组

下面为@DBTable注解添加一个String类型的tableName元素：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface DBTable {
    public String tableName() default "";
}

注意：元素名称后面要加上一对圆括号。这是因为注解本身是一种继承自接口java.lang.annotation.Annotation的特殊接口。
可以利用default为元素设置默认值，当使用注解时没有给出该元素的值时，会使用预先设置的默认值。如果元素没有提供默认值，那么在使用时就必须给定一个值，否则编译器会报错。

有元素的注解的使用

@DBTable(tableName = "Table1")
public class Table {

}

这样就将@DBTable中的tableName设置成了“Table1”。
如果注解有多个元素需要设置，只需用逗号分隔开：

@User(id = 100, name = "Bob")

如果某个元素是数组，那么需要加上一对大括号：

@SuiteClasses({
    Test1.class,
    Test2.class,
    Test3.class
})

上面的例子中还有一个特殊的地方：前面在为元素赋值时都使用“名 = 值”的模式，而这里没有显式标明元素名。实际上，这个是Java系统提供的一种“快捷方式”：如果注解中某个元素是唯一需要赋值的元素（唯一一个没有提供默认值的元素，或者是唯一一个元素），并且该元素值名为value，那么在赋值时就可以省去元素名与等号。
下面是SuiteClasses的定义，可以看到它只有一个元素，并且名称为value：

public @interface SuiteClasses {
    public Class<?>[] value();
}

注解处理器实例：根据JavaBean生成SQL语句

相比于注释，注解的最大优点就是可以在运行时通过反射读取其内容，这为编写各种工具类乃至框架提供了极大的便利。下面的例子中提供了一个工具类以及一系列注解，可以根据满足JavaBean规范的类动态地生成SQL语句。
首先是使用到的自定义注解：
（1）表名注解@DBTable：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface DBTable {
    public String tableName() default "";
}

（2）整型注解@SQLInteger：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SQLInteger {
    String name() default "";
}

（3）字符串型注解@SQLString：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SQLString {
    public String name() default "";
    public int length();
}

下面是注解处理器，基本都是通过反射读取注解内容实现。需要注意的一点是，JavaBean模式下所有域的访问权限都是private的，因此需要利用reflect包内的AccessibleObject类提供的方法获取其访问权限。

public class TableCreater {

    public static String printSQL(Class<?> clazz){
        //判断clazz是否有DBTable注解，若没有则返回
        DBTable dbTable;
        if(clazz == null || (dbTable = clazz.getAnnotation(DBTable.class)) == null) {
            return null;
        }

        //获得表名
        String tableName = dbTable.tableName().length() < 1 ?
                clazz.getName().toUpperCase() : dbTable.tableName() .toUpperCase();

        //获得所有域及其访问权限
        Field[] fields = clazz.getDeclaredFields();
        AccessibleObject.setAccessible(fields, true);

        //生成SQL语句CREATE TABLE中每一行的内容
        List<String> columns = new LinkedList<>();
        for(Field field : fields) {
            String column = null;
            Annotation[] annotations = field.getDeclaredAnnotations();
            if(annotations.length < 1) {
                continue;
            }
            for(Annotation annotation : annotations) {
                if(annotation instanceof SQLInteger) {
                    SQLInteger sInteger = (SQLInteger)annotation;
                    String name = sInteger.name().length() < 1 ?
                            field.getName().toUpperCase() : sInteger.name().toUpperCase();
                    column = name + " " + "INT";
                }else if (annotation instanceof SQLString) {
                    SQLString sString = (SQLString)annotation;
                    String name = sString.name().length() < 1 ?
                            field.getName().toUpperCase() : sString.name().toUpperCase();
                    String type = "VARCHAR(" + String.valueOf(sString.length()) + ")";
                    column = name + " " + type;
                }
            }
            if(column != null){
                columns.add(column);
            }
        }

        //将表名和各行内容拼接成SQL语句
        StringBuilder sql = new StringBuilder();
        sql.append("CREATE TABLE ");
        sql.append(tableName);
        sql.append("(\n");
        for(int i = 0 ; i < columns.size() ; i++){
            sql.append("    ");
            sql.append(columns.get(i));
            if(i < columns.size() - 1){
                sql.append(',');
            }
            sql.append('\n');
        }
        sql.append(")\n");

        //返回结果
        return sql.toString();
    }

}

下面看一个运行实例。首先是需要生成SQL语句的UserInfo类：

@DBTable(tableName = "USER")
public class UserInfo {
    public UserInfo() {

    }

    @SQLString(length = 10)
    private String name;

    @SQLInteger
    private int age;

    @SQLString(length = 30)
    private String job;

    @SQLString(length = 30)
    private String email;

    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
    public String getJob() {
        return job;
    }
    public void setJob(String job) {
        this.job = job;
    }
    public String getEmail() {
        return email;
    }
    public void setEmail(String email) {
        this.email = email;
    }
}

将UserInfo.class作为参数传入TableCreater.printSQL方法中：

public static void main(String[] args) {
    System.out.println(TableCreater.printSQL(UserInfo.class));
}

输出结果：

CREATE TABLE USER(
    NAME VARCHAR(10),
    AGE INT,
    JOB VARCHAR(30),
    EMAIL VARCHAR(30)
)

@Documented与@Inherited

@Documented与@Inherited也是创建自定义注解时使用的元注解，它们的意义如下：

• @Documented：将此注解包含在Javadoc中。
• @Inherited：允许子类继承父类的注解。

（Java 8）重复注解

一般的注解不能在一个目标上重复使用。不过，在Java 8中新增了一个@Repeatable注解，通过它可以实现重复注解。使用方法如下：
（1）创建一个需要实现重复注解功能的注解：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface User {
    String value();
}

（2）创建一个注解容器：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface Users {
    User[] value();
}

（3）为（1）中的注解加上@Repeatable并赋值，值为（2）中的注解容器的Class对象：

@Repeatable(Users.class)

使用示例：

@User("John")
@User("Bob")
public class SomeClass {

}