表征狀態(tài)傳輸(Representational State Transfer(REST) )是一個軟件架構(gòu)風(fēng)格，該架構(gòu)圍繞Http協(xié)議上數(shù)據(jù)的傳輸，使用http的那四個謂詞：get,put,serice.delete.這個架構(gòu)也避免了 對諸如：SOAP envelope這樣的附加包裝器的使用以及任何狀態(tài)數(shù)據(jù)的使用。

概要：REST是一個架構(gòu)風(fēng)格，首次在一個博士論文中被描述，該博士是Roy Fielding。在RESTful系統(tǒng)中，服務(wù)器利用URI暴露資源，客戶端使用四個Http謂詞來訪問資源。由于客戶端接收了資源，他們被置于某種狀 態(tài)。當(dāng)他們訪問一個新的資源，通常是點擊下一個連接，他們改變了，或者說是過渡了他們的狀態(tài)。為了工作，REST假設(shè)資源是能夠使用普遍的標(biāo)準(zhǔn)語法來代表 的。

3W網(wǎng)絡(luò)是最普及的例子，他是最大的基于REST策略構(gòu)建的系統(tǒng)。web瀏覽器作為客戶端訪問駐留在web服務(wù)器上的資源。資源通過HTML或者xml體現(xiàn)，所有的web瀏覽器可以消費它。瀏覽器可以很容易的根據(jù)連接跳轉(zhuǎn)到新的資源上面。

RESTful系統(tǒng)的優(yōu)勢在于他們可以高伸縮性和高靈活性。因為被訪問和操作的資源是通過http謂詞。資源通過URI被暴露，資源被通過標(biāo)準(zhǔn)的語 法體現(xiàn)，客戶端不會被服務(wù)器所影響。也就是說，RESTFul系統(tǒng)可以充分體現(xiàn)http的可伸縮性特性，比如：緩存和代理特性。

基礎(chǔ)REST策略：RESTful架構(gòu)堅持下面的基本原則：

• 應(yīng)用程序狀態(tài)和功能被分離到不同資源中。
• 資源是可以定位的通過標(biāo)準(zhǔn)URLs,并且這個URLs可以作為超媒體連接。
• 所有資源可以被http謂詞所使用：delete,get,post,put
• 所有資源提供信息通過MIME類型（該類型被HTTP支持）
• 協(xié)議是無狀態(tài)的
• 協(xié)議是可緩存的
• 協(xié)議是分層的

資源：資源是REST的中心，一個資源是信息源，可以被URI來標(biāo)注的。在web的早期，資源是大量的靜態(tài)文檔，在當(dāng)下，一個資源可以是任何信息源，例如web Service可以是一個資源如果他能夠通過一個URI來被訪問。

RESTful端點交換他們代表的資源。一個代表可以使一個包含了數(shù)據(jù)的文檔。例如：web Service的方法提供了訪問客戶的記錄，那么該方法就是資源，在服務(wù)和消費者之間傳輸?shù)目蛻粜畔⒖截悾彩琴Y源的代表。

REST最佳實踐：當(dāng)設(shè)計一個RESTful服務(wù)時，最佳實踐有如下幫助：

• 提供一個不一樣的URI給每個你希望暴露的資源。

        例如：如果你在建立一個系統(tǒng)，該系統(tǒng)處理駕駛記錄，每個記錄將有個唯一的URI，如果這個系統(tǒng)提供違規(guī)停車和超速罰款記錄，每個資源的類型應(yīng)該也有一個唯一的基準(zhǔn)。例如：超速罰款應(yīng)該通過/speedingfines/driverID來訪問，而違規(guī)停車應(yīng)該通過/parkingfines/driverID來訪問。

