Jax-rs\Jersey架構與RESTful Web Service

JAX-RS(Java API for RESTful Web Service，JSR-311)是Java提供用於開發RESTful Web服務基於註解(annotation)的API，

在Java EE 6中發布，旨在定義一個統一的規範，使得Java程式員可以使用一套固定的介面來開發REST應用，避免了依賴第三方框

架，同時JAX-RS使用POJO編程模型和基於註解的配置並整合JAXB，從而有效縮短了REST應用的開發週期，JSR-311開始於2007

年2月，至今發布了兩個最終版本1.0，1.1，值得注意的是JAX-RS2.0(JSR-339，始於2011年1月)進行中中；

（順便說下，Java之所以稱為開放技術就是因為JSR(Java Specification Requests)，任何組織和個人都能向JCP(Java 

Community Process)提起JSR，經專家組評審通過後可以在後續Java版本中作為新功能發布，Java的發展就是通過JCP來推動）。

JAX-RS API概述

JAX-RS定義的包結構如下，包含近五十多個介面，註解和抽象類別：
javax.ws.rs：包含用於建立RESTful服務資源的高層次（High-level）介面和註解；
javax.ws.rs.core：包含用於建立RESTful服務資源的低層次（Low-level）介面和註解；
javax.ws.rs.ext：包含用於擴充JAX-RS API支援類型的APIs；
注意：JAX-RS規範只是定義API，真正開發RESTful Web服務需要引入具體實現，具體實現由第三方提供，如Sun的參考實現Jersey，Apache CXF，Jboss RESTEasy。

JAX-RS API的目標

基於POJO：該API提供一組註解,類,介面用於將POJOs暴露為網路資源（Web Resource），並定義對象的生命週期和有效範圍； 以HTTP為中心：該規範將預設HTTP作為底層網路通訊協定並提供一個清晰的HTTP和URI元素到API類和註解之間的映射，該API提供對常見的HTTP使用模式和包括WebDAV，Atom發布協議在內的各種HTTP應用進行支援； 格式無關性：該API將能處理多種不同內容格式的HTTP實體，並提供統一的擴充機制允許應用新增支援其他內容格式（通過實體Provider）； 容器無關性：使用該API的應用能被部署到多個Web容器，該規範將定義如何將應用部署在Servlet容器和作為一個JAX-WS提供者； 融入Java EE：該規範將定義在Java EE容器中網路資源（Web Resource）類的環境並將指導如何使用Java EE提供的功能和組件。

下面看到一篇比較好的介紹JAX-RS和REST的文章，轉載過來一起學習。

一、簡介

　　Java Web有很多成熟的架構，主要可以分為兩類Web Application和Web Services。用於Web Application的架構套件括官方的Servlet/JSP, JSTL/JSF以及第三方Struts/spring MVC(action-based)。Web Services的項目又可以分為基於XML的（SOAP/WSDL）的和基於JSON的，Java Communitiy為這兩種方式都定義了標準，Java EE5引入了JAX-WS(Java API for XML Web Services)-JSR224，Java EE6引入了JAX-RS(Java API for RESTful Web Services)-JSR331。RESTful Service由於輕量，好測試，有彈性等特點，越來越受歡迎。Jersey，RESTEasy都是JAX-RS標準的具體實現。

  二、REST

Rest（representational state transfer, 表現層狀態轉化）是一種漸漸層成Web設計主流的設計理念，最早由Roy Thomas Fielding（HTTP1.0/1.1協議主要設計者之一，Apache作者之一，Apache基金會第一任主席）在2000年的博士論文中提出。 資源（Resource）：網路上一個實體（具體資訊），每個資源都用一個URI來標識和定位。所有的資源都位於伺服器中。 表現層（Representation）：資源的表現形式。例如文本資訊可以用Txt展現，也可以用HTML，XML，JSON格式表現，甚至是二進位格式。URI只代表資源實體，它的表現形式在Http要求標頭中用Accept和Content-Type欄位指定，這兩個欄位才是對錶現層的描述。用戶端見到的所有東西都只是伺服器上資源的表現層，用戶端和伺服器之間傳遞的也都是表現層（資源請求攜帶的參數，返回的JSON，TXT，JPG等MIME-TYPE）。 狀態轉換（State Transfer）：用戶端所有操作本質上就是用某種方法讓伺服器中的資源狀態發生變化。用戶端只能見到資源的表現層，所以伺服器上資源狀態的轉換必然建立在表現層上。用戶端讓伺服器資源發生狀態變化的唯一方法就是使用HTTP請求，通過HTTP請求的不同方法（Method）實現對資源的不同的狀態更改操作（如增刪改查Create,Read,Update,Delete）。HTTP協議中設計的要求方法包括GET(擷取)，POST(新增)，PUT(更新)，DELETE(刪除)，HEAD，STATUS，OPTIONS等，不同方法代表了不同的操作，但是HTML只實現了GET和POST。

 

樣本，例如有一個圖書管理的Restful服務，該服務將會呈現為下面的形式（先不用考慮服務具體如何?的）：

