JAX-RS 與 Jersey

JAX-RS 是 jakarta.ws.rs 套件中 HTTP 資源的 Jakarta 標準 API 與規格。它定義註解、請求與回應型別、用戶端 API、提供者，以及伺服器傳送事件支援。Jersey 是符合規格的 JAX-RS 實作。

JAX-RS 不同於 JAX-WS；後者處理 XML Web 服務。

定義資源 #

在編譯時加入 Jakarta REST API，並在執行時加入 JAX-RS 實作。資源類別使用 @Path；方法使用 HTTP 方法註解，也可以加入相對路徑：

@Path("/users")
@Produces(MediaType.APPLICATION_JSON)
public class UserResource {
    @GET
    @Path("/{id}")
    public User get(@PathParam("id") long id) {
        return service.find(id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response create(User input) {
        User created = service.create(input);
        return Response.created(
                URI.create("/users/" + created.id())).entity(created).build();
    }
}

Application 子類別可以使用 @ApplicationPath("/api") 註解。周圍的容器或實作會決定請求如何抵達 JAX-RS 執行期。

繫結請求 #

為非本文方法參數註解其來源：

• @PathParam、@QueryParam 與 @MatrixParam 讀取 URI 元件。
• @HeaderParam、@CookieParam 與 @FormParam 讀取標頭、Cookie 與表單資料。
• @Context 注入內容相關的 JAX-RS 物件。

@GET
public Response search(
        @QueryParam("q") String query,
        @QueryParam("limit") @DefaultValue("20") int limit) {
    return Response.ok(service.search(query, limit)).build();
}

未註解的資源方法參數通常是請求實體。其 Java 型別必須受 MessageBodyReader 支援；例如，JSON 至物件的繫結需要已安裝的 JSON 提供者。宣告 @Consumes 使契約明確。InputStream 可以接受原始實體，但單獨的核心 JAX-RS 不會剖析 multipart/form-data；請使用受支援的 multipart 提供者，例如 Jersey 的 multipart 模組。

使用 @BeanParam 將數個參數繫結分組到 bean 中：

public class PageRequest {
    @QueryParam("offset") @DefaultValue("0") int offset;
    @QueryParam("limit") @DefaultValue("20") int limit;
}

將它用作 @BeanParam PageRequest page。請明確驗證輸入，或使用執行期提供的 Jakarta Validation 整合。

產生回應與錯誤 #

方法可以直接回傳實體，也可以回傳 Response 以明確控制狀態、標頭與實體。@Produces 會參與內容協商。請回傳適當狀態與穩定的錯誤表示，不要向用戶端公開堆疊追蹤。

擲出 WebApplicationException（例如 NotFoundException 或 BadRequestException）會提供 HTTP 回應。對應用程式例外，請撰寫 ExceptionMapper<T> 並以 @Provider 註解：

@Provider
public class IllegalArgumentMapper
        implements ExceptionMapper<IllegalArgumentException> {
    public Response toResponse(IllegalArgumentException error) {
        return Response.status(Response.Status.BAD_REQUEST)
                .entity(Map.of("error", error.getMessage())).build();
    }
}

執行期會選擇適用的 mapper，其例外型別是擲出例外的最接近超型別。若沒有適用者，則會依容器整合產生伺服器錯誤回應。

使用 Jersey 部署 #

Jersey 實作 JAX-RS 契約，但本身不接受 TCP 連線。在 Servlet 容器中，加入 org.glassfish.jersey.containers:jersey-container-servlet、註冊 org.glassfish.jersey.servlet.ServletContainer，並設定資源套件掃描或 ResourceConfig。

對嵌入式伺服器，建立 ResourceConfig 並傳給受支援的 Jersey 容器。可行時，讓應用程式程式碼依賴 jakarta.ws.rs，並將 Jersey 特定設定隔離在部署邊界。