Jersey 开发RESTful（十五） Jersey的拦截器

【原创文章，转载请注明原文章地址，谢谢！】

上一节我们介绍了Jesery中的过滤器。过滤器主要用来处理请求头，响应头，请求URI地址等等，但是如果涉及到想要修改请求实体内容或者响应实体内容相关的统一业务，就需要使用Jersey提供的拦截器。
另外，拦截器和过滤器还有很多相同的额外特性，比如Namebind和优先级，也会在本节中介绍。

拦截器简介

在JAX-RS中，提供了拦截器机制，可以对服务端和移动端的请求/响应实体内容进行统一处理。和过滤器一样，拦截器也可以针对移动端和客户端，和过滤器不一样的是，拦截器在客户端和服务端都是相同的：

javax.ws.rs.ext.WriterInterceptor：写拦截器，可以在其中对于响应实体进行拦截操作；
javax.ws.rs.ext.ReaderInterceptor：读拦截器，可以在其中对于请求实体进行拦截操作；

我们分别来看下这两个拦截器的使用（以下两个例子来源于Jersey 用户指南https://jersey.github.io/documentation/latest/user-guide.html#filters-and-interceptors）：

public class GZIPWriterInterceptor implements WriterInterceptor {
     
    @Override
    public void aroundWriteTo(WriterInterceptorContext context)
                    throws IOException, WebApplicationException {
        final OutputStream outputStream = context.getOutputStream();
        context.setOutputStream(new GZIPOutputStream(outputStream));
        context.proceed();
    }
}

WriterInterceptor需要实现一个方法，aroundWriteTo，该方法传入了一个WriterInterceptorContext对象，通过这个对象我们能够得到相应体相关内容，相应头相关的内容：

image.png

我们来看下具体代码，在GZIPWriterInterceptor中，主要是把相应内容使用GZip压缩传输。
第一句代码，通过getOutputStream得到相应输出流；
第二句代码，使用GZIPOutputStream完成输出流的转化，并使用setOutputStream方法，替换原始相应输出流，变成gzip输出流；
第三句代码，使用proceed方法，让执行流程继续向下执行。这个proceed方法大家只要回忆一下Servlet中的Filter的chain.doFilterChain(req,resp)方法，或者想一下SpringAOP中的的around增强，方法中要调用ProceedingJoinPoint.proceed()方法让方法继续向下执行。在JAX-RS的interceptor中相似，interceptor可以有多个，构成一个拦截器链，执行完一个拦截器之后，需要把响应继续向下执行，只到传播到之前我们讲过的MessageBodyWriter的writeTo方法。

要使用该拦截器，有两种方式，第一种在该类上添加@Provider，使用JAX-RS的自动发现机制，第二种方式在服务器端使用ResourceConfig提供的register方法注册即可。

服务端的响应使用GZIP完成压缩，那么在客户端的请求中，就需要对GZIP请求进行解压缩：

public class GZIPReaderInterceptor implements ReaderInterceptor {
     
    @Override
    public Object aroundReadFrom(ReaderInterceptorContext context)
                    throws IOException, WebApplicationException {
        final InputStream originalInputStream = context.getInputStream();
        context.setInputStream(new GZIPInputStream(originalInputStream));
        return context.proceed();
    }
}

ReaderInterceptor和WriterInterceptor类似，只需要实现aroundReadFrom方法即可。同样，该方法传入了一个ReaderInterceptorContext类，我们可以通过这个类来处理请求实体相关内容：

image.png

在GZIPReaderInterceptor中，
第一句话代码，通过ReaderInterceptorContext获取请求输入流；
第二句代码，使用GZIPInputStream对请求输入流进行包装，后面再通过GZIPInputStream获取的内容就是gzip解压之后的原始内容了（即服务端使用gzip压缩之前的响应实体输出流）；将包装完成之后的新的输入流通过setInputStream方法替换原始请求流；
第三句代码，同上面介绍WriterInterceptor一样，我们也需要调用ReaderInterceptorContext的proceed方法，让请求流继续向下执行，只到之前介绍的MessageBodyReader的readFrom方法。

