5.4. JAX-RS 和 RESTEasy 应用更改

拦截器和 MessageBody 类

JSR 311：JAX-RS：RESTful Web 服务的 Java™ API 没有包含拦截器框架，因此 RESTEasy 2 提供一个。JSR 339：JAX-RS 2.0：RESTful Web 服务的 Java API 引入了官方拦截器和过滤框架，因此 RESTEasy 2 中包含的拦截器框架现已弃用，并且被 RESTEasy 3.x 中的 JAX-RS 兼容拦截器功能所取代。相关的接口在 jaxrs-api 模块的 javax.ws.rs.ext 软件包中定义。

如需有关拦截器的更多信息，请参阅用于 JBoss EAP 开发 Web Services 应用中的 RESTEasy 拦截器。

如需有关新的替换 API 的更多信息，请参阅 RESTEasy JAX-RS 3.9.0.Final API。

客户端 API

resteasy-jaxrs 中的 RESTEasy 客户端框架被 JBoss EAP 7.0 中的遵循 JAX-RS 2.0 的 resteasy-client 模块替代。因此，一些 RESTEasy 客户端 API 类和方法已弃用。

StringConverter

org.jboss.resteasy.spi.StringConverter 类在 RESTEasy 3.x 中被弃用。可以使用 JAX-RS jax.ws.rs.ext.ParamConverterProvider 类来替换此功能。

ResteasyProviderFactory 添加方法

大多数 org.jboss.resteasy.spi.ResteasyProviderFactory add() 方法已被删除或在 RESTEasy 3.0 中受到保护。例如，addBuiltInMessageBodyReader() 和 addBuiltInMessageBodyWriter() 方法已被删除，并且 addMessageBodyReader() 和 addMessageBodyWriter() 方法受保护。

您现在应使用 registerProvider（） 和 registerProviderInstance（） 方法。

从 RESTEasy 3 中删除额外的类

@org.jboss.resteasy.annotations.cache.ServerCached 注释指定对 JAX-RS 方法的响应应缓存在服务器上，并且必须从 RESTEasy 3 中删除。

SignedInput 和 SignedOuput

安全过滤器

@RolesAllowed、@PermitAll 和 @DenyAll 的安全过滤器现在返回 "403 Forbidden" 而不是 "401 Unauthorized"。

客户端过滤器

从 RESTEasy 3.0 之前，从版本使用 RESTEasy 客户端 API 时，在 JAX-RS 2.0 中引入的客户端侧过滤器不会绑定并运行。

异步 HTTP 支持

由于 JAX-RS 2.0 规范添加了利用 @Suspended 注释和 AsynResponse 接口的异步 HTTP 支持，因此用于异步 HTTP 的 RESTEasy 专有 API 已被弃用，并可能在以后的 RESTEasy 发行版中移除。异步 Tomcat 和异步 JBoss Web 模块也已从服务器安装中删除。如果您不使用 Servlet 3.0 容器或更高，则异步 HTTP 服务器端处理将模拟，并在同一个请求线程中异步运行。

服务器端缓存

服务器端缓存设置已更改。如需更多信息，请参阅 RESTEasy 文档。

YAML 供应商设置更改

在以前的 JBoss EAP 版本中，RESTEasy YAML 供应商设置被默认启用。这在 JBoss EAP 7 中有所改变。现在默认禁用 YAML 供应商。由于 RESTEasy 用于 unmarshalling 的 SnakeYAML 库中的安全问题，它不被支持，因此必须在应用中明确启用。有关如何在应用程序中启用 YAML 供应商并添加 Maven 依赖项的信息，请参阅 为 JBoss EAP 开发 Web Services Applications 中的 YAML 供应商。

Content-Type Header 中的默认 Charset UTF-8

