Java编程的逻辑 (85) - 注解

本系列文章经补充和完善，已修订整理成书《Java编程的逻辑》，由机械工业出版社华章分社出版，于2018年1月上市热销，读者好评如潮！各大网店和书店有售，欢迎购买，京东自营链接：http://item.jd.com/12299018.html

上节我们探讨了反射，反射相关的类中都有方法获取注解信息，我们在前面章节中也多次提到过注解，注解到底是什么呢？

在Java中，注解就是给程序添加一些信息，用字符@开头，这些信息用于修饰它后面紧挨着的其他代码元素，比如类、接口、字段、方法、方法中的参数、构造方法等，注解可以被编译器、程序运行时、和其他工具使用，用于增强或修改程序行为等。这么说比较抽象，下面我们会具体来看，先来看Java的一些内置注解。

内置注解

Java内置了一些常用注解，比如：@Override、@Deprecated、@SuppressWarnings，我们简要介绍下。

@Override

@Override修饰一个方法，表示该方法不是当前类首先声明的，而是在某个父类或实现的接口中声明的，当前类"重写"了该方法，比如：

static class Base {
    public void action() {};
}

static class Child extends Base {
    @Override
    public void action(){
        System.out.println("child action");
    }

    @Override
    public String toString() {
        return "child";
    }
}

Child的action()重写了父类Base中的action()，toString()重写了Object类中的toString()。这个注解不写也不会改变这些方法是"重写"的本质，那有什么用呢？它可以减少一些编程错误。如果方法有Override注解，但没有任何父类或实现的接口声明该方法，则编译器会报错，强制程序员修复该问题。比如，在上面的例子中，如果程序员修改了Base方法中的action方法定义，变为了：

static class Base {
    public void doAction() {};
}

但是，程序员忘记了修改Child方法，如果没有Override注解，编译器不会报告任何错误，它会认为action方法是Child新加的方法，doAction会调用父类的方法，这与程序员的期望是不符的，而有了Override注解，编译器就会报告错误。所以，如果方法是在父类或接口中定义的，加上@Override吧，让编译器帮你减少错误。

@Deprecated

@Deprecated可以修饰的范围很广，包括类、方法、字段、参数等，它表示对应的代码已经过时了，程序员不应该使用它，不过，它是一种警告，而不是强制性的，在IDE如Eclipse中，会给Deprecated元素加一条删除线以示警告，比如，Date中很多方法就过时了：

@Deprecated
public Date(int year, int month, int date)
@Deprecated
public int getYear()

调用这些方法，编译器也会显示删除线并警告，比如：

在声明元素为@Deprecated时，应该用Java文档注释的方式同时说明替代方案，就像Date中的API文档那样，在调用@Deprecated方法时，应该先考虑其建议的替代方案。

@SuppressWarnings

@SuppressWarnings表示压制Java的编译警告，它有一个必填参数，表示压制哪种类型的警告，它也可以修饰大部分代码元素，在更大范围的修饰也会对内部元素起效，比如，在类上的注解会影响到方法，在方法上的注解会影响到代码行。对于上面Date方法的调用，如果不希望显示警告，可以这样：

@SuppressWarnings({"deprecation","unused"})
public static void main(String[] args) {
    Date date = new Date(2017, 4, 12);
    int year = date.getYear();
}

除了这些内置注解，Java并没有给我们提供更多的可以直接使用的注解，我们日常开发中使用的注解基本都是自定义的，不过，一般也不是我们定义的，而是由各种框架和库定义的，我们主要还是根据它们的文档直接使用。

框架和库的注解

各种框架和库定义了大量的注解，程序员使用这些注解配置框架和库，与它们进行交互，我们看一些例子。

Jackson

在63节，我们介绍了通用的序列化库Jackson，并介绍了如何利用注解对序列化进行定制，比如：

使用@JsonIgnore和@JsonIgnoreProperties配置忽略字段
使用@JsonManagedReference和@JsonBackReference配置互相引用关系
使用@JsonProperty和@JsonFormat配置字段的名称和格式等

在Java提供注解功能之前，同样的配置功能也是可以实现的，一般通过配置文件实现，但是配置项和要配置的程序元素不在一个地方，难以管理和维护，使用注解就简单多了，代码和配置放在一起，一目了然，易于理解和维护。

依赖注入容器

