1. Overview

1.概述

Jersey is an open-source framework for developing RESTful web services. It serves as a reference implementation of JAX-RS.

Jersey 是一个开源框架，用于开发RESTful 网络服务。它是 JAX-RS 的参考实现。

In this tutorial, we’ll explore different ways to add a list as a query parameter when making requests using the Jersey client.

在本教程中，我们将探讨在使用 Jersey 客户端发出请求时将列表添加为查询参数的不同方法。

2. GET API to Receive a List in Query Parameters

2.接收查询参数列表的 GET API

We’ll first create a GET API, which receives a list in query parameters.

我们将首先创建一个 GET API，它将接收查询参数中的一个列表。

We can use the @QueryParam annotation to extract values from query parameters in a URI. The @QueryParam annotation takes a single argument, which is the name of the query parameter we want to extract.

我们可以使用 @QueryParam 注解从 URI 中的查询参数中提取值。@QueryParam注解接收一个参数，即我们要提取的查询参数的名称。

To specify a list-type query parameter using @QueryParam, we apply the annotation to a method parameter, indicating that it receives a list of values from a query parameter in the URL:

要使用 @QueryParam 指定列表类型的查询参数，我们将注解应用于方法参数，表示该参数从 URL 中的查询参数接收值列表：

@Path("/")
public class JerseyListDemo {
    @GET
    public String getItems(@QueryParam("items") List<String> items) {
        return "Received items: " + items;
    }
}

Now, we’ll use different methods to pass the list as a query parameter. Once done, we’ll verify the response to ensure the resource processes the list of items correctly.

现在，我们将使用不同的方法将列表作为查询参数传递。完成后，我们将验证响应，以确保资源能正确处理项目列表。

3. Using queryParam()

3.使用 queryParam()

The queryParam() method in Jersey adds query parameters to a URL when constructing an HTTP request. The queryParam() method allows us to specify the name and value of a query parameter.

在构建 HTTP 请求时，Jersey 中的 queryParam() 方法会将查询参数添加到 URL 中。queryParam() 方法允许我们指定查询参数的名称和值。

3.1. Using Query Parameters Directly

3.1.直接使用查询参数

In this approach, we add the query parameters directly using the method provided by Jersey.

在这种方法中，我们使用 Jersey 提供的方法直接添加查询参数。

In the below example, we’ve got a WebTarget as target(), and we’re adding a query parameter items with multiple values item1,item2 to the request URL:

在下面的示例中，我们用 target() 作为 WebTarget ，并在请求 URL 中添加了一个查询参数 items ，其中包含多个值 item1,item2 ：

@Test
public void givenList_whenUsingQueryParam_thenPassParamsAsList() {
    Response response = target("/")
      .queryParam("items", "item1", "item2")
      .request
      .get();
    assertEquals(Response.Status.OK.getStatusCode(), response.getStatus());
    assertEquals("Received items: [item1, item2]", response.readEntity(String.class));
}

This results in a URL with query parameters like /?items=item1&items=item2. Here, the items query parameter contains both item1 and item2 as its values.

这将产生一个带有查询参数的 URL，如 /?item1&item2。这里，items查询参数包含 item1 和 item2 作为其值。

3.2. Using a Comma-Separated String

3.2.使用逗号分隔字符串

In this approach, we convert a list into a comma-separated string, which is then added as a query parameter in the Jersey client. It simplifies the URL construction process but requires server-side logic to parse the string into a list:

在这种方法中，我们将列表转换为逗号分隔的字符串，然后将其作为查询参数添加到 Jersey 客户端中。它简化了 URL 的构建过程，但需要服务器端逻辑将字符串解析为列表：

@Test
public void givenList_whenUsingCommaSeparatedString_thenPassParamsAsList() {
    Response response = target("/")
      .queryParam("items", "item1,item2")
      .request()
      .get();
    assertEquals(Response.Status.OK.getStatusCode(), response.getStatus());
    assertEquals("Received items: [item1,item2]", response.readEntity(String.class));
}

This results in a URL with query parameters like /?items=item1,item2. Here, the items query parameter contains item1,item2 as its values.

这将产生一个查询参数为 /?items=item1,item2 的 URL。在这里，items 查询参数包含 item1,item2 作为其值。

4. Using UriBuilder

4.使用 UriBuilder

The UriBuilder approach is a powerful way to construct URLs with query parameters. In this approach, we create a UriBuilder instance, specify the base URI, and add query parameters iteratively:

UriBuilder 方法是使用查询参数构建 URL 的一种强大方法。在这种方法中，我们创建一个 UriBuilder 实例，指定基本 URI，然后迭代添加查询参数：

@Test
public void givenList_whenUsingUriBuilder_thenPassParamsAsList() {
    List<String> itemsList = Arrays.asList("item1","item2");
    UriBuilder builder = UriBuilder.fromUri("/");
    for (String item : itemsList) {
        builder.queryParam("items", item);
    }
    URI uri = builder.build();
    String expectedUri = "/?items=item1&items=item2";
    assertEquals(expectedUri, uri.toString());
}

The unit test ensures that the UriBuilder correctly assembles the URL with the desired query parameters and also validates its accuracy.

单元测试可确保 UriBuilder 使用所需的查询参数正确组装 URL，并验证其准确性。

5. Conclusion

5.结论

In this article, we learned different methods of passing a list as a query parameter in Jersey.

在本文中，我们学习了在 Jersey 中将列表作为查询参数传递的不同方法。

The queryParam() method is straightforward, making it a suitable choice for simple cases. On the other hand, UriBuilder is well-suited for dynamic URL generation with multiple query parameters. The choice depends on the need of the application, taking into factors like list complexity and the necessity of dynamic URL construction.

queryParam() 方法简单明了，适合简单情况。另一方面，UriBuilder非常适合动态生成带有多个查询参数的 URL。选择取决于应用程序的需要，并考虑到列表的复杂性和动态构建 URL 的必要性等因素。

As always, all the code presented in this article is available over on GitHub.

与往常一样，本文中介绍的所有代码均可在 GitHub 上获取。