第 49 章 JAX-RS 2.0 客户端 API
摘要
JAX-RS 2.0 定义功能齐全的客户端 API,可用于进行 REST 调用或任何 HTTP 客户端调用。这包括一个流畅的 API (以简化构建请求)、用于解析消息的框架(基于称为 实体提供程序的类型),以及客户端一侧异步调用的支持。
49.1. JAX-RS 2.0 客户端 API 简介
概述
JAX-RS 2.0 为 JAX-RS 客户端定义流畅的 API,它允许您通过步骤构建 HTTP 请求步骤,然后使用适当的 HTTP 动词(GET、POST、PUT 或 DELETE)调用请求。
还可以在 Blueprint XML 或 Spring XML 中定义 JAX-RS 客户端(使用 jaxrs:client
元素)。有关这个方法的详情,请参考 第 18.2 节 “配置 JAX-RS 客户端端点”。
依赖项
要在应用程序中使用 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-780029-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-780029-redhat-00001</version> </dependency>
客户端 API 软件包
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();
fluent API
JAX-RS 2.0 客户端 API 设计为一个 流畅的 API (有时称为域特定语言)。在流畅的 API 中,在单个声明中调用 Java 方法链,使得 Java 方法看起来像是简单语言中的命令。在 JAX-RS 2.0 中,fluent API 用于构建和调用 REST 请求。
进行 REST 调用的步骤
使用 JAX-RS 2.0 客户端 API,在一系列步骤中构建和调用客户端,如下所示:
- bootstrap 客户端。
- 配置目标。
- 构建和进行调用。
- 解析响应。
bootstrap 客户端
第一步是通过创建 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
.classreadEntity
的参数,将响应消息正文作为 String 进行访问。对于更常规转换或转换邮件正文的转换,您可以提供 一个实体供应商 来执行转换。如需了解更多详细信息,请参阅 第 49.4 节 “解析请求和响应”。