• 在URIs中使用聲明：使用nouns突出顯示資源是事情而不是動作這件事實。URLs諸如：/ordering隱喻了行為，而/orders隱喻了事情
• get對應(yīng)的方法應(yīng)該不去改變?nèi)魏螖?shù)據(jù)。
• 在應(yīng)答里使用鏈接：

          放入去向別的資源的鏈接到應(yīng)答里，可以使客戶端跟從一個數(shù)據(jù)鏈變得容易。例如，如果你的服務(wù)返回一個資源集合，對于客戶單來說，更容易訪問每個獨立的資 源，使用提供的連接，如果連接不被包含在response里面，客戶端需要附加的邏輯來跟從這個去向特定節(jié)點的連接。

• 使服務(wù)無狀態(tài)

         需要客戶端或者服務(wù)端維護狀態(tài)信息，導(dǎo)致兩者的緊耦合，緊耦合會讓升級和遷移變得更困難。維護狀態(tài)也會使從通信錯誤中還原狀態(tài)變得更麻煩。

設(shè)計一個RESTful web Service:

         要執(zhí)行以下步驟：

1. 定義服務(wù)將要暴露的資源：通常，一個服務(wù)將暴露一個或多個資源，這些資源會組織成一個樹，例如：一個駕駛記錄服務(wù)被組織成三個資 源：/license/driverID ,/license/driverID/speedingfines,/license/driverID/parkingfines
2. 定義在每個資源上執(zhí)行的動作，例如：你可能想更新駕駛員地址或者刪除停車罰單從一個駕駛員記錄中。
3. 映射行為到何時的http謂詞。

一旦你定義好了服務(wù)，你就可以使用FUSE Services Framework去實現(xiàn)它了。

采用Fuse Services Framework實現(xiàn)REST

           FSF提供RESTful Web Service的java API的實現(xiàn)。JAX-RS提供標(biāo)準(zhǔn)的方式去映射POJO到資源中去，使用annotations。

當(dāng)從一個抽象的服務(wù)定義轉(zhuǎn)移到使用JAX-RS實現(xiàn)RESTFul Web Services實現(xiàn)，你需要做：

    1.創(chuàng)建根資源類給資源，該根資源類代表了服務(wù)資源樹的頂端。

    2.映射服務(wù)的其他資源到樹的子資源節(jié)點上。

    3.創(chuàng)建方法來實現(xiàn)每個http謂詞。

Data bindings：

        默認(rèn)情況下，F(xiàn)SF使用JAXB對象來映射資源與他的java object。提供清晰，定義良好的映射，在對象和xml元素之間。

      FSF實現(xiàn)也支持交換數(shù)據(jù)采用JSON，JSON是一種被Ajax開發(fā)者廣泛使用的數(shù)據(jù)格式。在json和jaxb之間數(shù)據(jù)的編組被FSF運行時動態(tài)處理。

chapter2：創(chuàng)建資源

在RESTFul web Service中，所有的請求被資源所處理。JAX-RS API上實現(xiàn)了將資源看成java類。一個資源類是一個Java類，他被一個或多個RAX-RS注解所標(biāo)注。用JAX-RS實現(xiàn)的一個RESTFul web Service的核心是一個根資源類。根資源類是被暴露的服務(wù)的資源樹的入口點。他可以自己處理所有的請求，或者他可以提供對子起源的訪問通道。

 介紹：使用JAX-RS APIs實現(xiàn)的RESTFul WEb Services提供應(yīng)答作為資源代表，該代表實現(xiàn)了java類。一個資源類是一個類，該類使用了JAX-RS注解來實現(xiàn)一個資源。對于大多數(shù) RESTful web services來說，他就是一個需要被訪問的資源集合。資源類的注解提供了信息諸如：資源的URI和每個操作處理的謂詞。

資源類型：JAX-RS APIs允許你創(chuàng)建兩個基本類型的資源：

• 根資源類：是服務(wù)資源樹的入口點，他被裝飾（用@path注解），用以定義服務(wù)中資源的基準(zhǔn)URI。
• 子資源：通過根資源來訪問的資源，他們被裝飾了@path注解的方法所實現(xiàn)。一個子資源的@path注解定義了相對于基準(zhǔn)URI的路徑。

