阅读 1381

计算机程序的思维逻辑 (85) - 注解

本系列文章经补充和完善,已修订整理成书《Java编程的逻辑》(马俊昌著),由机械工业出版社华章分社出版,于2018年1月上市热销,读者好评如潮!各大网店和书店有售,欢迎购买:京东自营链接

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

在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关键字,通过它可以自动实现同步访问。

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

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

在编程的世界里,访问数据库的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中一种更为动态灵活的机制 - 动态代理。

(与其他章节一样,本节所有代码位于 github.com/swiftma/pro…,位于包shuo.laoma.dynamic.c85下)


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

关注下面的标签,发现更多相似文章
评论