第 49 章 JAX-RS 2.0 客户端 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_13_0-00015-redhat-00001</version>
</dependency>

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

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

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

javax.ws.rs.client

在开发 JAX-RS 2.0 Java 客户端时，您通常还需要从 core 软件包访问类：

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 中，fluent 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。以下示例演示了如何定义基本 URI、基础，然后使用 path (String) 方法向基本 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();

最后，您需要解析在上一步中获取的 resp ose、resp。通常，响应以 javax.ws.rs.core.Response 对象的形式返回，它封装 HTTP 标头和其他 HTTP 元数据，以及 HTTP 消息正文（若有）。

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

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

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