当然，上面的两段代码只是用作演示作用，在Jersey中，实际提供了针对GZIP的拦截器：org.glassfish.jersey.message.GZipEncoder。在Jersey中大量的使用了一个类来同时实现请求/响应的拦截器（过滤器/Entity Provider），有兴趣研究的童鞋可以去看看这个类的代码，这个类也是很简单的，本文中就不做过多介绍了。

拦截器和过滤器执行流程

综合上一节和上一篇文章的内容，我们来综合看一下，当拦截器和过滤器配合在一起时候的整个客户端请求到服务端响应的执行流程。

分析背景：在服务端和客户端都配置了一个GZIP拦截器；并且配置了过滤器用于修改请求头。

• 客户端发起一个POST请求；
• 客户端配置的ClientRequestFilters执行，完成请求头的修改；
• 客户端配置的GZIP拦截器（WriterInterceptor）执行，得到请求实体内容，并使用GZIPOutputStream压缩；
• 客户端配置的MessageBodyWriter执行，把实体内容通过gzip压缩并写入请求实体内容输出流中，真正发送请求；
• 服务端接受到请求。注意这个时候请求实体输入流中的内容是客户端通过gzip压缩之后的流；
• 所有标记了@PreMatching的ContainerRequestFilters执行；并完成URI到资源方法的匹配；
• 所有的PostMatching（默认的）的ContainerRequestFilters执行；
• 服务端的ReaderInterceptor过滤器执行，将请求中的压缩输入流包装到GZIPInputStream中解压缩；
• 服务端的MessageBodyReader执行，执行请求到资源方法实体的转化；
• 服务端资源类的方法执行；
• 服务端的ContainerResponseFilters过滤器执行，对响应头进行操作；
• 服务端的WriterInterceptor执行，将响应实体内容包装到GZIPOutputStream中；
• 服务端的MessageBodyWriter执行，将资源方法返回的实体写入到gzip压缩流中，执行响应返回；
• 客户端得到响应流，注意这个时候得到的响应流是gzip压缩之后的响应流；
• 客户端的ClientResponseFilters过滤器执行，对响应头做统一处理；
• 客户端在Response对象上执行response.readEntity()方法；
• 客户端的ReaderInterceptor拦截器执行，将原始响应实体输入流包装到GZIPInputStream中；
• 客户端的MessageBodyReaders执行，将解压后的响应实体转化成对应响应对象；
• 完成整个执行流程；

名称绑定(name bind)

在之前的过滤器和拦截器的介绍中我们发现，在服务器端，我们都是通过ResourceConfig的register方法统一注册服务端过滤器或者拦截器。但是这存在一个问题，我们能不能只针对某一些资源方法执行过滤器或者拦截器呢？（在客户端其实也有这个问题，但是客户端会灵活很多，因为客户端可以通过各种类，比如ClientConfig，Client，WebTarget等等单独注册拦截器或者过滤器）

在JAX-RS中，提供了NameBinding机制，简单理解NameBinding，就是把指定过滤器/拦截器通过资源方法的名称绑定在某些匹配的资源方法上。直接看一个例子：

首先我们定义一个注解类：

@NameBinding
@Retention(RetentionPolicy.RUNTIME)
public @interface Compress {}

在这里，我们定义了一个@Compress注解，并且在该注解上添加了一个@NameBinding注解，代表这是JAX-RS中的一个名称绑定标记；

再写一个资源类

@Path("helloworld")
public class HelloWorldResource {
 
    @GET
    @Produces("text/plain")
    public String getHello() {
        return "Hello World!";
    }
 
    @GET
    @Path("too-much-data")
    @Compress
    public String getVeryLongString() {
        String str = ... // very long string
        return str;
    }
}

在这个资源类中我们定义了两个资源，其中helloworld/too-much-data这个资源方法上面，我们添加了@Compress注解；

最后，修改我们的GZIPWriterInterceptor：