现代Java开发经常利用某种框架管理对象的生命周期及其依赖关系，这个框架一般称为DI(Dependency Injection)容器，DI是指依赖注入，流行的框架有Spring、Guice等，在使用这些框架时，程序员一般不通过new创建对象，而是由容器管理对象的创建，对于依赖的服务，也不需要自己管理，而是使用注解表达依赖关系。这么做的好处有很多，代码更为简单，也更为灵活，比如容器可以根据配置返回一个动态代理，实现AOP，这部分我们后续章节再介绍。

看个简单的例子，Guice定义了Inject注解，可以使用它表达依赖关系，比如像下面这样：

public class OrderService {
    
    @Inject
    UserService userService;
    
    @Inject
    ProductService productService;
    
    //....
}

Servlet 3.0

Servlet是Java为Web应用提供的技术框架，早期的Servlet只能在web.xml中进行配置，而Servlet 3.0则开始支持注解，可以使用@WebServlet配置一个类为Servlet，比如：

@WebServlet(urlPatterns = "/async", asyncSupported = true)
public class AsyncDemoServlet extends HttpServlet {...}

Web应用框架

在Web开发中，典型的架构都是MVC(Model-View-Controller)，典型的需求是配置哪个方法处理哪个URL的什么HTTP方法，然后将HTTP请求参数映射为Java方法的参数，各种框架如Spring MVC, Jersey等都支持使用注解进行配置，比如，使用Jersey的一个配置示例为：

@Path("/hello")
public class HelloResource {
    
    @GET
    @Path("test")
    @Produces(MediaType.APPLICATION_JSON)
    public Map<String, Object> test(
            @QueryParam("a") String a) {
        Map<String, Object> map = new HashMap<>();
        map.put("status", "ok");
        return map;
    }
}

类HelloResource将处理Jersey配置的根路径下/hello下的所有请求，而test方法将处理/hello/test的GET请求，响应格式为JSON，自动映射HTTP请求参数a到方法参数String a。

神奇的注解

通过以上的例子，我们可以看出，注解似乎有某种神奇的力量，通过简单的声明，就可以达到某种效果。在某些方面，它类似于我们在62节介绍的序列化，序列化机制中通过简单的Serializable接口，Java就能自动处理很多复杂的事情。它也类似于我们在并发部分中介绍的synchronized关键字，通过它可以自动实现同步访问。

这些都是声明式编程风格，在这种风格中，程序都由三个组件组成：

声明的关键字和语法本身
系统/框架/库，它们负责解释、执行声明式的语句
应用程序，使用声明式风格写程序

在编程的世界里，访问数据库的SQL语言，编写网页样式的CSS，以及后续章节将要介绍的正则表达式、函数式编程都是这种风格，这种风格降低了编程的难度，为应用程序员提供了更为高级的语言，使得程序员可以在更高的抽象层次上思考和解决问题，而不是陷于底层的细节实现。

创建注解

框架和库是怎么实现注解的呢？我们来看注解的创建。

@Override的定义

我们通过一些例子来说明，先看@Override的定义：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

定义注解与定义接口有点类似，都用了interface，不过注解的interface前多了@，另外，它还有两个元注解@Target和@Retention，这两个注解专门用于定义注解本身。

@Target

@Target表示注解的目标，@Override的目标是方法(ElementType.METHOD)，ElementType是一个枚举，其他可选值有：

TYPE：表示类、接口（包括注解），或者枚举声明
FIELD：字段，包括枚举常量
METHOD：方法
PARAMETER：方法中的参数
CONSTRUCTOR：构造方法
LOCAL_VARIABLE：本地变量
ANNOTATION_TYPE：注解类型
PACKAGE：包

目标可以有多个，用{}表示，比如@SuppressWarnings的@Target就有多个，定义为：

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}

如果没有声明@Target，默认为适用于所有类型。

@Retention

@Retention表示注解信息保留到什么时候，取值只能有一个，类型为RetentionPolicy，它是一个枚举，有三个取值：

SOURCE：只在源代码中保留，编译器将代码编译为字节码文件后就会丢掉
CLASS：保留到字节码文件中，但Java虚拟机将class文件加载到内存时不一定会在内存中保留
RUNTIME：一直保留到运行时

如果没有声明@Retention，默认为CLASS。

