Jakarta RESTful Web Services

这是 2.1 版本的最终发布。此版本的缺陷跟踪系统可在

https://github.com/jax-rs/api/issues

查阅。相应的 Javadocs 在线地址为：

https://jax-rs.github.io/apidocs/2.1

参考实现可从以下网址获取：

https://jersey.github.io

专家组寻求社区对本规范任何方面的反馈，请将意见发送至：

jaxrs-spec@javaee.groups.io

API 的目标如下：

以下是非目标：

本文档中的关键字 `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', `RECOMMENDED', `MAY', 和 `OPTIONAL' 的解释应遵循 RFC 2119[10] 的描述。

Java 代码和示例数据片段的格式如图 [1.1] 所示。

一般形式为 `http://example.org/…​' 和 `http://example.com/…​' 的 URI 代表应用程序或上下文相关的 URI。

本文档的所有部分均具有规范性，但示例、注释和明确标记为“非规范性”的部分除外。非规范性注释格式如下：

注意： 这是一个注释。

本规范是作为 JSR 370 在 Java Community Process 下开发的。它是 JSR 370 专家组组员协作工作的成果。以下是当前的专家组组员：

 — Sergey Beryozkin (Talend SA)

 — Adam Bien (个人成员)

 — Sebastian Dashner (个人成员)

 — Markus Karg (个人成员)

 — Casey Lee (Vision Service Plan)

 — Marcos Luna (个人成员)

 — Andy McCright (IBM)

 — Julian Reschke (个人成员)

 — Alessio Soldano (Red Hat)

以下是 JSR 339 专家组的前组员：

 — Jan Algermussen (个人成员)

 — Florent Beniot (OW2)

 — Sergey Beryozkin (Talend SA)

 — Adam Bien (个人成员)

 — Bill Burke (Red Hat)

 — Clinton L. Combs (个人成员)

 — Jian Wu Dai (IBM)

 — Bill De Hora (个人成员)

 — Markus Karg (个人成员)

 — Sastry Malladi (eBay, Inc)

 — Julian Reschke (个人成员)

 — Guilherme de Azevedo Silveira (个人成员)

 — Synodinos, Dionysios G. (个人成员)

JAX-RS 1.X 是作为 JSR 311 在 Java Community Process 下开发的。以下是 JSR 311 专家组的组员：

 — Heiko Braun (Red Hat Middleware LLC)

 — Larry Cable (BEA Systems)

 — Roy Fielding (Day Software, Inc.)

 — Harpreet Geekee (Nortel)

 — Nickolas Grabovas (个人成员)

 — Mark Hansen (个人成员)

 — John Harby (个人成员)

 — Hao He (个人成员)

 — Ryan Heaton (个人成员)

 — David Hensley (个人成员)

 — Stephan Koops (个人成员)

 — Changshin Lee (NCsoft Corporation)

 — Francois Leygues (Alcatel-Lucent)

 — Jerome Louvel (个人成员)

 — Hamid Ben Malek (Fujitsu Limited)

 — Ryan J. McDonough (个人成员)

 — Felix Meschberger (Day Software, Inc.)

 — David Orchard (BEA Systems)

 — Dhanji R. Prasanna (个人成员)

 — Julian Reschke (个人成员)

 — Jan Schulz-Hofen (个人成员)

 — Joel Smith (IBM)

 — Stefan Tilkov (innoQ Deutschland GmbH)

在此 JSR 开发过程中，我们得到了许多个人的大力贡献和建议。特别感谢 Marek Potociar 和 Michal Gajdos。还有 Gunnar Morling、Ondrej Mihalyi、Arjan Tijms、Guillermo Gonzales de Aguero、Christian Kaltepoth 以及许多许多其他人。最后但同样重要的是，感谢 JSR 370 专家组的所有贡献。

在 JSR 339 开发过程中，我们收到了许多出色的建议。特别感谢 Oracle 的 Martin Matula、Gerard Davison、Jakub Podlesak 和 Pavel Bucek，以及 Red Hat 的 Pete Muir 和 Emmanuel Bernard。还要感谢 Gunnar Morling 和 Ron Sigal (Red Hat) 关于如何改进资源验证的建议，以及 Mattias Arthursson 关于超媒体的见解。

在 JSR 311 开发过程中，我们在 JSR 和 Jersey (RI) 邮件列表中收到了许多出色的建议，特别感谢 James Manger (Telstra) 和 Reto Bachmann-Gmür (Trialox) 的贡献。以下个人（当时均在 Sun Microsystems）也做出了宝贵的技术贡献：Roberto Chinnici、Dianne Jiao (TCK)、Ron Monzillo、Rajiv Mordani、Eduardo Pelegri-Llopart、Jakub Podlesak (RI) 和 Bill Shannon。

GenericEntity 类受到 Google Guice TypeLiteral 类的启发。感谢 Bob Lee 和 Google 将此类捐赠给 JAX-RS。

构成 JAX-RS 应用的资源和提供者通过应用程序提供的 Application 子类进行配置。实现 MAY 提供查找资源类和提供者的替代机制（例如，运行时类扫描），但 Application 的使用是唯一的便携式配置方式。

具体的应用要求在此规范和 JAX-RS Javadocs 中详细说明。实现 MAY 执行超出本文档所述的验证步骤。