自 JBoss EAP 7.1 起，resteasy.add.charset 参数默认设置为 true。当资源方法返回一个 text/* 或 application/xml* 媒介类型且没有明确的字符集时，如果您不希望 RESTEasy 将 charset=UTF-8 添加到返回的 content-type 头时，可以将 resteasy.add.charset 参数设置为 false。

如需有关文本媒体类型和字符集的更多信息，请参阅为 JBoss EAP 开发 Web 服务应用中的文本介质类型和字符集。

SerializableProvider

从不受信任的源中反序列化 Java 对象是不安全的。因此，在 JBoss EAP 7 中，默认禁用 org.jboss.resteasy.plugins.providers.SerializableProvider 类，因此不建议使用这个提供程序。

将请求与资源方法匹配

在 RESTEasy 3 中，对匹配的规则实施进行了改进和修正，如 JAX-RS 规范中所定义。特别是，如何对子资源方法上的模糊的 URI 以及处理子资源松cator 时进行一个更改。

在 RESTEasy 2 中，即使存在具有相同 URI 的另一个子资源，也会让子资源 locator 成功执行。这个行为根据规格不正确。

在 RESTEasy 3 中，当子资源和子资源松cator 存在模糊的 URI 时，调用子资源将成功；但是，调用子资源 locator 将导致 HTTP 状态 405 Method Not Allowed 错误。

以下示例包含子资源方法和子资源 locator 上的模糊 @Path 注释。注意 URI 到端点（ anotherResource 和 anotherResourceLocator ）是相同的。两个端点的区别在于 anotherResource 方法与 REST 动词 POST 关联。anotherResourceLocator 方法不与任何 REST 动词关联。根据规范，将始终选择具有 REST 动词的端点（本例中为 anotherResource 方法）。

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

@Path("myResource")
public class ExampleSubResources {
    @POST
    @Path("items")
    @Produces("text/plain")
    public Response anotherResource(String text) {
        return Response.ok("ok").build();
    }

    @Path("items")
    @Produces("text/plain")
    public SubResource anotherResourceLocator() {
        return new SubResource();
    }
}

资源方法算法切换

在 3.0.25 之前的 RESTEasy 3.0.x 版本中使用的资源方法匹配算法中发现了一个错误，即 RESTEasy 在响应请求时返回太多的资源类型。

匹配算法有三个阶段：

根据 JAX-RS 2.0 规范，在对潜在资源方法集合进行排序后，仅将最大元素传递给第 3 步。但是，在 RESTEasy 3.0.25 之前的 RESTEasy 3.0.x 实施将所有方法传递给第 3 步。JBoss EAP 7.1.0 中包含的 RESTEasy 3.0.24 表现出了这种行为不正确。

RESTEasy 3.0.25 （包含在 JBoss EAP 7.1.1 中）提供了相应的修复，以限制传递到第 3 步要符合 JAX-RS 2.0 规范的方法。由于 looser 的行为可能更倾向于，因此 RESTEasy 3.0.25 还引入了 context-param 配置选项 resteasy.loose.step2.request.match（默认为 false ），它可以配置为启用旧行为。

如果您将 JBoss EAP 服务器从 7.1.0 升级到 7.1.1，并且您希望保留旧行为，并将所有潜在的资源方法传递给第 3 步，将 resteasy.loose.step2.request.matching 选项设置为 true。

在 JAX-RS 2.1 规范中更改了匹配的算法，将所有匹配的资源方法传递给第 3 步。RESTEasy 3.9.0 包含在 JBoss EAP 7.4 中，提供 jaxrs.2.0.request.matching 选项，以保留 JAX-RS 2.0 规范中定义的更严格的行为。

如果您将应用程序从 JBoss EAP 从 7.1.0 迁移到 7.2.x，则不应在资源方法匹配算法的行为中看到更改。如果您将应用程序从 JBoss EAP 从 7.1.1 迁移到 7.2.x 或更高版本，并希望保留 JAX-RS 2.0 规范中定义的更严格的行为，将 jaxrs.2.0.request.matching 选项设置为 true。

SPI Exceptions

所有 SPI 失败异常已被弃用，且不再在内部使用。它们已被对应的 JAX-RS 例外替代。

InjectoronnectionFactoryy 和 Registry

InjectorFactory 和 Registry SPI 已更改。如果使用 RESTEasy 作为文档和支持，这不应有问题。

JBoss EAP 中包含的 Jackson 版本发生了变化。先前版本的 JBoss EAP 包括 Jackson 1.9.9。JBoss EAP 7 现在包含 Jackson 2.6.3 或更高版本。因此，Jackson 供应商已从 resteasy-jackson-provider 改为 resteasy-jackson2-provider。

升级到 resteasy-jackson2-provider 需要一些软件包更改。例如，Jackson 注解软件包已从 org.codehaus.jackson.annotate 改为 com.fasterxml.jackson.annotation。

要切换应用程序以使用 JBoss EAP 之前版本中包含的默认供应商，请参阅在为 JBoss EAP 开发 Web Services Applications 中 切换 Default Jackson Provider。

Spring 4.0 框架引入了对 Java 8 的支持。如果您计划使用 RESTEasy 3.x 与 Spring 集成，请确保将 4.2.x 指定为部署中最低 Spring 版本，因为这是 JBoss EAP 7 支持的最早的稳定版本。

RESTEasy Jettison JSON 提供程序在 JBoss EAP 7 中已弃用，且不再默认添加到部署中。建议您切换到推荐的 RESTEasy Jackson 供应商。如果您希望继续使用 Jettison 提供程序，您必须在 jboss-deployment-descriptor.xml 文件中定义一个明确的依赖关系，如下例所示。

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
  <deployment>
    <exclusions>
      <module name="org.jboss.resteasy.resteasy-jackson2-provider"/>
      <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
    </exclusions>
    <dependencies>
      <module name="org.jboss.resteasy.resteasy-jettison-provider" services="import"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

有关如何定义显式依赖项的更多信息，请参阅 JBoss EAP 开发指南中为部署添加解释模块依赖项。

JBoss EAP 7.3 支持 MicroProfile REST 客户端的版本 1.3.x。如果您使用旧版 MicroProfile REST 客户端，则需要在代码中进行一些更新。

org.jboss.resteasy.client.microprofile.MicroprofileClientBuilderResolver 类被 org.eclipse.microprofile.rest.client.RestClientBuilder 替代。例如：

@Path("resource")
public interface TestResourceIntf {

   @Path("test")
   @GET
   public String test();
}

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
String s = service.test();

@Path("resource")
public interface TestResourceIntf {

   @Path("test")
   @GET
   public String test();
}

TestResourceIntf service = RestClientBuilder.newBuilder()
                              .baseUrl("http://localhost:8081/")
                              .build(TestResourceIntf.class);
String s = service.test();

有关 MicroProfile REST 客户端的更多信息，请参阅 JBoss EAP 开发 Web 服务应用 指南中的 MicroProfile REST 客户端。

MicroProfile 配置是开发人员用来将应用和微服务配置为在多个环境中运行的规范名称，而无需修改或重新打包这些应用。在以前的版本中，MicroProfile Config 作为技术预览提供 JBoss EAP，但自此后已被删除。MicroProfile 配置现在仅适用于 JBoss EAP XP。