資源：
　　系統中所有書籍的集合是一個資源，可以用URL http://www.example.com/books 來表示　　系統中有本書id為1000，這本書也是一個資源，可以用URL  http://www.example.com/books/1000 來表示
操作：
　　如果想要查看書集中包含哪些具體的書，可以使用GET方法請求集合資源：  
　　　　GET  http://www.example.com/books　　如果想要查看id為1000這本書的詳細資料，可以GET方法請求單本書的資源： 
　　　　GET http://www.example.com/books/1000　　如果想新增一本書，可以使用POST方法請求集合資源（假如成功後自動產生id為1001）：  
　　　　POST   http://www.example.com/books {  {'name' : ' good book'}, {'price': 100}}　　如果想修改一本書，可以使用PUT方法請求書的資源：  
　　　　PUT  http://www.example.com/books/1001  { {'price': 98} }　　如果想刪除id為1000的書，可以使用DELETE方法請求單本書的資源： 
　　　　DELETE  http://www.example.com/books/1000

  特別說明 URI中不應該包含動詞。資源表示的一種實體，應該都是名詞。只能用HTTP要求方法表示資源操作動作。

　　　　例如/posts/show/1 應該改為/posts/1  用GET方法表明是show操作。 有些難以用要求方法直接表達的動作可以換成名詞，作為服務性的資源。

　　　　例如 transfer動作   可以修改為POST /transaction  from=1&to=2&amout=100.00 URI中不應該包含版本號碼。不同的版本其實是同一種資源的不同表現層，所有應該使用同一個URI。版本號碼在HTTP要求標頭的Accept欄位中區分（參考 http://www.informit.com/articles/article.aspx?p=1566460）。

　　　　例如

　　　　　　http://www.example.com/app/1.0/foo

　　　　　　http://www.example.com/app/2.0/foo

　　　　在要求標頭中區分：

　　　　　　Accept: vnd.example-com.foo+json; version=1.0

　　　　　　Accept: vnd.example-com.foo+json; version=2.0

  三、JAX-RS

JAX-RS和所有JAVA EE的技術一樣，只提供了技術標準，允許各個廠家有自己的實現版本，實現版本有：RESTEasy(JBoss), Jersey(Sun提供的參考實現), Apache CXF, Restlet(最早的REST架構，先於JAX-RS出現), Apache Wink。JAX-RS基於JavaEE的Servlet。標準中定義的註解大大簡化資源位置和參數的描述，僅僅使用註解就可以將一個POJO java類封裝成一個Web資源。JAX-RS也有類似於Spring依賴注入的方式，減少類之間的耦合度。

 

JAX-RS標準的一個簡單RESTful Web Service樣本，例如有一個greeter的資源，URI為http://localhost:8080/greeter/

@Path("/greeter")   public class GreeterResource {    @GET    @Path("/{name}")    public String sayHello(@PathParam("name") String name) {        return "Hello, " + name;    }

    @DELETE    @Path("/{name}")    public String sayBye(@PathParam("name") String name) {        return "Bye, " + name;
    }
}

使用GET方法請求該資源 (http://localhost:8080/greeter/tom)

將得到輸出:   Hello, tom

使用DELETE方法請求該資源 (http://localhost:8080/greeter/lily)

將得到輸出： Bye, lily

 

如果把上面的資源類定義為介面， 將REST服務的定義和實現分離是一種更好的實現方式。代碼更簡潔清晰，後期修改也更方便。

 

  四、JAX-RS註解 1.資源類或方法的相對路徑註解

@Path

　　若希望一個Java類能夠處理REST請求，則這個類必須至少添加一個@Path("/")的annotation；對於方法，這個annotation是可選的，如果不添加，則繼承類的定義。

　　Path裡的值可以是複雜運算式，例如@Path("{id}")，其中的{xxx}表示一個模板參數，模板參數是定義在@Path裡的萬用字元，它以 { 開始，中間是一堆字母和數位混合串（不能包含 / 字元），以} 結尾。又如： @Path("{firstName}-{lastName}") 

　　Path也支援Regex，例如：@Path("{id: \\d+}") 

　　優先順序檢查規則（如果這樣的規則還不能解決問題，那就是設計的過於複雜了）： 首先檢查匹配的字元個數，越多越優先； 其次檢查內嵌的模板運算式個數，越多越優先； 最後檢查非預設模板運算式個數（預設模板即未定義Regex的模板）

　　     例如 /customers/{id}/{name}/address   /customers/{id : .+}/address   /customers/{id}/address   /customers/{id : .+}  

 

　　Path的字元（如果Path中的運算式包含需要轉義的字元，JAX-RS會自動進行轉義；否則會認為以及進行過URL Encoding） 　　允許a-z, A-Z, 0-9 　　允許_-!.~'()* 　　保留（需轉義）,;:$$+=?/[]@ 　　其字元都需要用%HH轉義

　

　 子資源定位器（Subresource Locators），一個指定了@Path註解但未指定HttpMethod註解的方法，該方法可以返回另一個資源類對象，讓這個對象接著分發和處理請求子資源的請求。子資源類並不需要作為服務對外暴露，所以類上可以不用加@Path註解。

@Path("/customers")public class CustomerResource {　　......　　@Path("{database}-db")　　public CustomerResource getDatabase(@PathParam("database") String db) {　　　　// find the instance based on the db parameter　　　　CustomerResource resource = locateCustomerResource(db);　　　　return resource;　　}　　protected CustomerResource locateCustomerResource(String db) {　　　　...　　}
　　......}public class CustomerResource {　　@GET　　@Path(