JAX-RS 实现 MAY 在检测到两个或多个资源可能导致执行 请求匹配 中描述的算法时出现歧义时报告错误条件。例如，如果同一资源类中的两个资源方法在对该部分描述的算法的所有相关注解中具有相同的（甚至重叠的）值。确切的验证步骤集以及错误报告机制取决于实现。

应用程序的发布方式因应用程序是在 Java SE 环境中运行还是在容器中运行而异。本节介绍替代的发布方式。

资源类是使用 JAX-RS 注解来实现相应 Web 资源的 Java 类。资源类是 POJO，至少有一个方法被注解为 @Path 或请求方法设计符。

当实例化资源类时，被注解为以下任一注解的字段和 Bean 属性的值将根据注解的语义进行设置：

由于注入发生在对象创建时，因此这些注解（@Context 除外）在资源类字段和 Bean 属性上的使用仅支持默认的每个请求资源类生命周期。如果资源类的生命周期不同，实现应警告在资源类字段或 Bean 属性上使用这些注解。

JAX-RS 实现仅需要设置其运行时创建的实例的注解字段和 Bean 属性值。由子资源定位符（参见 子资源）返回的对象期望由其创建者初始化。

每个上述注解的有效参数类型列在相应的 Javadoc 中，但通常（不包括 @Context）支持以下类型：

DefaultValue 注解可用于为上述某些类型提供默认值，有关用法详细信息以及在缺少此注解和请求数据的情况下生成值的规则，请参阅 DefaultValue 的 Javadoc。Encoded 注解可用于禁用 @MatrixParam、@QueryParam 和 @PathParam 注解的字段和属性的自动 URI 解码。

使用上述 5 个步骤之一在构造字段或属性值期间抛出的 WebApplicationException 将被直接处理，如 异常 中所述。在构造字段或属性值期间抛出的其他异常（使用上述 5 个步骤之一）将被视为客户端错误：如果字段或属性被注解为 @MatrixParam、@QueryParam 或 @PathParam ，则实现必须生成一个 NotFoundException（404 状态）实例来包装抛出的异常，并且没有实体；如果字段或属性被注解为 @HeaderParam 或 @CookieParam ，则实现必须生成一个 BadRequestException（400 状态）实例来包装抛出的异常，并且没有实体。异常必须按照 异常 中的描述进行处理。

资源方法是资源类中被请求方法设计符注解的方法。它们用于处理请求，并且必须符合本节描述的某些限制。

请求方法设计符是使用 @HttpMethod 注解的运行时注解。JAX-RS 为常见的 HTTP 方法定义了一组请求方法设计符：@GET、@POST、@PUT、@DELETE、@PATCH、@HEAD 和 @OPTIONS。用户可以定义自己的自定义请求方法设计符，包括常见 HTTP 方法的替代设计符。

根资源类通过 @Path 注解锚定在 URI 空间中。注解的值是一个相对 URI 路径模板，其基础 URI 由部署上下文和应用程序路径的组合提供（请参阅 @ApplicationPath 注解）。

URI 路径模板是一个带有零个或多个嵌入式参数的字符串，当所有参数都替换为值时，它是一个有效的 URI[5] 路径。@Path 注解的 Javadoc 描述了它们的语法。例如：

在上面的示例中，Widget 资源类由相对 URI 路径 widgets/xxx 标识，其中 xxx 是 id 参数的值。

注意： 由于 \{ 和 } 不是 URI[5] 的保留或未保留部分的组成部分，因此它们不会出现在有效的 URI 中。

注解的值会自动编码，例如，以下两行是等效的：

模板参数可以可选地指定用于匹配其值的正则表达式。默认值匹配任何文本并终止于路径段的末尾，但其他值可以用于改变此行为，例如：

在上面的示例中，Widget 资源类将匹配任何以 widgets 开头且至少包含一个额外路径段的请求；path 参数的值将是 widgets 之后的请求路径。例如，给定请求路径 widgets/small/a，path 的值将是 small/a。

URI 路径参数的值可以通过 @PathParam 在字段、属性或方法参数上进行注入。请注意，如果 URI 模板用于方法，则在字段或属性中注入的路径参数可能不可用（设置为 null）。以下示例说明了这种情况：

