第 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_10_0-00020-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_10_0-00020-redhat-00001</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 中，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、基础，然后使用路径 (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();

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

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

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

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