Springboot整合Jersey实现REST full风格API及原理

2023-01-09 Spring全家桶实战案例

环境：Springboot2.5.13

概述

Jersey RESTful 框架是开源的RESTful框架, 实现了JAX-RS (JSR 311 & JSR 339) 规范。它扩展了JAX-RS 参考实现，提供了更多的特性和工具，可以进一步地简化 RESTful service 和 client 开发。尽管相对年轻，它已经是一个产品级的 RESTful service 和 client 框架。与Struts类似，它同样可以和hibernate,spring框架整合。

jersey1.X使用的是sun的com.sun.jersey

jersey2.X使用的是glassfish的org.glassfish.jersey

Jersey与JAX-RS的关系：

Jersey是一个框架，实现了restful风格； JAX-RS也实现了restful风格。那么Jersey与JAX-RS是什么关系呢？我们可以这样理解：JAX-RS是JAVA自己的一个小的框架，实现了restful风格，只不过功能不是很强大；而Jersey呢，它是一个比较成熟的restful框架了，它在设计的时候，是基于JAX-RS的，它使用了java的JAX-RS的一些注解，当然了，他也有自己的特有注解，以及其他更强大的功能。

如果你更喜欢REST端点的JAX-RS编程模型，则可以使用可用的实现之一，而不是Spring MVC。Jersey和Apache CXF开箱即用就可以很好地工作。CXF要求你在应用程序上下文中将其Servlet或过滤器注册为@Bean。Jersey原生支持Spring，所以我们在Spring Boot中也为它提供了自动配置支持，还有一个starter。

要开始使用Jersey，需要把
spring-boot-starter-jersey作为依赖，然后需要一个ResourceConfig类型的@Bean，用来注册所有端点，如下面的例子所示:

示例：

@Component
public class MyJerseyConfig extends ResourceConfig {
  public MyJerseyConfig() {
    register(MyEndpoint.class);
  }
}

Jersey对扫描可执行档案的支持相当有限。例如，当运行一个可执行的war文件时，它不能扫描在完全可执行的jar文件或WEB-INF/classes中找到的包中的端点。为了避免这种限制，不应该使用packages方法，而应该使用register方法单独注册端点，如上例所示。

对于更高级的定制，你还可以注册任意数量实现了ResourceConfigCustomizer的bean。所有注册的Endpoint都应该是带有HTTP资源注解的@Components (@GET等)，如下面的例子所示:

@Component
@Path("/hello")
public class MyEndpoint {
  @GET
  public String message() {
    return "Hello";
  }
}

JAX-RS注解

一、@Path

一个Java类要能够处理REST请求，则这个类必须至少添加一个@Path("/")的注解；对于方法，这个注解是可选的，如果不添加，则继承类的定义。

@Path里的值可以是一个复杂的表达式，例如@Path("/{id}") ，其中 {id}表达式表示一个路径请求的一部分。
@Path也支持正则表达式，例如： @Path("{id: \d+}") ，其中 \d+ 表示一个数字。

二、@Method

一个方法上只有添加了某个Http Method的注解，例如@GET，才会生效。
对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个：

GET（SELECT）：从服务器取出资源（一项或多项）

POST（CREATE）：在服务器新建一个资源

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）

PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）

DELETE（DELETE）：从服务器删除资源

还有两个不常用的Method。

HEAD：获取资源的元数据

OPTIONS：一般由浏览器自动发起，用于描述目标资源的通信选项。

下面是一些例子：

GET /uses：列出所有用户

POST /users：新建用户

GET /users/ID：获取指定id用户的信息

PUT /users/ID：更新指定id用户的信息

PATCH /users/ID：更新指定id用户的信息

DELETE /users/ID：删除指定id用户

GET /users/ID/addresses：列出指定id用户的所有住址信息

DELETE /users/ID/addresses/ID：删除指定id用户下的指定地址id信息

三：Accept和Content-Type的区别

Accept就表示接口要返回给客户端的数据格式，

Content-Type表示客户端发送给服务器端的数据格式。

四：@Produces

定义资源类或
javax.ws.rs.ext.MessageBodyWriter的方法可以生成的媒体类型。如果没有指定，那么容器将假定可以生成任何类型。方法级注释覆盖类级注释。容器负责确保调用的方法能够生成HTTP请求中请求的一种媒体类型。如果没有这样的方法可用，容器必须以RFC 2616指定的HTTP“406 Not accepted”作为响应。

有几种格式如下：

@Produces("text/plain") 文本类型
@Produces("text/html") Html类型
@Produces({"Application/xml"}) Xml类型
@Produces({ "application/json"}) Json类型

可以一次注解两种或多种的MIME类型，格式如：{"application/xml", "application/json"}这表示两者都可以使用，但是选择的时候一般会选择前者，即application/xml,因为它第一次出现。

五：@Consumes