@Override和@SuppressWarnings都是给编译器用的，所以@Retention都是RetentionPolicy.SOURCE。

定义参数

可以为注解定义一些参数，定义的方式是在注解内定义一些方法，比如@SuppressWarnings内定义的方法value，返回值类型表示参数的类型，这里是String[]，使用@SuppressWarnings时必须给value提供值，比如：

@SuppressWarnings(value={"deprecation","unused"})

当只有一个参数，且名称为value时，提供参数值时可以省略"value="，即上面的代码可以简写为：

@SuppressWarnings({"deprecation","unused"})

注解内参数的类型不是什么都可以的，合法的类型有基本类型、String、Class、枚举、注解、以及这些类型的数组。

参数定义时可以使用default指定一个默认值，比如，Guice中Inject注解的定义：

@Target({ METHOD, CONSTRUCTOR, FIELD })
@Retention(RUNTIME)
@Documented
public @interface Inject {
  boolean optional() default false;
}

它有一个参数optional，默认值为false。如果类型为String，默认值可以为""，但不能为null。如果定义了参数且没有提供默认值，在使用注解时必须提供具体的值，不能为null。

@Inject多了一个元注解@Documented，它表示注解信息包含到Javadoc中。

@Inherited

与接口和类不同，注解不能继承。不过注解有一个与继承有关的元注解@Inherited，它是什么意思呢？我们看个例子：

public class InheritDemo {
    @Inherited
    @Retention(RetentionPolicy.RUNTIME)
    static @interface Test {
    }
    
    @Test
    static class Base {
    }
    
    static class Child extends Base {
    }
    
    public static void main(String[] args) {
        System.out.println(Child.class.isAnnotationPresent(Test.class));
    }
}

Test是一个注解，类Base有该注解，Child继承了Base但没有声明该注解，main方法检查Child类是否有Test注解，输出为true，这是因为Test有注解@Inherited，如果去掉，输出就变成false了。

查看注解信息

创建了注解，就可以在程序中使用，注解指定的目标，提供需要的参数，但这还是不会影响到程序的运行。要影响程序，我们要先能查看这些信息。我们主要考虑@Retention为RetentionPolicy.RUNTIME的注解，利用反射机制在运行时进行查看和利用这些信息。

在上节中，我们提到了反射相关类中与注解有关的方法，这里汇总说明下，Class、Field、Method、Constructor中都有如下方法：

//获取所有的注解
public Annotation[] getAnnotations()
//获取所有本元素上直接声明的注解，忽略inherited来的
public Annotation[] getDeclaredAnnotations()
//获取指定类型的注解，没有返回null
public <A extends Annotation> A getAnnotation(Class<A> annotationClass)
//判断是否有指定类型的注解
public boolean isAnnotationPresent(Class<? extends Annotation> annotationClass)

Annotation是一个接口，它表示注解，具体定义为：

public interface Annotation {
    boolean equals(Object obj);
    int hashCode();
    String toString();
    //返回真正的注解类型
    Class<? extends Annotation> annotationType();
}

实际上，所有的注解类型，内部实现时，都是扩展的Annotation。

对于Method和Contructor，它们都有方法参数，而参数也可以有注解，所以它们都有如下方法：

public Annotation[][] getParameterAnnotations()

返回值是一个二维数组，每个参数对应一个一维数组，我们看个简单的例子：

public class MethodAnnotations {
    @Target(ElementType.PARAMETER)
    @Retention(RetentionPolicy.RUNTIME)
    static @interface QueryParam {
        String value();
    }
    
    @Target(ElementType.PARAMETER)
    @Retention(RetentionPolicy.RUNTIME)
    static @interface DefaultValue {
        String value() default "";
    }
    
    public void hello(@QueryParam("action") String action,
            @QueryParam("sort") @DefaultValue("asc") String sort){
        // ...
    }
    
    public static void main(String[] args) throws Exception {
        Class<?> cls = MethodAnnotations.class;
        Method method = cls.getMethod("hello", new Class[]{String.class, String.class});
        
        Annotation[][] annts = method.getParameterAnnotations();
        for(int i=0; i<annts.length; i++){
            System.out.println("annotations for paramter " + (i+1));
            Annotation[] anntArr = annts[i];
            for(Annotation annt : anntArr){
                if(annt instanceof QueryParam){
                    QueryParam qp = (QueryParam)annt;
                    System.out.println(qp.annotationType().getSimpleName()+":"+ qp.value());
                }else if(annt instanceof DefaultValue){
                    DefaultValue dv = (DefaultValue)annt;
                    System.out.println(dv.annotationType().getSimpleName()+":"+ dv.value());
                }
            }
        }
    }
}