例子：簡單資源類：

package demo.jaxrs.server;  import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.PathParam;  @Path("/customerservice")  public class CustomerService {   public CustomerService()   {   }    @GET    public Customer getCustomer(@QueryParam("id") String id)   {     ...   }    ... }

基本的JAX-RS 注解
 

概述：

RESTful web service實現(xiàn)最最基本的信息片是：

• 服務(wù)資源的URI
• 一個class的方法如何被映射到http謂詞上。

JAX-RS定義了一組注解來提供基本的信息。所有的資源類必須有至少一個注解。

設(shè)置路徑：

@path注解指明了一個資源的URI，該注解定義在Javax.ws.rs.Path接口中。它既可以用來包裝一個資源類，也可以用來包裝一個資 源的方法。它用一個字符串作為唯一參數(shù)（可參看上面的代碼）。該字符串是一個URI的形式，指明了被實現(xiàn)資源的location。

URI模板指明了資源的相對路徑，如下所示：模板包括

• 未處理的路徑組件
• 被{}包圍的參數(shù)指示符：參數(shù)指示符可以包括通常的表達式來替換缺省的路徑

@Path("resourceName/{param1}/../{paramN}")

例如：URI模板：widgets/{color}/{number}將映射到widgets/blue/12.參數(shù)color的值是blue,number參數(shù)的值是12.

URI模板怎樣映射到一個完整的URI，依賴于@Path注解包裝的是什么東東，如果@path在根資源類中（注解包裝的是根資源類），那么URI模板是所有資源的根URI,并且他被直接添加到服務(wù)發(fā)布的URI中。如果注解是封裝一個子資源類，它將相對于根資源的URI。

指定HTTP 謂詞：JAX-RS使用五個注解來指定http謂詞，這些謂詞使用在方法上。

• javax.ws.rs.DELETE指明了方法映射到DELETE
• javax.ws.rs.GET指明方法映射到GET
• javax.ws.rs.POST指明方法映射到post
• javax.ws.rs.PUT指明方法映射到put
• javax.ws.rs.HEAD指明方法映射到HEAD

當(dāng)映射方法到http謂詞，你必須確保映射是有意義的。例如，入股你映射一個要提交訂單的方法，你應(yīng)當(dāng)映射他到一個put或者post謂詞。如果映射它到一個get或者delete謂詞，將導(dǎo)致不可以預(yù)計的情況發(fā)生。

根資源類：

概述：根資源類是一個JAX-RS實現(xiàn)的RESTful服務(wù)的入口點，它被@path包裝，指示出組成服務(wù)的所有資源的根URI。他的方法直接實現(xiàn)在資源上的操作或者提供一個訪問其他子資源的通道。

需求：一個類為了成為根資源類，它必須符合下面的規(guī)則：

• 類必須被@path包裝

         指定的路徑是根URI對于所有實現(xiàn)服務(wù)的資源來說。如果根資源類指明它的路徑是wiggets并且一個方法實現(xiàn)了GET謂詞，然后一個在wedgets上 的GET調(diào)用將調(diào)用該方法。如果子資源指明了他的URI是{id},那么完整的URI模板對于子資源來說，就是widgets/{id}，并且他將處理形 如widgets/12和widgets/42這樣的請求。

• 類必須有一個公用的構(gòu)造器用于運行時被調(diào)用

        運行環(huán)境必須能夠提供構(gòu)造器所需的所有參數(shù)。構(gòu)造器的參數(shù)可以包括被JAX-RS參數(shù)注解包裝的參數(shù)。

• 至少有一個類方法必須被HTTP謂詞注解所包裝或者被@path所包裝

下例現(xiàn)實了一個根資源類提供一個訪問子資源類的通道：

