使用 JAX-RS (JSR-311) 建立 RESTful Web 服務完整指南

JAX-RS 核心資源模型

JAX-RS 以註解驅動，定義五種資源類型：

程式碼範例：員工聯絡資源

package com.ibm.jaxrs.sample.organization;

import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;
import java.util.List;

@Path("/contacts")
@Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
public class ContactsResource {

  @GET
  public List getAllContacts() { /* 回傳所有聯絡人 */ }

  @GET
  @Path("/{emailAddress:.+@.+\\.[a-z]+}")
  public ContactInfo getByEmail(@PathParam("emailAddress") String email) { /* 依 Email 查詢 */ }

  @GET
  @Path("/{lastName}")
  public ContactInfo getByLastName(@PathParam("lastName") String lastName) { /* 依姓氏查詢 */ }

  @POST
  @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
  public void addContact(ContactInfo info) { /* 新增聯絡人 */ }

  @Path("/contact/{contactName}/department")
  public Department getContactDept(@PathParam("contactName") String name) {
    return new Department(name); // Sub-resource Locator
  }
}

// Sub-resource
class Department {
  private String name;
  Department(String name) { this.name = name; }
  @GET public String getDepartmentName() { return name; }
}

關鍵註解詳解

@Path

• 值可含常字、變數 {var}、正則 {var:regex}
• 範例：@Path("/contacts/{email:.+@.+\\.[a-z]+}") 只比對 Email 格式

HTTP 方法註解

@GET、@POST、@PUT、@DELETE、@HEAD 對應 HTTP 動詞。可自訂：

@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME)
@HttpMethod("GET") public @interface CustomGET {}

@Consumes / @Produces

• 類別/方法層級均可標註，方法優先覆蓋類別
• Client 以 Content-Type 決定 @Consumes、以 Accept 決定 @Produces
• 範例：Accept: application/json → 回傳 JSON；Content-Type: application/xml → 接收 XML

訊息體讀寫提供者

預設支援 String、InputStream、JAXB 物件等。自訂型別需實作：

• MessageBodyWriter<T>：序列化輸出，標註 @Provider、@Produces
• MessageBodyReader<T>：反序列化輸入，標註 @Provider、@Consumes

@Provider @Produces("application/xml")
public class ContactInfoWriter implements MessageBodyWriter {
  public boolean isWriteable(...) { return true; }
  public void writeTo(ContactInfo ci, ..., OutputStream out) { ci.serialize(out); }
}

應用程式啟動配置

擴充 javax.ws.rs.core.Application：

public class ContactInfoApplication extends Application {
  @Override public Set> getClasses() {
    return new HashSet<>(Arrays.asList(
      ContactsResource.class, ContactInfoWriter.class, ContactInfoReader.class));
  }
  @Override public Set