这里定义了两个注解@QueryParam和@DefaultValue，都用于修饰方法参数，方法hello使用了这两个注解，在main方法中，我们演示了如何获取方法参数的注解信息，输出为：

annotations for paramter 1
QueryParam:action
annotations for paramter 2
QueryParam:sort
DefaultValue:asc

代码比较简单，就不赘述了。

定义了注解，通过反射获取到注解信息，但具体怎么利用这些信息呢？我们看两个简单的示例，一个是定制序列化，另一个是DI容器。

应用注解 - 定制序列化

定义注解

上节我们演示了一个简单的通用序列化类SimpleMapper，在将对象转换为字符串时，格式是固定的，本节演示如何对输出格式进行定制化。我们实现一个简单的类SimpleFormatter，它有一个方法：

public static String format(Object obj)

我们定义两个注解，@Label和@Format，@Label用于定制输出字段的名称，@Format用于定义日期类型的输出格式，它们的定义如下：

@Retention(RUNTIME)
@Target(FIELD)
public @interface Label {
    String value() default "";
}

@Retention(RUNTIME)
@Target(FIELD)
public @interface Format {
    String pattern() default "yyyy-MM-dd HH:mm:ss";
    String timezone() default "GMT+8";
}

使用注解

可以用这两个注解来修饰要序列化的类字段，比如：

static class Student {
    @Label("姓名")
    String name;
    
    @Label("出生日期")
    @Format(pattern="yyyy/MM/dd")
    Date born;
    
    @Label("分数")
    double score;

    public Student() {
    }

    public Student(String name, Date born, Double score) {
        super();
        this.name = name;
        this.born = born;
        this.score = score;
    }

    @Override
    public String toString() {
        return "Student [name=" + name + ", born=" + born + ", score=" + score + "]";
    }
}

我们可以这样来使用SimpleFormatter：

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
Student zhangsan = new Student("张三", sdf.parse("1990-12-12"), 80.9d);
System.out.println(SimpleFormatter.format(zhangsan));

输出为：

姓名：张三
出生日期：1990/12/12
分数：80.9

利用注解信息

可以看出，输出使用了自定义的字段名称和日期格式，SimpleFormatter.format()是怎么利用这些注解的呢？我们看代码：

public static String format(Object obj) {
    try {
        Class<?> cls = obj.getClass();
        StringBuilder sb = new StringBuilder();
        for (Field f : cls.getDeclaredFields()) {
            if (!f.isAccessible()) {
                f.setAccessible(true);
            }
            Label label = f.getAnnotation(Label.class);
            String name = label != null ? label.value() : f.getName();
            Object value = f.get(obj);
            if (value != null && f.getType() == Date.class) {
                value = formatDate(f, value);
            }
            sb.append(name + "：" + value + "\n");
        }
        return sb.toString();
    } catch (IllegalAccessException e) {
        throw new RuntimeException(e);
    }
}

对于日期类型的字段，调用了formatDate，其代码为：

private static Object formatDate(Field f, Object value) {
    Format format = f.getAnnotation(Format.class);
    if (format != null) {
        SimpleDateFormat sdf = new SimpleDateFormat(format.pattern());
        sdf.setTimeZone(TimeZone.getTimeZone(format.timezone()));
        return sdf.format(value);
    }
    return value;
}

这些代码都比较简单，我们就不解释了。

应用注解 - DI容器

定义@SimpleInject

我们再来看一个简单的DI容器的例子，我们引入一个注解@SimpleInject，修饰类中字段，表达依赖关系，定义为：

@Retention(RUNTIME)
@Target(FIELD)
public @interface SimpleInject {
}

使用@SimpleInject

我们看两个简单的服务ServiceA和ServiceB，ServiceA依赖于ServiceB，它们的定义为：

public class ServiceA {

    @SimpleInject
    ServiceB b;
    
    public void callB(){
        b.action();
    }
}

public class ServiceB {

    public void action(){
        System.out.println("I'm B");
    }
}

