rest註解說明及使用示例（java）
1.常用API介紹
1.1 javax.ws.rs包(用於建立RESTful服務資源的高階介面和註解)
1.1.1 統一介面
JAX-RS使用@javax.ws.rs.POST 、@javax.ws.rs.GET 、@javax.ws.rs.PUT、@javax.ws.rs.DELETE四個註解代表了對資源的CRUD(Create, Retrieve, Update, Delete)操作。
1.1.2 定位資源
注:下文中url中的root代表你的web應用的名稱加上你在web.xml中servlet-mapping元素設定的路徑。
@javax.ws.rs.ApplicationPath 標識應用路徑，用於由@Path提供的所有資源uri的基本uri。當釋出在一個servlet容器中，它的值可以使用web.xml中的servlet-mapping進行重寫。
@javax.ws.rs.Path 標識要請求的資源類或類方法的uri路徑。
@javax.ws.rs.PathParam 將uri中指定的路徑引數繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
比如：
| 1 2 3 4 5 6 7 8 9 |
@Path("/user")
publicclassUserResource{
@GET
@Path("{userName}")
@Produces(MediaType.APPLICATION_JSON)
publicUsergetUser(@PathParam("userName")StringuserName){
... |
當瀏覽器請求http://localhost:8080/root/user/boglond時，方法中userName值為boglond。
@javax.ws.rs.QueryParam 將http請求的Query引數繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
| 1 2 3 4 5 6 7 8 9 |
@Path("/user")
publicclassUserRecource{
@GET
@Path("/getUser")
@Produces(MediaType.APPLICATION_JSON)
publicUsergetUser(@QueryParam |
當瀏覽器請求http://localhost:8080/root/user/getUser?userName=boglond&age=26時，方法中userName值為boglond，age值為26。
@javax.ws.rs.FormParam 將http請求的Form表單中的引數繫結到資源方法引數。
eg:
| 1 2 3 4 5 6 7 8 9 | @Path("/user") publicclassUserRecource{ @javax.ws.rs.POST @Path("/insert") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) publicStringinsertUser(@FormParam("userName")StringuserName,@FormParam("age")intage){ ... } } |
頁面中的form表單如下
| 1 2 3 4 5 | <formaction="/root/user/insert"method="post"> 姓名:<inputname="userName"id="userName"type="text"value="boglond"/></br> 年齡:<inputname="age"id="age"type="text"value="26"/> <buttontype="submit">提交</button> </form> |
提交表單後方法中userName值為boglond，age值為26。
@javax.ws.rs.CookieParam 將http cookie的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
| 1 2 3 4 5 6 7 8 9 | @Path("/user") publicclassUserRecource{ @GET @Path("/getCookieParam") @Produces(MediaType.APPLICATION_JSON) publicStringgetCookieParam(@CookieParam("JSESSIONID")StringjsessionId){ ... } } |
當瀏覽器請求http://localhost:8080/root/user/getCookieParam時，方法中jsessionId值為”FFF7BDDC46579DBDDDEB3E94776A2623″,此值不是固定的,不同的瀏覽器有不同的值。
@javax.ws.rs.HeaderParam 將http header的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
| 1 2 3 4 5 6 7 8 9 10 | @Path("/user") publicclassUserRecource{ @GET @Path("/getHeaderParam") @Produces(MediaType.APPLICATION_JSON) publicStringgetHeaderParam(@HeaderParam("Accept")Stringaccept,@HeaderParam("Accept-Language") StringacceptLang){ ... } } |
當瀏覽器請求http://localhost:8080/root/user/getHeaderParam時，方法中accept值為”text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8″，acceptLang值為”zh-CN,zh;q=0.8,en-US;q=0.5,en;q=0.3″，不同的瀏覽器，值有所不同。
@javax.ws.rs.MatrixParam 將uri矩陣引數的值繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
| 1 2 3 4 5 6 7 8 9 | @Path("/user") publicclassUserRecource{ @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) publicUsergetUser(@MatrixParam("userName")StringuserName,@MatrixParam("age")intage){ ... } } |
當瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond;age=26時，方法中userName值為boglond，age值為26。
@javax.ws.rs.DefaultValue 設定 @PathParam, @QueryParam, @MatrixParam, @CookieParam, @FormParam, or @HeaderParam引數的預設值。如果它們沒有接收到值，就使用預設值。
@javax.ws.rs.BeanParam 將請求中的bean繫結到資源方法引數，資源類的欄位，或資源類的bean屬性。
eg:
| 1 2 3 4 5 6 7 8 | @javax.xml.bind.annotation.XmlRootElement publicclassUserBean{ @FormParam("userName") privateStringuserName; @FormParam("age") privateintage; ... } |
| 1 2 3 4 5 6 7 8 9 | @Path("/user") publicclassUserRecource{ @javax.ws.rs.POST @Path("/insertUserBean") @Consumes(MediaType.APPLICATION_FORM_URLENCODED) publicStringinsertUserBean(@BeanParamUserBeanuserBean){ ... } } |
頁面中的form表單如下:
| 1 2 3 4 5 | <formaction="/root/user/insertUserBean"method="post"> 姓名:<inputname="userName"id="userName"type="text"value="boglond"/></br> 年齡:<inputname="age"id="age"type="text"value="26"/> <buttontype="submit">提交</button> </form> |
當提交表單後insertUserBean方法中的userBean物件的屬性值會對映為表單中對應的值。
1.1.3 表述資源的資料格式(通過媒體型別表述)
@javax.ws.rs.Consumes 定義一個資源類的方法或MessageBodyReader能夠接受的媒體型別。方法級別的@Consumes會覆蓋類級別的@Consumes。(指定將要返回給client端的資料MIME型別)
@javax.ws.rs.Produces 定義一個資源類的方法或MessageBodyWriter能夠產生的媒體型別。方法級別的@Produces會覆蓋類級別的@Produces。(指定可以接受client傳送過來的MIME型別)
eg:@Produces(“application/json”);指定多個MIME型別 @Produces({“application/json”,”application/xml”})
常見的媒體型別如
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | text/html：HTML格式 text/plain：純文字格式 text/xml：XML格式(它會忽略xml頭所指定編碼格式而預設採用us-ascii編碼) image/gif：gif圖片格式 image/jpeg：jpg圖片格式 image/png：png圖片格式 application/xhtml+xml：XHTML格式 application/xml：XML格式(它會根據xml頭指定的編碼格式來編碼) application/atom+xml：AtomXML聚合格式 application/json：JSON資料格式 application/pdf：pdf格式 application/msword：Word文件格式 application/octet-stream：二進位制流資料（如常見的檔案下載） application/x-www-form-urlencoded：<formencType=””>中預設的encType，form表單資料被編碼為key/value格式傳送到伺服器（表單預設的提交資料的格式） multipart/form-data：需要在表單中進行檔案上傳時，就需要使用該格式。 |
媒體型別的常量值在javax.ws.rs.core.MediaType中。
1.1.4 編解碼
@javax.ws.rs.Encoded 禁用由 @QueryParam, @PathParam, @FormParam or @MatrixParam繫結的引數值的自動解碼
eg:
| 1 2 3 4 5 6 7 8 9 10 | @Path("/user") publicclassUserRecource{ @GET @Path("/getUser") @Produces(MediaType.APPLICATION_JSON) publicUsergetUser(@MatrixParam("userName")StringuserName, @MatrixParam("age")intage){ ... } } |
此時沒有使用@Encoded
當瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond%5CD;age=26時,方法中userName值為boglond\D，age值為26。
當給方法引數加上@Encoded時,
瀏覽器請求http://localhost:8080/root/user/getUser;userName=boglond%5CD;age=26,方法中userName值為boglond%5CD，age值為26。
@Encoded可加在方法的上面禁用此方法所有引數的自動解碼。
1.2 javax.ws.rs.client包(JAX-RS客戶端API)
javax.ws.rs.client.WebTarget 由資源URI標識的資源目標。
javax.ws.rs.client.ClientBuilder 用於載入客戶端例項的主入口點。
eg:使用 request() 函式來初始化一個請求並用後續的 post 或者get等方法來指定請求的型別。
| 1 2 | Clientclient=ClientBuilder.newClient(); client.target(..).request().get(); |
通過 path() 和 resolveTemplate() 方法來處理動態的 URL 路徑引數。
| 1 2 3 4 | client.target(..).path(..).resolveTemplate(..); javax.ws.rs.client.InvocationCallback<RESPONSE>可以實現從呼叫處理接收非同步處理事件。 javax.ws.rs.client.ClientRequestFilter客戶端請求過濾器。 javax.ws.rs.client.ClientResponseFilter客戶端響應過濾器。 |
1.3 javax.ws.rs.container包(特定容器JAX-RS API )
@javax.ws.rs.container.ResourceContext 提供對資源類例項的訪問,使用@javax.ws.rs.core.Context 注入。
eg:
| 1 2 3 | publicStringgetResourceContext(@javax.ws.rs.core.ContextResourceContextresourceContext){ ... } |
@javax.ws.rs.container.ContainerRequestContext 容器請求過濾器上下文。為過濾器提供特定於請求的資訊的可變類，例如請求URI，訊息頭，訊息實體或請求範圍屬性。暴露的setter方法允許修改暴露的請求特定資訊。
@javax.ws.rs.container.ContainerResponseContext 容器響應過濾器上下文。為過濾器提供特定於響應的資訊的可變類，例如訊息頭，訊息實體或請求範圍屬性。暴露的setter方法允許修改暴露的響應特定資訊。
1.4 javax.ws.rs.core包(用於建立RESTful服務資源的低階介面和註解)
@javax.ws.rs.core.MediaType 媒體型別常量類。
j
avax.ws.rs.core.Cookie 在請求中轉移的HTTP Cookie的值。
eg:
| 1 2 | Cookiec=newCookie(name,value); javax.ws.rs.core.Form表示使用"application / x-www-form-urlencoded"媒體型別編碼的HTML表單資料請求實體。 |
eg:
| 1 2 | Formf=newForm(); f.param(name,value) |
javax.ws.rs.core.Response.Status http所定義的響應狀態碼。
javax.ws.rs.core.HttpHeaders 一個可注入的介面，提供對HTTP頭資訊的訪問。
eg:
| 1 2 3 4 5 6 | @GET @Path("/getHttpHeaders") @Produces(MediaType.APPLICATION_JSON) publicStringgetHttpHeaders(@javax.ws.rs.core.ContextHttpHeadershttpHeaders){ ... } |
@javax.ws.rs.core.UriInfo 一個可注入的介面，提供對應用程式和請求URI資訊的訪問。
eg:
| 1 2 3 4 5 6 | @GET @Path("/getUriInfo") @Produces(MediaType.APPLICATION_JSON) publicStringgetUriInfo(@javax.ws.rs.core.ContextUriInfouriInfo){ ... } |
@javax.ws.rs.core.Context 將資訊注入類欄位，bean屬性或方法引數。如
1.5 javax.ws.rs.ext包(為JAX-RS API支援的型別提供擴充套件)
javax.ws.rs.ext.MessageBodyReader<T> 反序列化
javax.ws.rs.ext.MessageBodyWriter<T> 序列化
來源：http://blog.jobbole.com/109031/