知識庫 / REST RSS 訂閱

1. 簡介

Jersey 是一個流行的 Java 框架，用於創建 RESTful Web 服務。

在本教程中，我們將探索如何通過一個簡單的 Jersey 項目讀取不同請求參數類型。

2. 項目設置

使用 Maven 考古包，我們可以為我們的文章生成一個可運行的項目：

mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2
  -DarchetypeGroupId=org.glassfish.jersey.archetypes -DinteractiveMode=false
  -DgroupId=com.example -DartifactId=simple-service -Dpackage=com.example
  -DarchetypeVersion=2.28

生成的 Jersey 項目將運行在 Grizzly 容器之上。

默認情況下，應用程序的端點將是 http://localhost:8080/myapp。

讓我們添加一個 items 資源，我們將用於我們的實驗：

@Path("items")
public class ItemsController {
    // our endpoints are defined here
}

順便説明的是，Jersey 也非常適合與 Spring 控制器一起使用。

3. 註釋參數類型

因此，在我們實際讀取任何請求參數之前，我們先明確一些規則。允許的參數類型如下：

• 基本類型，如float和char
• 具有單個String參數構造函數的類型
• 具有要麼fromString靜態方法，要麼valueOf靜態方法；對於這些類型，單個String參數是必需的
• 集合 – 如List、Set和SortedSet – 這些集合的類型是上述類型

此外，我們可以註冊一個ParamConverterProvider JAX-RS 擴展 SPI。返回類型必須是一個能夠將String轉換為類型的ParamConverter 實例。

4. Cookie

我們可以使用 Jersey 方法中 @CookieParam 註解來解析 Cookie 值：

@GET
public String jsessionid(@CookieParam("JSESSIONId") String jsessionId) {
    return "Cookie parameter value is [" + jsessionId+ "]";
}

<div>
  <div>
    <span>如果啓動我們的容器，我們可以使用 cURL 訪問此端點以查看響應：</span>
  </div>
</div>

> curl --cookie "JSESSIONID=5BDA743FEBD1BAEFED12ECE124330923" http://localhost:8080/myapp/items
Cookie parameter value is [5BDA743FEBD1BAEFED12ECE124330923]

5. 標題

或者，我們可以使用 @HeaderParam 註解來解析 HTTP 頭部。

@GET
public String contentType(@HeaderParam("Content-Type") String contentType) {
    return "Header parameter value is [" + contentType+ "]";
}

讓我們再次測試一下:

> curl --header "Content-Type: text/html" http://localhost:8080/myapp/items
Header parameter value is [text/html]

6. 路徑參數

尤其在使用 RESTful API 時，通常會在路徑中包含信息。

我們可以使用 @PathParam 提取路徑元素：

@GET
@Path("/{id}")
public String itemId(@PathParam("id") Integer id) {
    return "Path parameter value is [" + id + "]";
}

讓我們再次發送一個 curl 命令，帶有一個值為 3 的參數：

> curl http://localhost:8080/myapp/items/3
Path parameter value is [3]

7. 查詢參數

我們通常在 RESTful API 中使用查詢參數來傳遞可選信息。

要讀取這些值，我們可以使用 @QueryParam 註解：

@GET
public String itemName(@QueryParam("name") String name) {
    return "Query parameter value is [" + name + "]";
}

所以，現在我們可以使用 curl，就像之前一樣：

> curl http://localhost:8080/myapp/items?name=Toaster
Query parameter value if [Toaster]

8. 表單參數

@POST
public String itemShipment(@FormParam("deliveryAddress") String deliveryAddress, 
  @FormParam("quantity") Long quantity) {
    return "Form parameters are [deliveryAddress=" + deliveryAddress+ ", quantity=" + quantity + "]";
}

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  -d 'deliveryAddress=Washington nr 4&quantity=5' \
  http://localhost:8080/myapp/items
Form parameters are [deliveryAddress=Washington nr 4, quantity=5]

@GET
public String itemColors(@MatrixParam("colors") List<String> colors) {
    return "Matrix parameter values are " + Arrays.toString(colors.toArray());
}

> curl http://localhost:8080/myapp/items;colors=blue,red
Matrix parameter values are [blue,red]

public class ItemOrder {
    @HeaderParam("coupon")
    private String coupon;

    @PathParam("itemId")
    private Long itemId;

    @FormParam("total")
    private Double total;

    //getter and setter

    @Override
    public String toString() {
        return "ItemOrder {coupon=" + coupon + ", itemId=" + itemId + ", total=" + total + '}';
    }
}

@POST
@Path("/{itemId}")
public String itemOrder(@BeanParam ItemOrder itemOrder) {
    return itemOrder.toString();
}

> curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
  --header 'coupon:FREE10p' \
  -d total=70 \
  http://localhost:8080/myapp/items/28711
ItemOrder {coupon=FREE10p, itemId=28711, total=70}