1. 概述
Jersey 是一个用于开发 RESTful Web 服务的开源框架,同时也具备强大的内置客户端功能。
在这个快速教程中,我们将探讨如何使用 Jersey 2 创建 JAX-RS 客户端。
有关使用 Jersey 构建 RESTful Web 服务的讨论,请参考 这篇文章。
2. Maven 依赖
首先,在 pom.xml
中添加所需的依赖(针对 Jersey 的 JAX-RS 客户端):
<dependency>
<groupId>org.glassfish.jersey.core</groupId>
<artifactId>jersey-client</artifactId>
<version>2.25.1</version>
</dependency>
如果需要使用 Jackson 2.x 作为 JSON 提供器:
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-jackson</artifactId>
<version>2.25.1</version>
</dependency>
这些依赖的最新版本可以在 jersey-client 和 jersey-media-json-jackson 查找。
3. Jersey 中的 RESTful 客户端
我们将开发一个 JAX-RS 客户端来消费我们之前在这里创建的 JSON 和 XML REST API(/jersey-rest-api-with-spring),确保服务已部署并且 URL 可访问。
3.1. 资源表示类
让我们看看资源表示类:
@XmlRootElement
public class Employee {
private int id;
private String firstName;
// standard getters and setters
}
只有在需要 XML 支持时,才需要像 @XmlRootElement 这样的 JAXB 注解。
3.2. 创建 Client 实例
我们需要首先创建一个 Client 实例:
Client client = ClientBuilder.newClient();
3.3. 创建 WebTarget
有了 Client 实例后,我们可以使用目标资源的 URI 来创建一个 WebTarget:
WebTarget webTarget
= client.target("http://localhost:8082/spring-jersey");
使用 WebTarget,我们可以定义到特定资源的路径:
WebTarget employeeWebTarget
= webTarget.path("resources/employees");
3.4. 构建 HTTP 请求调用
通过 WebTarget.request() 方法之一创建一个调用构建器实例:
Invocation.Builder invocationBuilder
= employeeWebTarget.request(MediaType.APPLICATION_JSON);
对于 XML 格式,可以使用 MediaType.APPLICATION_XML。
3.5. 调用 HTTP 请求
调用 HTTP GET:
Response response
= invocationBuilder.get(Employee.class);
调用 HTTP POST:
Response response
= invocationBuilder
.post(Entity.entity(employee, MediaType.APPLICATION_JSON);
3.6. 示例 REST 客户端
现在开始编写简单的 REST 客户端。getJsonEmployee()
方法根据员工 id 获取一个 Employee 对象。由 REST Web 服务返回的 JSON 将被反序列化为 Employee 对象后返回。
使用 JAX-RS API 流畅地创建 web 目标、调用构建器并调用 HTTP GET 请求:
public class RestClient {
private static final String REST_URI
= "http://localhost:8082/spring-jersey/resources/employees";
private Client client = ClientBuilder.newClient();
public Employee getJsonEmployee(int id) {
return client
.target(REST_URI)
.path(String.valueOf(id))
.request(MediaType.APPLICATION_JSON)
.get(Employee.class);
}
//...
}
接下来,我们添加一个处理 POST HTTP 请求的方法。createJsonEmployee()
方法通过调用 REST Web 服务 创建 Employee。客户端 API 内部将 Employee 对象序列化为 JSON 后再调用 HTTP POST 方法:
public Response createJsonEmployee(Employee emp) {
return client
.target(REST_URI)
.request(MediaType.APPLICATION_JSON)
.post(Entity.entity(emp, MediaType.APPLICATION_JSON));
}
4. 测试客户端
现在让我们使用 JUnit 测试我们的客户端:
public class JerseyClientLiveTest {
public static final int HTTP_CREATED = 201;
private RestClient client = new RestClient();
@Test
public void givenCorrectObject_whenCorrectJsonRequest_thenResponseCodeCreated() {
Employee emp = new Employee(6, "Johny");
Response response = client.createJsonEmployee(emp);
assertEquals(response.getStatus(), HTTP_CREATED);
}
}
5. 总结
在这篇文章中,我们介绍了使用 Jersey 2 的 JAX-RS 客户端,并开发了一个简单的 RESTful Java 客户端。
如常,完整的源代码可以在 这个 Github 项目 找到。