定义资源类或
javax.ws.rs.ext.MessageBodyReader的方法可以接受的媒体类型。如果没有指定，容器将假定任何媒体类型都是可接受的。方法级注释覆盖类级注释。容器负责确保所调用的方法能够使用HTTP请求实体的媒体类型。如果没有这样的方法可用，容器必须按照RFC 2616的规定，以HTTP“415 Unsupported Media Type”作为响应。

六：@QueryParam与@PathParam区别

@QueryParam：指定的是URL中的参数是以键值对的形式出现的,而在程序中

@QueryParam("id") Integer id获取请求参数id

如：URL输入为:/api/users?id=1

@PathParam：参数作为路径的一部分

如： /api/users/1

Jersey详细配置

在SpringBoot中引入如下依赖

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-jersey</artifactId>
</dependency>

引入上面的依赖后，接下来我们只需要定义继承ResourceConfig类型的Bean即可。Jersey的自动配置其中有一个条件就是当前的CLASSPATH中有ResourceConfig类型的Bean才生效，如下：

@Configuration(proxyBeanMethods = false)
@ConditionalOnBean(type = "org.glassfish.jersey.server.ResourceConfig")
@EnableConfigurationProperties(JerseyProperties.class)
public class JerseyAutoConfiguration implements ServletContextAware {
}

其中@ConditionalOnBean条件限制了只有当前容器中有ResourceConfig类型的Bean该自动配置才会生效。

注册继承ResourceConfig后请求又是如何被匹配的？

当上面的自动配置生效后，默认情况下会注册一个Servlet：

public class JerseyAutoConfiguration implements ServletContextAware {
  @Bean
  @ConditionalOnMissingBean
  public JerseyApplicationPath jerseyApplicationPath() {
    return new DefaultJerseyApplicationPath(this.jersey.getApplicationPath(), this.config);
  }
  @Bean
  @ConditionalOnMissingBean(name = "jerseyFilterRegistration")
  @ConditionalOnProperty(prefix = "spring.jersey", name = "type", havingValue = "filter")
  public FilterRegistrationBean<ServletContainer> jerseyFilterRegistration(JerseyApplicationPath applicationPath) {
    FilterRegistrationBean<ServletContainer> registration = new FilterRegistrationBean<>();
    registration.setFilter(new ServletContainer(this.config));
    // ...
    return registration;
  }
  @Bean
  @ConditionalOnMissingBean(name = "jerseyServletRegistration")
  @ConditionalOnProperty(prefix = "spring.jersey", name = "type", havingValue = "servlet", matchIfMissing = true)
  public ServletRegistrationBean<ServletContainer> jerseyServletRegistration(JerseyApplicationPath applicationPath) {
    ServletRegistrationBean<ServletContainer> registration = new ServletRegistrationBean<>(
      new ServletContainer(this.config), applicationPath.getUrlMapping());
    addInitParameters(registration);
    registration.setName(getServletRegistrationName());
    registration.setLoadOnStartup(this.jersey.getServlet().getLoadOnStartup());
    return registration;
  }
}

上面列出了Filter及Servlet，根据上面的配置知道，在没有手动在配置文件中设置spring.jersey.type=filter，那么默认就是servlet生效。

向容器注册了ServletContainer Servlet程序，该Servlet程序传入了自定义的ResourceConfig及默认的该Servlet请求Mapping地址默认是/*。

ServletContainer

该Servlet传入了ResourceConfig：

public class JerseyAutoConfiguration implements ServletContextAware {
  // 通过构造函数注入ResourceConfig类型的Bean
  private final ResourceConfig config;
	public JerseyAutoConfiguration(JerseyProperties jersey, ResourceConfig config,
    ObjectProvider<ResourceConfigCustomizer> customizers) {
    this.jersey = jersey;
    this.config = config;
    customizers.orderedStream().forEach((customizer) -> customizer.customize(this.config));
  }
}

个性化配置ResourceConfig

要想个性化定制配置，可以注册任意数量的实现ResourceConfigCustomizer的bean。

@Component
public class CustomResourceConfigCustomizer implements ResourceConfigCustomizer {

  @Override
  public void customize(ResourceConfig config) {
    // 个性化定制配置
  }

}

配置应用请求路径

@Component
// 添加此注解所有的api接口都需要添加/api前缀
@ApplicationPath("/api")
public class JerseyConfig extends ResourceConfig {
}

配置文件方式

spring:
  jersey:
    type: servlet
    # 该配置会覆盖@ApplicationPath
    application-path: /api-a

示例：

@Component
@Path("/users")
public class UserEndpoint {

  @Path("/{id}")
  @GET
  @Produces({"application/json"})
  public User queryUser(@PathParam("id") Integer id) {
    return new User(id, "姓名 - " + id, 6 + id) ;
  }
  
}

完毕！！！