JAX-RS 實戰：從 REST 原理到企業級應用開發全解析

一、REST 架構風格核心原則

REST（Representational State Transfer）非標準而是架構風格，基於 HTTP/URI/XML 等成熟協議，核心原則三條：

1. 資源唯一標識：每個資源對應唯一 URI，結構清晰可預測（如 /users/123/accounts）
2. HTTP 語義映射：CRUD 操作與 HTTP 方法一一對應
   • POST → 創建資源
   • GET → 獲取資源
   • PUT → 更新資源
   • DELETE → 刪除資源
3. 多重表現與內容協商：同一資源支持 XML/JSON 等多種表現，通過 Accept/Content-Type 協商格式，降低客戶端與服務端耦合

二、JAX-RS (JSR-311) 核心優勢

• 標準化 API：javax.ws.rs 統一接口，避免綁定第三方框架
• POJO + 註解編程模型：極簡開發體驗，無需繁雜配置
• 內建 JAXB 整合：XML/JSON 序列化零代碼實現
• 多實現可選：Jersey（參考實現）、CXF、RESTEasy 等，僅需修改 web.xml 即可切換

三、核心概念與代碼實戰

1. Resource 類與方法

@Path("/")
public class BookkeepingService {
    @Path("/person/")
    @POST
    @Consumes("application/json")
    public Response createPerson(Person person) { ... }

    @Path("/person/{id:\\d+}/")
    @GET
    @Produces("application/json")
    public Person readPerson(@PathParam("id") int id) { ... }
}

• @Path 定義資源路徑，支持正則模板變量（{id:\\d+}）
• 根資源類與子資源類區別在於類級別是否有 @Path
• 資源方法標註 HTTP 方法（@GET/@POST/@PUT/@DELETE），子資源定位器無此類註解

2. 參數綁定註解全景

實體參數：資源方法僅允許一個無註解參數，映射請求體（如 createPerson(Person person) 自動反序列化 JSON）。

3. 返回值類型與狀態碼控制

• void → 204 No Content
• Response → 完全控制狀態碼、Header、Entity
• GenericEntity → 保留泛型類型信息的 Entity
• 其他 POJO → 自動序列化為響應體，null 為 204，非 null 為 200

異常處理：拋出 WebApplicationException 或返回攜帶錯誤碼的 Response。

4. @Context 注入上下文資源

@Context UriInfo uriInfo;
@Context HttpHeaders headers;
@Context SecurityContext security;
@Context HttpServletRequest servletRequest;

支持標準 Java EE 與 Servlet API 類型注入，便於訪問請求上下文。

四、內容協商與自定義 MessageBodyProvider

1. 雙向協商機制

• 服務端：@Produces 指定可生產格式，@Consumes 指定可消費格式
• 客戶端：Accept 請求頭選擇響應格式，Content-Type 聲明請求格式

2. GsonProvider 實現 JSON 定制序列化

@Provider
@Produces("application/json")
@Consumes("application/json")
public class GsonProvider implements MessageBodyWriter<Object>, MessageBodyReader<Object> {
    private final Gson gson = new GsonBuilder()
        .excludeFieldsWithoutExposeAnnotation()
        .setDateFormat("yyyy-MM-dd")
        .create();
    // 實現 readFrom/writeTo 等方法...
}

通過 @Expose 註解精確控制序列化字段，日期格式統一，避免預設 Gson 行為不符業務預期。

五、JAX-RS 與 JPA 深度融合：同一 POJO 多重角色

@Entity
@Table(name = "TABLE_ACCOUNT")
@XmlRootElement  // JAXB
public class Account {
    @Id @GeneratedValue @Column(name="COL_ID") @Expose private int id;
    @ManyToOne @JoinColumn(name="COL_PERSON") @Expose private Person person;
    @Column(name="COL_AMOUNT") @Expose private BigDecimal amount;
    @Column(name="COL_DATE") @Expose private Date date;
    @ManyToOne @JoinColumn(name="COL_CATEGORY") @Expose private Category category;
    @Column(name="COL_COMMENT") @Expose private String comment;
    // getter/setter...
}

三大收益：

1. 類數量減半：無需單獨定義 DTO/VO，實體類直接服務於持久化、XML/JSON 序列化
2. 字段級精確控制：@Expose（Gson）、@XmlElement（JAXB）、JPA 註解各司其職
3. 事務邊界清晰：Service 層管理事務，Resource 類僅負責協議轉換

六、部署與遷移實踐

• 示例基於 Jersey + OpenJPA + Tomcat
• 遷移至 GlassFish/JBoss/WildFly 僅需調整 web.xml（Servlet 註冊）與 persistence.xml（數據源、方言）
• 生產環境建議：啟用 Jersey 監控、配置連接池、設置請求大小限制、集成 Swagger/OpenAPI 文檔生成

七、總結

JAX-RS 以「約定優於配置」實現了 REST 開發的標準化：註解驅動資源映射、聲明式內容協商、POJO 多重復用。掌握其核心註解語義、參數綁定規則、Provider 擴展機制，即可構建高性能、可演進的 RESTful 服務。