@Compress
public class GZIPWriterInterceptor implements WriterInterceptor {
    @Override
    public void aroundWriteTo(WriterInterceptorContext context)
                    throws IOException, WebApplicationException {
        final OutputStream outputStream = context.getOutputStream();
        context.setOutputStream(new GZIPOutputStream(outputStream));
        context.proceed();
    }
}

这个GZIPWriterInterceptor和我们之前的GZIPWriterInterceptor没有区别，唯一的区别就在于我们在这个类上添加了@Compress注解。

至此，我们的Namebinding已经配置完成，效果就是GZIPWriterInterceptor只会作用于添加了@Compress注解的资源方法请求。

动态绑定

通过NameBinding我们可以很方便的控制拦截器和过滤器要针对处理的资源方法；但是有个问题，我们的NameBinding注解大量分散在各个资源类的各个资源方法上，我们要检查某个过滤器到底过滤了哪些资源方法，是非常困难的。这非常类似我们在Spring中的事务控制，一种方式我们可以通过@Transactional标签来控制，另一种方式我们可以通过配置的方式来统一添加事务，在实际的开发中，我们更建议使用xml统一配置的方式来完成事务配置，因为这样【集中管理】。

在JAX-RS中，除了NameBinding的匹配方式，还提供了动态绑定的方式来统一配置过滤器/拦截器的匹配规则。我们直接来看代码。要想完成上面namebinding相同的效果，我们可以这样来写一个类：

public class CompressionDynamicBinding implements DynamicFeature {
     
    @Override
    public void configure(ResourceInfo resourceInfo, FeatureContext context) {
        if (HelloWorldResource.class.equals(resourceInfo.getResourceClass())
                && resourceInfo.getResourceMethod()
                    .getName().contains("VeryLongString")) {
            context.register(GZIPWriterInterceptor.class);
        }
    }
}

这个类非常简单，实现了DynamicFeature接口，很明显这就是一个特殊的Provider，我们实现了configure方法，在方法中，通过传入的ResourceInfo对象，我们做了这样的判断：
1，本次请求的资源类型为HelloWorldResource；
2，本次请求的资源方法名中包含VeryLongString；
即完成匹配；那么我们注册一个GZIPWriterInterceptor（即针对这些匹配的资源方法执行GZIPWriterInterceptor拦截器）；

要使用该类非常简单，只需要添加@Provider标签即可。
那么，要实现正则表达式的匹配，只需要自己使用正则对方法名进行匹配即可。达到非常灵活的统一资源匹配方式。

优先级

当我们为应用定义了多个过滤器/拦截器之后，在某些情况下，希望对这些过滤器/拦截器的顺序进行控制，这个时候，只需要使用 javax.annotation.Priority注解标记在过滤器或者拦截器类上，即可完成执行顺序的控制。

image.png

该标签就只有一个int类型的value，要求该值为一个正整数，并且该值越大，优先级越低（即越后执行）；

但是注意，一般情况下面，我们不会自己随意的去设置这个优先级。在Jersey中，提供了一个javax.ws.rs.Priorities类，在该类中为我们定义了一些基础的优先级值：

image.png

在Jersey中所有内置的过滤器/拦截器，都是直接使用这些预定义好的优先级来定义自己的过滤器/拦截器优先级：

@Priority(Priorities.HEADER_DECORATOR)
public class ResponseFilter implements ContainerResponseFilter {
 
}

@Priority(Priorities.HEADER_DECORATOR+1)
public class ResponseFilter2 implements ContainerResponseFilter {
 
}

代码非常简单，两个过滤器都使用Priorities.HEADER_DECORATOR这个基础优先级，并且ResponseFilter2在Priorities.HEADER_DECORATOR基础上+1，则执行顺序在ResponseFilter之后。

小结

在本节中，介绍了Jersey中的拦截器，并介绍了拦截器+过滤器的一个完整的客户端-服务端的请求响应执行流程。然后介绍了定义过滤器/拦截器的两种资源方法匹配机制NameBinding和动态绑定。最后介绍了拦截器/过滤器的优先级定义。

至此，Jersey中的常用的内容介绍完毕。下一节我们介绍Jersey中的统一异常处理。

WechatIMG7.jpeg