第 49 章 JAX-RS 2.0 Client API

JAX-RS 2.0 定义了用于 JAX-RS 客户端的流畅 API，它可让您构建 HTTP 请求逐步构建，然后使用适当的 HTTP 动词（GET、POST、PUT 或 DELETE）调用请求。

要在应用中使用 JAX-RS 2.0 客户端 API，您必须将以下 Maven 依赖项添加到项目的 pom.xml 文件中：

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-rs-client</artifactId>
  <version>3.3.6.fuse-7_11_1-00015-redhat-00002</version>
</dependency>

如果您计划使用异步调用功能（请参阅 第 49.6 节 “客户端上的异步处理”），您还需要以下 Maven 依赖项：

<dependency>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-rt-transports-http-hc</artifactId>
  <version>3.3.6.fuse-7_11_1-00015-redhat-00002</version>
</dependency>

JAX-RS 2.0 客户端接口和类位于以下 Java 软件包中：

javax.ws.rs.client

在开发 JAX-RS 2.0 Java 客户端时，您通常需要访问核心软件包中的类：

javax.ws.rs.core

以下代码片段演示了一个简单的示例，其中 JAX-RS 2.0 客户端 API 用于对 http://example.org/bookstore JAX-RS 服务进行调用，并通过 GET HTTP 方法调用：

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
import javax.ws.rs.core.Response;
...
Client client = ClientBuilder.newClient();
Response res = client.target("http://example.org/bookstore/books/123")
    .request("application/xml").get();

JAX-RS 2.0 客户端 API 设计为一个 流畅的 API （有时称为域特定语言）。在流畅的 API 中，以单一声明调用一个 Java 方法链，因此 Java 方法从简单语言类似命令。在 JAX-RS 2.0 中，流畅的 API 用于构建和调用 REST 请求。

使用 JAX-RS 2.0 客户端 API，在一系列步骤中构建并调用客户端调用，如下所示：

第一步是通过创建 javax.ws.rs.client.Client 对象来引导客户端。此 客户端 实例是一个相对重量型对象，它代表支持 JAX-RS 客户端（包括拦截器和其他 CXF 功能）所需的技术堆栈。理想情况下，您应在可以时重新使用客户端对象，而不是创建新对象。

要创建新的 Client 对象，请在 ClientBuilder 类上调用静态方法，如下所示：

// Java
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Client;
...
Client client = ClientBuilder.newClient();
...

通过配置目标，您可以有效地定义用于 REST 调用的 URI。以下示例演示了如何使用 path(String) 方法定义基本 URI 基础 URI，然后向基本 URI 添加额外路径片段：

// Java
import javax.ws.rs.client.WebTarget;
...
WebTarget base = client.target("http://example.org/bookstore/");
WebTarget books = base.path("books").path("{id}");
...

这实际上分为两个步骤：首先，您先构建 HTTP 请求（包括标头、接受媒体类型等）；然后，您可以调用相关的 HTTP 方法（可选提供请求消息正文（如果需要）。

例如，要创建并调用接受 application/xml 介质类型的请求：

// Java
import javax.ws.rs.core.Response;
...
Response resp = books.resolveTemplate("id", "123").request("application/xml").get();

最后，您需要解析上一步中获得的重新启动。通常，以 javax.ws.rs.core.Response 对象的形式返回响应，它封装了 HTTP 标头和其他 HTTP 元数据，以及 HTTP 邮件正文（若有）。

如果要以 String 格式访问返回的 HTTP 消息，您可以使用 String.class 参数调用 readEntity 方法，如下所示：

// Java
...
String msg = resp.readEntity(String.class);

您可以始终将响应的消息正文作为 String 进行访问，方法是将 String.class 指定为 readEntity 的参数。有关更常规转换或转换邮件正文，您可以提供 一个实体供应商 来执行转换。如需了解更多详细信息，请参阅 第 49.4 节 “解析请求和响应”。