REST 在 Java 中的使用

UWAIS 9年前發布 | 17K 次閱讀 Java REST Java開發

REST是一種混合的架構風格。本篇主要描述一下J2EE對REST的支持。

Java是在J2EE6中引入了對REST的支持，即JSR-311(JAX-RS 1.1: The JavaTM API for RESTful Web Services)，現在JAX-RS到2.0版本了，對應的是JSR-339，JSR是Java技術規范提案，由JCP組織進行管理。該規范使得使用Java進行開發的人員使用一套固定的接口來開發 REST 應用，避免了依賴于第三方框架。JAX-RS是一套接口，具體實現由第三方提供，例如 Sun 的參考實現 Jersey、Apache 的CXF 以及 JBoss 的 RESTEasy，下文會有對它們如何發布rest服務的簡單介紹。

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屬性。

比如：

@Path("/user")
public class UserResource {
 @GET
 @Path("{userName"})
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@PathParam("userName") String userName) {
 ...
 }
}

當瀏覽器請求http://localhost:8080/root/user/boglond時，方法中userName值為boglond。

@javax.ws.rs.QueryParam 將http請求的Query參數綁定到資源方法參數，資源類的字段，或資源類的bean屬性。

eg:

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getUser")
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@QueryParam("userName") String userName,@QueryParam("age") int age) {
 ...
 }
}

當瀏覽器請求http://localhost:8080/root/user/getUser?userName=boglond&age=26時，方法中userName值為boglond，age值為26。

@javax.ws.rs.FormParam 將http請求的Form表單中的參數綁定到資源方法參數。

eg:

@Path("/user")
public class UserRecource {
 @javax.ws.rs.POST
 @Path("/insert")
 @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
 public String insertUser(@FormParam("userName") String userName,@FormParam("age") int age){
 ...
 }
}

頁面中的form表單如下

<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:

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getCookieParam")
 @Produces(MediaType.APPLICATION_JSON)
 public String getCookieParam(@CookieParam("JSESSIONID") String jsessionId) {
 ...
 }
}

當瀏覽器請求http://localhost:8080/root/user/getCookieParam時，方法中jsessionId值為”FFF7BDDC46579DBDDDEB3E94776A2623″,此值不是固定的,不同的瀏覽器有不同的值。

@javax.ws.rs.HeaderParam 將http header的值綁定到資源方法參數，資源類的字段，或資源類的bean屬性。

eg:

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getHeaderParam")
 @Produces(MediaType.APPLICATION_JSON)
 public String getHeaderParam(@HeaderParam("Accept") String accept,@HeaderParam("Accept-Language") 
  String acceptLang) {
 ...
 }
}

當瀏覽器請求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:

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getUser")
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@MatrixParam("userName") String userName,@MatrixParam("age") int age) {
 ...
 }
}

當瀏覽器請求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:

bean的配置:

@javax.xml.bind.annotation.XmlRootElement
public class UserBean{
 @FormParam("userName")
 private String userName;
 @FormParam("age")
 private int age;
 ...
}

資源類方法的配置:

@Path("/user")
public class UserRecource {
 @javax.ws.rs.POST
 @Path("/insertUserBean")
 @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
 public String insertUserBean(@BeanParam UserBeanuserBean){
 ...
 }
}

頁面中的form表單如下:

<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”})

常見的媒體類型如

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:

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getUser")
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@MatrixParam("userName") String userName,
 @MatrixParam("age") int age) {
 ...
 }
}

此時沒有使用@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等方法來指定請求的類型。

Clientclient = ClientBuilder.newClient();
client.target(..).request().get();

通過 path() 和 resolveTemplate() 方法來處理動態的 URL 路徑參數。

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:

public String getResourceContext(@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 媒體類型常量類。

avax.ws.rs.core.Cookie 在請求中轉移的HTTP Cookie的值。

eg:

Cookie c = new Cookie(name, value);
javax.ws.rs.core.Form 表示使用"application / x-www-form-urlencoded"媒體類型編碼的HTML表單數據請求實體。

eg:

Form f = new Form();
f.param(name, value)

javax.ws.rs.core.Response.Status http所定義的響應狀態碼。

javax.ws.rs.core.HttpHeaders 一個可注入的接口，提供對HTTP頭信息的訪問。

eg:

@GET
@Path("/getHttpHeaders")
@Produces(MediaType.APPLICATION_JSON)
public String getHttpHeaders(@javax.ws.rs.core.ContextHttpHeadershttpHeaders) {
...
}

@javax.ws.rs.core.UriInfo 一個可注入的接口，提供對應用程序和請求URI信息的訪問。

eg:

@GET
@Path("/getUriInfo")
@Produces(MediaType.APPLICATION_JSON)
public String getUriInfo(@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> 序列化

2.Jersey發布rest服務簡介

Jersey項目使用apache Maven構建，它的相關模塊都可從Maven中央倉庫獲取。本項目是基于JAX-RS 2.0的。

2.1 創建一個maven工程

如圖

2.2 在pom中添加依賴

<dependency>
    <groupId>javax.ws.rs</groupId>
    <artifactId>javax.ws.rs-api</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <!-- if yourcontainerimplements ServletAPIolderthan 3.0, use "jersey-container-servlet-core"  -->
    <artifactId>jersey-container-servlet</artifactId> 
    <version>2.25</version>
</dependency>

2.3 配置web.xml

在web.xml中添加

<servlet>
      <servlet-name>jersey-demo</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
      <init-param>
          <param-name>jersey.config.server.provider.packages</param-name>
          <!-- 這個包路徑換成你的包路徑,多個包路徑可以使用逗號分隔-->
          <param-value>com.boglond.jersey</param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
      <servlet-name>jersey-demo</servlet-name>
      <!-- 這個設置為你想要的路徑-->
      <url-pattern>/resources/*</url-pattern>
</servlet-mapping>

2.4 創建資源類

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getUser")
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@QueryParam("userName") String userName,
 @QueryParam("age") int age) {
 ...
 }
}

訪問:在瀏覽器里輸入http://localhost:8080/jersey-demo/resources/user/getUser?userName=boglond&age=30即可訪問。

3.CXF發布rest服務簡介

3.1 創建一個maven工程

如圖

3.2 在pom中添加依賴

CXF的依賴

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-frontend-jaxrs</artifactId>
    <version>3.0.0</version>
</dependency>      
<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-jetty</artifactId>
    <version>3.0.0</version>
</dependency>

日志的依賴

<dependency>
    <groupId>log4j</groupId>
    <artifactId>log4j</artifactId>
    <version>1.2.17</version>
</dependency>
<dependency>
 <groupId>org.slf4j</groupId>
 <artifactId>slf4j-log4j12</artifactId>
 <version>1.7.6</version>
</dependency>

3.3 創建資源類

@Path("/user")
public class UserRecource {
 @GET
 @Path("/getUser")
 @Produces(MediaType.APPLICATION_JSON)
 public UsergetUser(@QueryParam("userName") String userName,
 @QueryParam("age") int age) {
 ...
 }
}

3.4 發布REST服務

package com.boglond.cxf;
import java.util.ArrayList;
import java.util.List;
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
import org.apache.cxf.jaxrs.lifecycle.ResourceProvider;
import org.apache.cxf.jaxrs.lifecycle.SingletonResourceProvider;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class CxfServer {
  private final static Loggerlogger = LoggerFactory.getLogger(CxfServer.class);
  public static void main(String[] args) {  
    List<Class<?>> resourceClassList = new ArrayList<Class<?>>();
    resourceClassList.add(UserRecource.class);    
    List<ResourceProvider> resourceProviderList = new ArrayList<ResourceProvider>();
    resourceProviderList.add(new SingletonResourceProvider(new UserRecource()));
    // 發布 REST 服務
    JAXRSServerFactoryBeanfactory = new JAXRSServerFactoryBean();
    factory.setAddress("http://localhost:11002/cxf-demo/recources");
    factory.setResourceClasses(resourceClassList);
    factory.setResourceProviders(resourceProviderList);
    factory.create();
    logger.info("使用CXF發布REST服務成功");
  }
}

訪問:在瀏覽器里輸入http://localhost:8080/cxf-demo/recources/user/getUser?userName=boglond&age=26即可訪問。

4.RESTEasy發布rest服務簡介

4.1 創建一個maven工程

如圖

4.2 在pom中添加依賴

<dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-jaxrs</artifactId>
      <version>3.1.0.Final</version>
</dependency>
<dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-jaxb-provider</artifactId>
      <version>3.1.0.Final</version>
</dependency>
如果servlet容器使用的是servlet3.0 需要加入如下依賴
<dependency>
      <groupId>org.jboss.resteasy</groupId>
      <artifactId>resteasy-servlet-initializer</artifactId>
      <version>3.1.0.Final</version>
</dependency>

注:如果你配置的maven倉庫地址下載不下來resteasy依賴的jar,就將你的maven conf文件夾下的setting.xml 中的倉庫url替換為下面的url。<url>http://repository.jboss.org/nexus/content/groups/public/</url>

4.3 配置web.xml