package demo.jaxrs.server;  import javax.ws.rs.DELETE; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.PUT; import javax.ws.rs.Path; import javax.ws.rs.PathParam; import javax.ws.rs.QueryParam; import javax.ws.rs.core.Response;  @Path("/customerservice/")  public class CustomerService {   public CustomerService()    {     ...   }    @GET    public Customer getCustomer(@QueryParam("id") String id)   {     ...   }    @DELETE   public Response deleteCustomer(@QueryParam("id") String id)   {     ...   }    @PUT   public Response updateCustomer(Customer customer)   {     ...   }    @POST   public Response addCustomer(Customer customer)   {     ...   }    @Path("/orders/{orderId}/")    public Order getOrder(@PathParam("orderId") String orderId)   {     ...   }  }

resource 方法的工作原理
 

概述：資源方法被JAX-RS注解所注釋。他們有HTTP方法注解之一來指明方法處理哪種類型的請求，JAX-RS放置了約束在資源方法上。

普通約束：所有的資源方法必須符合以下條件

• 必須是public的
• 必須被HTTP方法注解所包裝
• 不能有多于一個的實體參數(shù)

參數(shù)：資源方法參數(shù)采取兩種形式：

• 實體參數(shù)-實體參數(shù)是無注解的，他們的值和request的body對應(yīng)，一個實體參數(shù)可以使任意類型的，所以應(yīng)用城西得有一個實體提供器。通常是JAXB對象。
• 被注解的參數(shù)：被注解的參數(shù)使用一個JAX-RS注解來指明參數(shù)值是如何映射到請求的。通常，參數(shù)值映射的是request URI的一部分。

如下例：實現(xiàn)了一個資源方法，它具有有效的參數(shù)列

@POST @Path("disaster/monster/giant/{id}") public void addDaikaiju(Kaiju kaiju,                         @PathParam("id") String id) {   ... }

如下例，實現(xiàn)了一個資源方法，他具有無效的參數(shù)列
 

@POST @Path("disaster/monster/giant/") public void addDaikaiju(Kaiju kaiju,                         String id) {   ... }

返回值：資源方法可以返回以下類型的值

• void
• 任何java class：如果是返回javaclass，那么應(yīng)用程序必然有一個實體提供者。
• 一個Response。
• 一個GenericEntity<T>類型的對象

所有的資源方法返回一個HTTP狀態(tài)代碼給請求端。當(dāng)方法的返回類型是void或者返回值是null時，資源方法設(shè)置狀態(tài)代碼為200，當(dāng)資源方法返回值不是null，它設(shè)置狀態(tài)值為204.

子資源的工作原理

概述：實際情況下，一個服務(wù)要處理很多資源。例如，在一個訂單處理服務(wù)的最佳實踐中，支持每個客戶作為唯一資源來被處理，每個訂單也作為唯一資源來被處理。

使用JAX-RS APIs，可以將客戶資源和訂單資源作為子資源來處理。一個子資源就是要通過根資源才能訪問的資源。通過增加@path注解到一個類方法來定義一個資源是子資源。子資源可以由兩條途徑來實現(xiàn)：

• 子資源方法-直接實現(xiàn)一個http謂詞，被一個注解所包裝
• 子資源定位-只想一個實現(xiàn)子資源的類

說明子資源：子資源通過用@path包裝一個方法來指明。子資源的URI結(jié)構(gòu)如下：

1.追加子資源的@path注解值到子資源的父資源的@path注解值后面。

   父資源的@path注解也許被找到在資源類的一個方法哪里，該方法返回一個對象，該對象包含了子資源。

2.重復(fù)前面的步驟直到根資源被觸及。

3.被組裝的URI被追加到基準(zhǔn)URI上。

@Conumes 和 @Produces

@Consumes 注釋代表的是一個資源可以接受的 MIME 類型。@Produces 注釋代表的是一個資源可以返回的 MIME 類型。這些注釋均可在資源、資源方法、子資源方法、子資源定位器或子資源內(nèi)找到。

 @Consumes("application/json")   @Produces("application/json")