ServiceA使用@SimpleInject表达对ServiceB的依赖。

DI容器的类为SimpleContainer，提供一个方法：

public static <T> T getInstance(Class<T> cls)

应用程序使用该方法获取对象实例，而不是自己new，使用方法如下所示：

ServiceA a = SimpleContainer.getInstance(ServiceA.class);
a.callB();

利用@SimpleInject

SimpleContainer.getInstance会创建需要的对象，并配置依赖关系，其代码为：

public static <T> T getInstance(Class<T> cls) {
    try {
        T obj = cls.newInstance();
        Field[] fields = cls.getDeclaredFields();
        for (Field f : fields) {
            if (f.isAnnotationPresent(SimpleInject.class)) {
                if (!f.isAccessible()) {
                    f.setAccessible(true);
                }
                Class<?> fieldCls = f.getType();
                f.set(obj, getInstance(fieldCls));
            }
        }
        return obj;
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

代码假定每个类型都有一个public默认构造方法，使用它创建对象，然后查看每个字段，如果有SimpleInject注解，就根据字段类型获取该类型的实例，并设置字段的值。

定义@SimpleSingleton

在上面的代码中，每次获取一个类型的对象，都会新创建一个对象，实际开发中，这可能不是期望的结果，期望的模式可能是单例，即每个类型只创建一个对象，该对象被所有访问的代码共享，怎么满足这种需求呢？我们增加一个注解@SimpleSingleton，用于修饰类，表示类型是单例，定义如下：

@Retention(RUNTIME)
@Target(TYPE)
public @interface SimpleSingleton {
}

使用@SimpleSingleton

我们可以这样修饰ServiceB：

@SimpleSingleton
public class ServiceB {

    public void action(){
        System.out.println("I'm B");
    }
}

利用@SimpleSingleton

SimpleContainer也需要做修改，首先增加一个静态变量，缓存创建过的单例对象：

private static Map<Class<?>, Object> instances = new ConcurrentHashMap<>();

getInstance也需要做修改，如下所示：

public static <T> T getInstance(Class<T> cls) {
    try {
        boolean singleton = cls.isAnnotationPresent(SimpleSingleton.class);
        if (!singleton) {
            return createInstance(cls);
        }
        Object obj = instances.get(cls);
        if (obj != null) {
            return (T) obj;
        }
        synchronized (cls) {
            obj = instances.get(cls);
            if (obj == null) {
                obj = createInstance(cls);
                instances.put(cls, obj);
            }
        }
        return (T) obj;
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

首先检查类型是否是单例，如果不是，就直接调用createInstance创建对象。否则，检查缓存，如果有，直接返回，没有的话，调用createInstance创建对象，并放入缓存中。

createInstance与第一版的getInstance类似，代码为：

private static <T> T createInstance(Class<T> cls) throws Exception {
    T obj = cls.newInstance();
    Field[] fields = cls.getDeclaredFields();
    for (Field f : fields) {
        if (f.isAnnotationPresent(SimpleInject.class)) {
            if (!f.isAccessible()) {
                f.setAccessible(true);
            }
            Class<?> fieldCls = f.getType();
            f.set(obj, getInstance(fieldCls));
        }
    }
    return obj;
}

小结

本节介绍了Java中的注解，包括注解的使用、自定义注解和应用示例。

注解提升了Java语言的表达能力，有效地实现了应用功能和底层功能的分离，框架/库的程序员可以专注于底层实现，借助反射实现通用功能，提供注解给应用程序员使用，应用程序员可以专注于应用功能，通过简单的声明式注解与框架/库进行协作。

下一节，我们来探讨Java中一种更为动态灵活的机制 - 动态代理。

(与其他章节一样，本节所有代码位于 https://github.com/swiftma/program-logic，位于包shuo.laoma.dynamic.c85下)

----------------

未完待续，查看最新文章，敬请关注微信公众号“老马说编程”(扫描下方二维码)，从入门到高级，深入浅出，老马和你一起探索Java编程及计算机技术的本质。用心原创，保留所有版权。

posted @ 2017-05-11 08:00 老马说编程阅读(2794) 评论(0) 编辑收藏举报

会员力量，点亮园子希望

刷新页面返回顶部

老马说编程

深入浅出探索Java编程及计算机技术的本质

Java编程的逻辑 (85) - 注解

公告