应用程序类可以使用 @Consumes 和 @Produces 注解分别声明支持的请求和响应媒体类型。这些注解可以应用于资源方法、资源类或实体提供者（参见 声明媒体类型能力）。在资源方法上使用这些注解会覆盖资源类或实体提供者上的任何注解，用于方法参数或返回类型。如果缺少这些注解中的任何一个，则假定支持任何媒体类型（/*）。

以下示例说明了这些注解的用法：

在上面：

实现不得调用其 @Produces 的有效值与请求 Accept Header 不匹配的方法。实现不得调用其 @Consumes 的有效值与请求 Content-Type Header 不匹配的方法。

在接受多种媒体类型时，客户端可以通过使用称为 q 参数的相对质量因子来指示偏好。q 参数的值，或 q-value，用于对接受的类型集进行排序。例如，客户端可以通过 1 的相对质量因子指示对 application/widgets+xml 的偏好，而对 application/xml 则为 0.8。Q-value 的范围从 0（不受欢迎）到 1（非常理想），省略时默认为 1。与 WidgetsResource 类匹配的 GET 请求，其 accept header 为 text/html; q=1, application/widgets+xml; q=0.8，将根据 q 的值调用 getAsHtml 方法而不是 getAsXML。

服务器也可以使用 qs 参数指示媒体类型偏好；仅当客户端接受多种媒体类型且 q-value 相同时，才会检查服务器偏好。考虑以下示例：

假设客户端发出带有 accept header application/*; q=0.5, text/html 的 GET 请求。根据此请求，服务器确定 application/xml 和 application/json 都被客户端同样偏好，q-value 为 0.5。通过在 @Produces 注解中指定服务器相对质量因子，可以控制选择哪个响应媒体类型：

在此示例中，更新了 @Produces 的值，并且响应带有包含 application/*; q=0.5 的 accept header 的 GET 请求时，JAX-RS 实现必须选择媒体类型 application/xml，因为其 qs-value 更高。请注意，qs-value 与 q-value 一样，是相对的，因此仅能与同一 @Produces 注解实例中的其他 qs-value 进行比较。有关更多信息，请参阅 确定 MediaType 的响应。

JAX-RS 注解可以用于超类或已实现接口的方法和方法参数。只要方法及其参数本身没有 JAX-RS 注解，这些注解就会被相应的子类或实现类方法继承。超类上的注解优先于已实现接口上的注解。在多个已实现接口中定义的冲突注解的优先级是实现特定的。请注意，不支持类或接口注解的继承。

如果子类或实现方法具有任何 JAX-RS 注解，则所有超类或接口方法上的注解都将被忽略。例如：

在上面，ActivityLog.getFeed 从接口继承了 @GET 和 @Produces 注解。相反：

在上面，ReadOnlyAtomFeed.getFeed 上的 @GET 注解不会被 Activity-Log.getFeed 继承，并且由于它重新定义了 @Produces 注解，因此需要自己的请求方法设计符。

为了与其他 Jakarta EE 规范保持一致，建议始终重复注解而不是依赖于注解继承。

本节描述了请求如何匹配到资源类和方法。实现不要求使用编写的算法，但必须产生与算法产生的结果等效的结果。

在许多情况下，无法静态确定响应的媒体类型。以下算法用于在运行时确定响应媒体类型 \(M_{\mbox{selected}}\)：

请注意，上述设置在无法确定具体类型时，响应的默认媒体类型为 application/octet-stream 。建议 MessageBodyWriter 实现通过 @Produces 指定至少一种具体类型。

默认情况下，每个提供者类的一个实例为每个 JAX-RS 应用程序实例化。首先调用构造函数（参见 构造函数），然后注入任何请求的依赖项（参见 上下文 章节），然后可以多次（同时）调用适当的提供者方法，最后对象可供垃圾回收。提供者 描述了提供者如何通过依赖注入访问其他提供者。

实现 MAY 提供其他提供者生命周期，指定这些的机制不在本规范范围内。例如，基于控制反转框架的实现可以支持该框架提供的所有生命周期选项。

实体提供者提供表示与其关联的 Java 类型之间的映射服务。实体提供者有两种形式：MessageBodyReader 和 MessageBodyWriter ，如下所述。

上下文提供程序为资源类和其他提供程序提供上下文。上下文提供程序类实现 ContextResolver<T> 接口，并可能使用 @Provider 注解以实现自动发现。例如，希望为默认 JAXB 实体提供程序提供自定义 JAXBContext 的应用程序将提供一个实现 ContextResolver<JAXBContext> 的类。

上下文提供程序可以从 getContext 方法返回 null，如果它们不希望为特定 Java 类型提供其上下文。例如，JAXB 上下文提供程序可能只想为某些 JAXB 类提供上下文。上下文提供程序还可以管理同一类型的多个上下文，这些上下文以不同的 Java 类型为键。

异常映射提供程序将已检查异常或运行时异常映射到 Response 实例。异常映射提供程序实现 ExceptionMapper<T> 接口，并可能使用 @Provider 注解以实现自动发现。

当资源类或提供程序方法抛出异常，并且存在该异常的异常映射提供程序时，将使用匹配的提供程序来获取 Response 实例。生成的 Response 将像 Web 资源方法返回 Response 一样进行处理（参见 返回类型）。特别是，映射的 Response 必须使用 Filters and Interceptors 章节中定义的 ContainerResponse 过滤器链进行处理。

选择异常映射提供程序来映射异常时，实现必须使用其通用类型是异常的最近超类的提供程序。如果两个或多个异常提供程序适用，则必须按照 优先级 部分所述选择优先级最高的那个。

为避免潜在的无限循环，在处理请求及其相应响应期间必须使用单个异常映射器。JAX-RS 实现不得尝试映射在处理先前从异常映射的响应时抛出的异常。相反，此异常必须按照 异常 部分的步骤 3 和 4 的描述进行处理。

请注意，异常映射提供程序 **不** 支持作为客户端 API 的一部分。

异常处理根据提供程序是客户端运行时还是服务器运行时的组成部分而有所不同。这将在接下来的两个部分中介绍。

需要一个 Client 实例才能使用 Client API 访问 Web 资源。可以通过调用 ClientBuilder 上的 newClient 来获取 Client 的默认实例。Client 实例可以使用从 Configurable 继承的方法进行配置，如下所示

有关提供程序的信息，请参阅 Providers 章节。属性只是名称-值对，其中值是任意对象。功能也是提供程序，并且必须实现 Feature 接口；它们对于将一组逻辑上相关的属性和提供程序（包括其他功能）分组在一起并作为单元启用很有用。

可以使用流畅的 API 访问 Web 资源，其中方法调用被链接起来以构建并最终提交 HTTP 请求。以下示例获取由 http://example.org/hello 标识的资源的 text/plain 表示形式

从概念上讲，提交请求所需的步骤如下：(i) 获取 Client 实例 (ii) 创建 WebTarget (iii) 从 WebTarget 创建请求，以及 (iv) 提交请求或获取准备好的 Invocation 以供稍后提交。有关使用 Invocation 的更多信息，请参阅 [invocations] 部分。

方法链接不限于上面显示的示例。请求可以通过设置标头、Cookie、查询参数等进一步指定。例如

有关 javax.ws.rs.client 包中类的更多信息，请参阅 Javadoc。

使用 WebTarget 的好处在构建复杂 URI 时显而易见，例如通过向基 URI 添加其他路径段或模板。以下示例重点介绍了这些情况

请注意 {whom} URI 模板参数的使用。上面的示例获取由 http://example.org/hello/world 标识的资源的表示。

WebTarget 实例对于它们的 URI（或 URI 模板）是 **不可变** 的：用于指定其他路径段和参数的方法会返回一个新的 WebTarget 实例。但是，WebTarget 实例对于它们的配置是 **可变** 的。因此，配置 WebTarget 不会创建新实例。

在此示例中，创建了两个 WebTarget 实例。实例 hello 继承了 base 的配置，并由注册 MyProvider.class 进一步配置。请注意，对 hello 配置的更改不会影响 base，即继承执行配置的 **深拷贝**。有关可配置类型的更多信息，请参阅 [configurable_types] 部分。

对请求的响应不限于 Response 类型。以下示例将客户编号 123 的状态升级为“金卡会员”，首先获取 Customer 类型实体，然后将该实体发布到不同的 URI

请注意在调用 post 时使用了 xml() 的 **变体**。javax.ws.rs.client.Entity 类为 JAX-RS 应用程序中最常用的媒体类型定义了变体。

在上面的示例中，就像在服务器 API 中一样，JAX-RS 实现被要求使用实体提供程序将 application/xml 类型的表示映射到 Customer 实例，反之亦然。有关所有 JAX-RS 实现必须支持的实体提供程序列表，请参阅 标准实体提供程序。

调用是已准备好并可执行的请求。调用提供了一个 **通用接口**，它允许创建者和提交者之间进行关注点分离。特别是，提交者不需要知道调用是如何准备的，只需要知道它应该如何执行：即同步执行或异步执行。

让我们来看以下示例 ^[11]

Collections.transform(invs, new F<Invocation, Response>() @Override public Response apply(Invocation inv) return inv.invoke(); );

在此示例中，创建了两个调用并由创建者存储在一个集合中。然后提交者遍历集合，应用一个将 Invocation 映射到 Response 的转换。该映射调用 Invocation.invoke 来同步执行调用；通过调用 Invocation.submit 也支持异步执行。有关异步调用的更多信息，请参阅 Asynchronous Processing 章节。

以下 Client API 类型是可配置的：Client、ClientBuilder 和 WebTarget。配置方法是从所有这些类实现的 Configurable 接口继承的。此接口支持配置

上述任何类型的实例上定义的配置都将由从它创建的其他实例继承。例如，从 Client 创建的 WebTarget 实例将继承 Client 的配置。但是，对 WebTarget 实例的任何其他更改都不会影响 Client 的配置，反之亦然。因此，一旦继承了配置，它就会从父配置中分离（深拷贝），父配置和子配置的更改对彼此不可见。

Client API 在 Client API 中引入了异步编程。JAX-RS 中的异步编程使客户端可以通过将工作推送到后台线程来解除某些线程的阻塞，这些线程可以稍后监视和可能等待（join）。这可以通过提供 InvocationCallback 实例或操作异步调用者返回的 Future<T> 类型的结果来实现，或者两者的组合。

使用 InvocationCallback 可实现更具 **响应式** 的编程风格，用户提供的代码仅在发生特定事件时激活（或响应）。回调在简单情况下效果很好，但在涉及多个事件时，源代码会更难理解。例如，当需要组合、合并或以任何方式操作异步调用时。这些类型的场景可能导致回调嵌套在其他回调中，使代码可读性大大降低——由于调用固有的嵌套，通常被称为 **“厄运金字塔”**。

为了满足提高可读性和使程序员能够更好地推理异步计算的要求，Java 8 引入了一个名为 CompletionStage 的新接口，其中包含大量用于管理异步计算的方法。

JAX-RS 2.1 定义了一种新的调用程序类型，称为 RxInvoker，以及该类型的一个默认实现 CompletionStageRxInvoker，它基于 Java 8 的 CompletionStage 类型。有一个新的 rx 方法，其用法类似于 Client API 中描述的 async。让我们来看以下示例

此示例首先创建一个 CompletionStage<String> 类型的异步计算，然后简单地等待它完成并显示其结果（技术上，在最后一行创建了一个 CompletionStage<Void> 类型的第二个计算，仅用于消耗第一个计算的结果）。

当多个异步计算对于完成一项任务是必需的时，CompletionStage 的价值变得显而易见。以下示例并行获取目的地价格和预测，并仅在满足所需条件时进行预订。

请注意，调用 thenCombine 方法时传递的 Consumer 需要每个阶段的值可用，因此只能在两个并行阶段完成后执行。

正如我们将在下一节中看到的，CompletionStage 的支持是所有 JAX-RS 实现的 **默认** 支持，但其他响应式 API 也可能作为扩展支持。

Executor 服务可用于提交异步任务以供执行。JAX-RS 应用程序可以在构建 Client 实例时指定 executor 服务。ClientBuilder 中为此目的提供了两个方法，即 executorService 和 scheduledExecutorService。

在支持 Jakarta Concurrency [13] 的环境中（例如完整的 Jakarta EE 平台产品），实现必须分别使用 ManagedExecutorService 和 ManagedScheduledExecutorService。有关 executor 服务的信息，请参阅 ClientBuilder 的 Javadoc。

实体拦截器包装在特定扩展点的方法调用。过滤器在扩展点执行代码，但不包装方法调用。过滤器有四个扩展点：ClientRequest、ClientResponse、ContainerRequest 和 ContainerResponse。实体拦截器有两个扩展点：ReadFrom 和 WriteTo。对于每个扩展点，都有一个对应的接口

**客户端** 过滤器是实现 ClientRequestFilter 或 ClientResponseFilter 或两者的类。 **容器** 过滤器是实现 ContainerRequestFilter 或 ContainerResponseFilter 或两者的类。实体拦截器是实现 ReaderInterceptor 或 WriterInterceptor 或两者的类。过滤器和实体拦截器是提供程序，因此可以使用 @Provider 注解以实现自动发现。

在 Client API 中，ClientRequestFilter 在 HTTP 请求发送到网络之前作为调用管道的一部分执行；ClientResponseFilter 在收到服务器响应后，在控制权返回到应用程序之前执行。在 Server API 中，ContainerRequestFilter 在收到来自客户端的请求时执行；ContainerResponseFilter 在 HTTP 响应发送到网络之前，作为响应管道的一部分执行。

全局绑定的（参见 全局绑定）ContainerRequestFilter 是在资源匹配后执行的容器过滤器，**除非** 它被注解了 @PreMatching。此注解在此类过滤器上的使用定义了一个新的扩展点供应用程序使用，即。某些 ContainerRequestContext 方法在此扩展点可能不可用。

实现 ReaderInterceptor 的实体拦截器包装对 MessageBodyReader 的 readFrom 方法的调用。实现 WriterInterceptor 的实体拦截器包装对 MessageBodyWriter 的 writeTo 方法的调用。JAX-RS 实现被要求在将表示形式映射到 Java 类型及反之亦然时调用已注册的拦截器。有关实体提供程序的信息，请参阅 Entity Providers。

有关客户端和服务器处理管道中过滤器和实体拦截器交互的图示，请参阅附录 Processing Pipeline。

过滤器被分组到 **过滤器链** 中。对于上一节中介绍的每个扩展点，都有一个单独的过滤器链，即：ClientRequest、ClientResponse、ContainerRequest、ContainerResponse 和 PreMatchContainerRequest。链中的过滤器根据其优先级（参见 Priorities）进行排序，并按顺序执行。

以下示例显示了一个容器日志过滤器实现：每个方法仅记录消息并返回。

ContainerRequestContext 是一个可变类，它为过滤器提供请求特定信息，例如请求 URI、消息头、消息实体或请求范围的属性。暴露的 setter 允许在请求被资源方法处理之前（对请求）进行修改。类似地，有一个对应的 ContainerResponseContext，它提供响应特定信息。

实现 ClientRequestFilter 或 ContainerRequestFilter 的请求过滤器可以通过在其相应的上下文对象中调用 abortWith(Response) 来停止其相应链的执行。如果调用此方法，JAX-RS 实现被要求中止链的执行，并将响应对象视为通过调用资源方法（Server API）或执行 HTTP 调用（Client API）生成的。例如，在缓存命中时，客户端 **缓存** 过滤器可能会调用 abortWith(Response) 来中止执行并优化网络访问。

如上所述，注解了 @PreMatching 的 ContainerRequestFilter 在接收到客户端请求时执行，但在匹配资源方法 **之前** 执行。因此，此类型的过滤器能够修改匹配算法的输入（参见 Request Matching），并因此改变其结果。以下示例使用了一个注解了 @PreMatching 的 ContainerRequestFilter，通过使用 X-HTTP-Method-Override 头在资源匹配之前覆盖 HTTP 方法来隧道化 POST 请求。

实体拦截器实现 ReaderInterceptor 或 WriterInterceptor 接口，或两者都实现。对于每种类型的实体拦截器，都存在一个 **拦截器链**。链中的实体拦截器根据其优先级（参见 Priorities）进行排序，并按顺序执行。

作为 JAX-RS 处理管道（参见附录 Processing Pipeline）的一部分，实体拦截器包装对实现 MessageBodyReader 的类的 readFrom 方法的调用以及对实现 MessageBodyWriter 的类的 writeTo 方法的调用。拦截器应显式调用上下文方法 proceed 以继续链的执行。由于其包装性质，未能调用此方法将阻止相应消息正文读取器或消息正文写入器中的被包装方法执行。

以下示例显示了一个 GZIP 实体拦截器实现，它提供解压缩和压缩功能 ^[12]。

上下文类型 ReaderInterceptorContext 和 WriterInterceptorContext 提供对相应被包装方法的参数的读写访问。在上面显示的示例中，在继续之前，输入和输出流被包装并更新在上下文对象中。JAX-RS 实现必须在调用被包装的 MessageBodyReader.readFrom 和 MessageBodyWriter.writeTo 方法时使用上下文中设置的最后参数值。

值得注意的是，直接从应用程序代码调用（例如，通过注入 Providers 实例）的 readFrom 或 writeTo **不会** 触发任何实体拦截器的执行，因为它不是正常 JAX-RS 处理管道的一部分。

默认情况下，与其他所有提供程序一样，每个过滤器或实体拦截器的单个实例都会为每个 JAX-RS 应用程序实例化。首先调用构造函数，然后注入任何请求的依赖项，然后根据需要调用相应的方法（同时）。实现可以提供除默认选项之外的替代生命周期选项。有关更多信息，请参阅 Lifecycle and Environment。

绑定是将过滤器或拦截器与资源类或方法（Server API）或调用（Client API）相关联的过程。下一节中介绍的绑定形式仅作为 Server API 的一部分受支持。有关 Client API 中的绑定的信息，请参阅 Binding in Client API。

过滤器和拦截器作为其相应链一部分的执行顺序由 [15] 中定义的 @Priority 注解控制。优先级由整数表示。扩展点 、 、 、 和 的执行链按 **升序** 排序；数字越小，优先级越高。扩展点 和 的执行链按 **降序** 排序；数字越大，优先级越高。这些规则确保响应过滤器按与请求过滤器相反的顺序执行。

JAX-RS 中的 Priorities 类定义了一组用于安全、头装饰器、解码器和编码器的内置优先级。默认绑定优先级是 javax.ws.rs.Priorities.USER。例如，身份验证过滤器的优先级可以设置为

请注意，尽管如 Binding in Client API 所解释的，注解不用于 Client API 中的绑定，但它们仍用于定义优先级。因此，如果需要与默认值不同的优先级，则必须为注册到 Client API 的过滤器或拦截器使用 @Priority 注解。

属于同一优先级类的过滤器和拦截器的执行顺序是实现依赖的。

Server API 支持使用 @HeaderParam、@QueryParam 等注解来提取请求值并将其映射到 Java 字段、属性和参数。它还支持通过非注解参数（即没有 JAX-RS 注解的参数）将请求实体正文映射到 Java 对象。有关更多信息，请参阅 Resources 章节。

在 JAX-RS 的早期版本中，任何附加验证都需要以编程方式进行。此版本的 JAX-RS 引入了对基于 Bean Validation 规范 [16] 的声明式验证的支持。

Bean Validation 规范 [16] 支持使用 **约束注解** 作为声明式验证 Bean、方法参数和方法返回值的方式。例如，考虑以下使用约束注解增强的资源类

@NotNull 和 @Email 注解对表单参数 firstName、lastName 和 email 施加了附加约束。@NotNull 约束是 Bean Validation API 内置的；@Email 约束假定在上面的示例中是用户定义的。这些约束注解不限于方法参数，它们可以在 JAX-RS 绑定注解允许的任何位置使用，除了构造函数和属性 setter。上例中的 MyResourceClass 可以写成如下形式，而不是使用方法参数

请注意，在此版本中，firstName 和 lastName 是通过注入初始化的字段，而 email 是一个资源类属性。属性上的约束注解在它们相应的 getter 中指定。

约束注解也允许在资源类上使用。除了注解字段和属性外，还可以为整个类定义注解。假设 @NonEmptyNames 验证 MyResourceClass 中的两个 **名称** 字段之一是否已提供。使用此类注解，可以扩展上面的示例

资源类上的约束注解对于定义跨字段和跨属性的约束非常有用。

注解约束和验证器根据 Bean Validation 规范 [16] 定义。上面显示的 @Email 注解是使用 Bean Validation 的 @Constraint 元注解定义的

@Constraint 注解必须包含对将用于验证被修饰值的验证器类的引用。EmailValidator 类必须实现 ConstraintValidator<Email, T>，其中 T 是正在被验证的值的类型。例如，

因此，EmailValidator 应用于被 @Email 注解且类型为 String 的值。可以为相同的约束注解定义不同类型的验证器。

约束注解还必须定义一个 groups 元素，以指示它们所属的处理组。如果未指定组（如上例所示），则假定为 Default 组。为简化起见，JAX-RS 实现 **不** 要求支持 Default 以外的处理组。在下面的内容中，我们假设约束验证在 Default 处理组中进行。

请求实体正文可以映射到资源方法参数。可以通过两种方式验证这些实体。如果请求实体被映射到注解了 Bean Validation 注解的 Java bean 类，则可以使用 @Valid 启用验证

在这种情况下，将调用与 @StandardUser（以及像 @NotNull 这样的非类级别约束）关联的验证器来验证映射到 user 的请求实体。或者，可以定义一个新注解并直接用于资源方法参数。

在上面的示例中，将使用 @PremiumUser 而不是 @StandardUser 来验证请求实体。这两种触发实体验证的方式也可以通过将 @Valid 包含在约束列表中来组合。@Valid 的存在将触发对注解 Java bean 类 **所有** 约束注解的验证。除非存在 @ConvertGroup 注解，否则此验证将在 Default 处理组中进行。有关 @ConvertGroup 的更多信息，请参阅 [16]。

从资源方法返回的响应实体正文可以通过注解资源方法本身以类似的方式进行验证。为了举例说明，假设在返回用户之前需要检查 @StandardUser 和 @PremiumUser，则 getUser 方法可以如下注解

请注意，@PremiumUser 被显式列出，而 @StandardUser 是由 @Valid 注解的存在触发的（参见本节前面 User 类的定义）。

根据 [16]，默认情况下仅为所谓的 **约束** 方法启用验证。Java Beans 规范中定义的 Getter 方法不是约束方法，因此默认情况下它们不会被验证。@ValidateOnExecution 注解（在 [16] 中定义）可用于选择性地启用和禁用验证。例如，您可以按如下方式为上面显示的 getEmail 方法启用验证

@ValidateOnExecution 的 type 属性的默认值是 IMPLICIT，在上面的示例中，这会导致验证 getEmail 方法。有关此注解的其他用途，请参阅 [16]。

请注意，如果 **启用** 了 Getter 方法的验证，并且资源方法的签名符合 Getter 的规则，则资源方法可能（无意中）在验证期间被调用。反之，如果 **禁用** 了 Getter 方法的验证，并且 **匹配** 的资源方法的签名符合 Getter 的规则，JAX-RS 运行时仍将在调用之前验证该方法（即，将忽略验证首选项）。

约束注解的继承规则在 [16] 中定义。值得注意的是，这些规则与 Annotation Inheritance 中定义的规则不兼容。总的来说，约束注解在类型层次结构中是累积的（可以加强），而 JAX-RS 注解被继承或被覆盖和忽略。

本规范的目标是通过利用现有的 Bean Validation 实现来验证 JAX-RS 资源。因此，JAX-RS 实现 **必须** 遵循 [16] 中定义的约束注解规则。

约束注解允许出现在以下注解的相同位置：@MatrixParam、@QueryParam、@PathParam、@CookieParam、@HeaderParam 和 @Context，**除了** 类构造函数和属性 setter。具体来说，它们允许出现在资源方法参数、字段和属性 getter 以及资源类、实体参数和资源方法（返回值）中。

JAX-RS 中默认的资源类实例生命周期是每个请求。实现可以支持其他生命周期；在资源类中使用其他 JAX-RS 注解的相同注意事项也适用于约束注解。例如，注解了生命周期为单例的资源类的构造函数参数的约束验证将只执行一次。

JAX-RS 实现 **应** 使用以下过程在实例化资源类实例后对其进行验证

[16] 中的异常模型定义了一个基类 javax.validation.ValidationException 和几个子类来报告特定于约束定义、约束声明、组定义和约束冲突的错误。JAX-RS 实现 **必须** 提供一个默认的异常映射器（参见 Exception Mapping Providers），遵循以下规则

在所有情况下，JAX-RS 实现 **应** 包含一个描述错误来源的响应实体；但是，此实体的确切内容和格式超出了本规范的范围。如 Exception Mapping Providers 所述，应用程序可以提供自己的异常映射器，从而定制上述默认映射器。

异步处理是一种能够更好地有效利用处理线程的技术。在客户端，发出请求的线程也可能负责更新 UI 组件；如果该线程被阻塞等待响应，应用程序的用户感知性能将受到影响。类似地，在服务器端，处理请求的线程应避免在等待外部事件完成时阻塞，以便在此期间到达服务器的其他请求可以得到处理 ^[14]。

如 Enterprise Java Beans (EJBs) 所述，支持 EJB 的产品中的 JAX-RS 实现还必须支持将无状态和单例会话 Bean 用作根资源类。当 EJB 方法注解了 @Asynchronous 时，EJB 容器会自动为其执行分配必要的资源。因此，在这种情况下，使用 Executor 对于生成异步响应是不必要的。

考虑以下示例

在这种情况下，不需要显式的线程管理，因为这是由 EJB 容器控制的。就像本章中的其他示例一样，通过调用注入的 AsyncResponse 上的 resume 来生成响应。因此，longRunningOp 的返回类型只是 void。

流畅的 API 在调用构建过程中支持异步调用。默认情况下，调用是同步的，但可以通过调用 async 方法并（可选地）注册 InvocationCallback 实例来使其异步运行，如下所示

请注意，在此示例中，调用 async 后的 get 调用会立即返回，而不会阻塞调用者的线程。响应类型被指定为 InvocationCallback 的类型参数。当调用成功完成且响应可用时，会调用 completed 方法；当调用失败时，会使用 Throwable 实例调用 failed 方法。

所有异步调用都返回一个 Future<T> 实例，其中类型参数 T 匹配 InvocationCallback 中指定的类型。此实例可用于监视或取消异步调用

虽然建议在执行异步调用时传递 InvocationCallback 实例，但并非强制要求。省略时，调用返回的 Future<T> 可用于通过调用 Future.get 方法来访问响应，该方法在调用成功时返回 T 的实例，在调用失败时返回 null。

Server-sent events (SSE) 是 W3C 最初作为 HTML5 的一部分引入的规范，但目前由 WHATWG [17] 维护。它提供了一种从服务器到客户端建立单向通道的方法。连接是长期的：它被重用于从服务器发送的多个事件，但它仍然基于 HTTP 协议。客户端通过在 Accept 头中使用特殊媒体类型 text/event-stream 来请求打开 SSE 连接。

事件是结构化的，包含多个字段，即 event、data、id、retry 和 comment。SSE 是一种消息传递协议，其中 event 字段对应一个主题，而 id 字段可用于验证事件顺序和保证连续性。如果连接因任何原因中断，id 可以在请求头中发送，以便服务器重播过去的事件 —尽管这是一种可选行为，并非所有实现都可能支持。事件负载通过 data 字段传输，并且必须是文本格式；retry 用于控制重连，最后 comment 是一个通用字段，也可用于保持连接活动。

JAX-RS 针对SSE的客户端API的灵感来源于HTML5中对应的JavaScript API，但由于使用了不同的语言而进行了相应的更改。客户端API的入口点是SseEventSource类型，它提供了一个流畅的构建器，类似于JAX-RS API中的其他类。SseEventSource是从一个已配置了资源位置的WebTarget构建的；SseEventSource不重复WebTarget中的任何功能，只添加了SSE所需的逻辑。

以下示例展示了如何打开一个SSE连接并读取一些消息一段时间

如本例所示，SseEventSource实现了AutoCloseable。在打开源之前，客户端注册了一个事件消费者，该消费者仅打印每个事件。其他生命周期事件（如onComplete和onError）的处理器也得到支持，但为了简单起见，本示例仅显示了onEvent。

JAX-RS SSE服务器API用于接受连接并向一个或多个客户端发送事件。注入了SseEventSink并产生text/event-stream媒体类型的资源方法是一个SSE资源方法。

以下示例接受SSE连接，并使用一个执行器线程在关闭连接前发送3个事件

SSE资源方法遵循与异步处理（参见引言）相似的模式，即代表传入连接的对象（在此例中为SseEventSink）被注入到资源方法中。

上面的示例还注入了Sse类型，该类型提供了事件和广播器的工厂方法。有关广播的更多信息，请参阅广播。请注意，与SseEventSource一样，SseEventSink接口也是自动关闭的，因此使用了上面的try-with-resources语句。

SseEventSink上的send方法返回一个CompletionStage<?>，作为提供异步发送消息到客户端的操作的句柄。

应用程序可能需要同时向多个客户端发送事件。此操作在JAX-RS中称为广播。多个SseEventSink可以注册到单个SseBroadcaster上。

广播器只能通过调用注入的Sse实例上的newBroadcaster方法来创建。SseBroadcaster的生命周期和范围完全由应用程序控制，不由JAX-RS 运行时控制。以下示例展示了广播器的使用，请注意资源类上的@Singleton注解

广播器上的register方法用于添加新的SseEventSink；broadcast方法用于将SSE事件发送给所有已注册的消费者。

来自SSE客户端的连接由可注入的SseEventSink实例表示。SSE与异步处理（参见异步处理章节）之间存在一些相似之处。异步响应最多可以恢复一次，而SseEventSink可以多次用于流式传输单个事件。

为了兼容性，实现必须在发送第一个消息或资源方法返回时启动SSE响应的处理，以两者中较早的为准。初始SSE响应（可能只包含HTTP头）使用标准的JAX-RS 管道进行处理，如附录处理管道中所述。每个后续的SSE事件可能包含不同的有效载荷，因此需要使用特定的消息体写入器。请注意，由于此用例与正常的JAX-RS 管道略有不同，实现不应在每个单独的事件上调用实体拦截器。^[15]

SseEventSource类使用基于RuntimeDelegate的现有JAX-RS 机制，通过服务名称javax.ws.rs.sse.SseEventSource.Builder查找实现。javax.ws.rs.sse中的大多数类型都是线程安全的；读者可以参考Javadoc以获取有关线程安全的更多信息。

上下文特定于特定请求，但是某些JAX-RS 组件的实例（生命周期非按请求的提供者和资源类）可能需要支持多个并发请求。在注入上下文类型列表中类型的实例时，提供的实例必须能够为特定请求选择正确的上下文。使用线程局部代理是实现此目的的常用方法。

本节介绍可用于提供者（客户端和服务器）以及资源类和Application子类（仅服务器端）的上下文类型。除了Configuration和Providers（可在客户端和服务器端提供者中注入）之外，所有其他类型都是仅服务器端。

@Context 注解可用于指示对Servlet定义的资源的依赖。基于Servlet的实现必须支持以下Servlet定义类型的注入：ServletConfig, ServletContext, HttpServletRequest和HttpServletResponse。

注入的HttpServletRequest允许资源方法流式传输请求实体的内容。如果资源方法有一个参数的值来自请求实体，那么流将已经被消耗，尝试访问它可能会导致异常。

注入的HttpServletResponse允许资源方法在返回之前提交HTTP响应。实现必须检查已提交的状态，并且仅在响应尚未提交时才处理返回值。

Servlet过滤器可以通过访问请求参数来触发请求体消耗。在Servlet容器中，如果请求体已经被消耗，则@FormParam注解和application/x-www-form-urlencoded的标准实体提供者必须从Servlet请求参数中获取其值。Servlet API不区分URI中的参数和请求体中的参数，因此基于URI的查询参数可能包含在实体参数中。

本节描述了在与支持以下规范的产品中结合使用JAX-RS 实现时适用的其他要求。

其他容器技术可以指定其自己的可注入资源集，但至少必须支持访问上下文类型中列出的类型。

如果未通过注入提供，则提供的RuntimeDelegate API类使用以下算法获取具体实现类。下面列出的步骤按顺序执行，在每个步骤中，最多会产生一个候选实现类名。然后，实现将尝试使用当前上下文类加载器或java.lang.Class.forName(String)方法加载具有给定类名的类。一旦某个步骤成功加载了实现类，算法就会终止。