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-clientjersey-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 项目 找到。