什么是 RESTEasy

RESTEasy 是 JBoss 的一个开源项目，提供各种框架帮助你构建 RESTful Web Services 和 RESTful Java 应用程序。它是 JAX-RS 规范的一个完整实现并通过 JCP 认证。作为一个 JBOSS 的项目，它当然能和 JBOSS 应用服务器很好地集成在一起。但是，它也能在任何运行 JDK5 或以上版本的 Servlet 容器中运行。RESTEasy 还提供一个 RESTEasy JAX-RS 客户端调用框架，能够很方便与 EJB、Seam、Guice、Spring 和 Spring MVC 集成使用，支持在客户端与服务器端自动实现 GZIP 解压缩。

官方网站：http://resteasy.jboss.org/

特性

直接抄自官网说明：

Fully certified JAX-RS implementation
Portable to any app-server/Tomcat that runs on JDK 6 or higher
Embeddedable server implementation for junit testing
Client framework that leverages JAX-RS annotations so that you can write HTTP clients easily (JAX-RS only defines server bindings)
Client “Browser” cache. Supports HTTP 1.1 caching semantics including cache revalidation
Server in-memory cache. Local response cache. Automatically handles ETag generation and cache revalidation
Rich set of providers for: XML, JSON, YAML, Fastinfoset, Multipart, XOP, Atom, etc.
JAXB marshalling into XML, JSON, Jackson, Fastinfoset, and Atom as well as wrappers for maps, arrays, lists, and sets of JAXB Objects.
GZIP content-encoding. Automatic GZIP compression/decompression suppport in client and server frameworks
Asynchronous HTTP (Comet) abstractions for JBoss Web, Tomcat 6, and Servlet 3.0
Asynchronous Job Service.
Rich interceptor model.
OAuth2 and Distributed SSO with JBoss AS7
Digital Signature and encryption support with S/MIME and DOSETA
EJB, Seam, Guice, Spring, and Spring MVC integration

安装和配置

如果你在 Servlet3.0 容器中使用 Resteasy，则需要添加如下依赖：

<dependency><groupId>org.jboss.resteasy</groupId><artifactId>resteasy-servlet-initializer</artifactId><version>3.0.9.Final</version>
</dependency>

否则，如果你在 Servlet3.0 之前的容器中使用 Resteasy，则 WEB-INF/web.xml 中需要包括如下内容：

<servlet><servlet-name>Resteasy</servlet-name><servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class><init-param><param-name>javax.ws.rs.Application</param-name><param-value>com.restfully.shop.services.ShoppingApplication</param-value></init-param>
</servlet><servlet-mapping><servlet-name>Resteasy</servlet-name><url-pattern>/*</url-pattern>
</servlet-mapping>

另外，还可以在 <context-param> 节点配置如下参数：

resteasy.servlet.mapping.prefix
resteasy.scan
resteasy.scan.providers
resteasy.scan.resources
resteasy.providers
resteasy.use.builtin.providers
resteasy.resources
resteasy.jndi.resources
javax.ws.rs.Application
resteasy.media.type.mappings
resteasy.language.mappings
resteasy.document.expand.entity.references
resteasy.document.secure.processing.feature
resteasy.document.secure.disableDTDs
resteasy.wider.request.matching
resteasy.use.container.form.params

以上参数在需要使用的时候查阅官方文档的说明即可。

在 Servlet3.0 之前，你可以将 RESTEasy 配置为 ServletContextListener：

<listener><listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
</listener>

同样，在 Servlet3.0 之前，你可以将 RESTEasy 配置为 Servlet Filter：

<filter><filter-name>Resteasy</filter-name><filter-class>org.jboss.resteasy.plugins.server.servlet.FilterDispatcher</filter-class><init-param><param-name>javax.ws.rs.Application</param-name><param-value>com.restfully.shop.services.ShoppingApplication</param-value></init-param>
</filter><filter-mapping><filter-name>Resteasy</filter-name><url-pattern>/*</url-pattern>
</filter-mapping>

常见的注解

@Path and @GET, @POST

一个示例代码：

@Path("/library")
public class Library {@GET@Path("/books")public String getBooks() {...}@GET@Path("/book/{isbn}")public String getBook(@PathParam("isbn") String id) {// search my database and get a string representation and return it}@PUT@Path("/book/{isbn}")public void addBook(@PathParam("isbn") String id, @QueryParam("name") String name) {...}@DELETE@Path("/book/{id}")public void removeBook(@PathParam("id") String id {...}}

说明：

类或方法是存在 @Path 注解或者 HTTP 方法的注解
如果方法上没有 HTTP 方法的注解，则称为 JAXRSResourceLocators
@Path 注解支持正则表达式映射

例如：

@Path("/resources")
public class MyResource {@GET@Path("{var:.*}/stuff")public String get() {...}
}

下面的 GETs 请求会映射到 get() 方法：

GET /resources/stuff
GET /resources/foo/stuff
GET /resources/on/and/on/stuff

表达式的格式是：

"{" variable-name [ ":" regular-expression ] "}"

当正则表达式不存在时，类似于：

"([]*)"

例如， @Path("/resources/{var}/stuff")` 将会匹配下面请求：

GET /resources/foo/stuff
GET /resources/bar/stuff

而不会匹配：

GET /resources/a/bunch/of/stuff

@PathParam

@PathParam 是一个参数注解，可以将一个 URL 上的参数映射到方法的参数上，它可以映射到方法参数的类型有基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象。

例如：

@GET
@Path("/book/{isbn}")
public String getBook(@PathParam("isbn") ISBN id) {...}public class ISBN {public ISBN(String str) {...}
}

或者：

public class ISBN {public static ISBN valueOf(String isbn) {...}
}

@Path 注解中可以使用 @PathParam 注解对应的参数，例如：

@GET
@Path("/aaa{param:b+}/{many:.*}/stuff")
public String getIt(@PathParam("param") String bs, @PathParam("many") String many) {...}

对于下面的请求，对应的 param 和 many 变量如下：

另外，@PathParam 注解也可以将 URL 后面的多个参数映射到内置的 javax.ws.rs.core.PathSegment 对象，该对象定义如下：

public interface PathSegment {/*** Get the path segment.* <p>* @return the path segment*/String getPath();/*** Get a map of the matrix parameters associated with the path segment* @return the map of matrix parameters*/MultivaluedMap<String, String> getMatrixParameters();}

使用 PathSegment 作为参数类型：

@GET
@Path("/book/{id}")
public String getBook(@PathParam("id") PathSegment id) {...}

则下面请求会映射到 getBook 方法：

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

@QueryParam

对于下面的请求：

GET /books?num=5

可以使用 @QueryParam 注解进行映射：

@GET
public String getBooks(@QueryParam("num") int num) {
...
}

@HeaderParam

@HeaderParam 注解用于将 HTTP header 中参数映射到方法的调用上，例如从 http header 中获取 From 变量的值映射到 from 参数上：

@GET
public String getBooks(@HeaderParam("From") String from) {
...
}

同 PathParam 注解一样，方法的参数类型可以是基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象，例如，MediaType 对象有个 valueOf() 方法：

@PUT
public void put(@HeaderParam("Content-Type") MediaType contentType, ...)

@MatrixParam

对于 URL 中的多参数，也可以使用 @MatrixParam 注解，例如对下面的请求，

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

可以使用下面代码来处理：

@GET
public String getBook(@MatrixParam("name") String name, @MatrixParam("author") String author) {...}

@CookieParam

获取 Cookie 参数：

@GET
public String getBooks(@CookieParam("sessionid") int id) {
...
}@GET
publi cString getBooks(@CookieParam("sessionid") javax.ws.rs.core.Cookie id) {...}

同 PathParam 注解一样，方法的参数类型可以是基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象。

@FormParam

将表单中的字段映射到方法调用上，例如，对于下面的表单：

<form method="POST" action="/resources/service">
First name:
<input type="text" name="firstname">
<br>
Last name:
<input type="text" name="lastname">
</form>

通过 post 方法提交，处理该请求的方法为：

@Path("/")
public class NameRegistry {@Path("/resources/service")@POSTpublic void addName(@FormParam("firstname") String first, @FormParam("lastname") String last) {...}
}

你也可以添加 application/x-www-form-urlencoded 来反序列化 URL 中的多参数：

@Path("/")
public class NameRegistry {@Path("/resources/service")@POST@Consumes("application/x-www-form-urlencoded")public void addName(@FormParam("firstname") String first, MultivaluedMap<String, String> form) {...}
}

@Form

@FormParam 只是将表单字段绑定到方法的参数上，而 @Form 可以将表单绑定到一个对象上。

例如：

public static class Person{@FormParam("name")private String name;@Form(prefix = "invoice")private Address invoice;@Form(prefix = "shipping")private Address shipping;
}public static class Address{@FormParam("street")private String street;
}@Path("person")
public static class MyResource{@POST@Produces(MediaType.TEXT_PLAIN)@Consumes(MediaType.APPLICATION_FORM_URLENCODED)public String post(@Form Person p){return p.toString();}}

客户端可以提交下面的参数：

name=bill
invoice.street=xxx
shipping.street=yyy

public static class Person {@Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;@Form(prefix="address") Map<String, Address> addresses;
}public static class TelephoneNumber {@FormParam("countryCode") private String countryCode;@FormParam("number") private String number;
}public static class Address {@FormParam("street") private String street;@FormParam("houseNumber") private String houseNumber;
}@Path("person")
public static class MyResource {@POST@Consumes(MediaType.APPLICATION_FORM_URLENCODED)public void post (@Form Person p) {}
}

然后，提交下面的参数：

request.addFormHeader("telephoneNumbers[0].countryCode", "31");
request.addFormHeader("telephoneNumbers[0].number", "0612345678");
request.addFormHeader("telephoneNumbers[1].countryCode", "91");
request.addFormHeader("telephoneNumbers[1].number", "9717738723");
request.addFormHeader("address[INVOICE].street", "Main Street");
request.addFormHeader("address[INVOICE].houseNumber", "2");
request.addFormHeader("address[SHIPPING].street", "Square One");
request.addFormHeader("address[SHIPPING].houseNumber", "13");

@DefaultValue

用于设置默认值。

@GET
public String getBooks(@QueryParam("num") @DefaultValue("10") int num) {...}

@Encoded 和 @Encoding

对 @*Params 注解的参数进行编解码。

@Context

该注解允许你将以下对象注入到一个实例：

javax.ws.rs.core.HttpHeaders,
javax.ws.rs.core.UriInfo
javax.ws.rs.core.Request
javax.servlet.HttpServletRequest
javax.servlet.HttpServletResponse
javax.servlet.ServletConfig
javax.servlet.ServletContext
javax.ws.rs.core.SecurityContext

@Produces 和 @Consumes

@Consumes 注解定义对应的方法处理的 content-type 请求类型。

@Consumes("text/*")
@Path("/library")
public class Library {@POSTpublic String stringBook(String book) {...}@Consumes("text/xml")@POSTpublic String jaxbBook(Book book) {...}
}

当客户端发送下面请求时，stringBook() 方法会调用：

 POST /librarycontent-type: text/plainthsi sis anice book

@Produces 用于映射客户端的请求并匹配客户端请求的 Accept header。

例如，对下面的代码：

@Produces("text/*")
@Path("/library")
public class Library {@GET@Produces("application/json")public String getJSON() {...}@GETpublic String get() {...}
}

则，客户端发送下面请求时，getJSON() 会被调用。

GET /library
Accept: application/json

可以修改 web.xml 中的配置，对 Accept 和 Accept-Language 做一些映射。例如：

<web-app><display-name>Archetype Created Web Application</display-name><context-param><param-name>resteasy.media.type.mappings</param-name><param-value>html : text/html, json : application/json, xml : application/xml</param-value></context-param><context-param><param-name>resteasy.language.mappings</param-name><param-value>en : en-US, es : es, fr : fr</param-value></context-param><servlet><servlet-name>Resteasy</servlet-name><servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class></servlet><servlet-mapping><servlet-name>Resteasy</servlet-name><url-pattern>/*</url-pattern></servlet-mapping>
</web-app>

然后，可以通过调用 http://service.foo.com/resouce?someName=application/xml 来得到一个 application/xml 的返回结果。

@GZIP

配置请求输出内容为 Gzip 压缩，例如：

@Path("/")
public interface MyProxy {@Consumes("application/xml")@PUTpublic void put(@GZIP Order order);
}

JAX-RS Resource Locators and Sub Resources

前面提到当方法上只有 @Path 注解没有 HTTP 方法的注解时，则该方法为资源定位器，该方法可以返回一个子资源，然后由资源来定义映射路径和对应的 HTTP 方法。

例如：

@Path("/")
public class ShoppingStore {@Path("/customers/{id}")public Customer getCustomer(@PathParam("id") int id) {Customer cust = ...; // Find a customer objectreturn cust;}
}public class Customer {@GETpublic String get() {...}@Path("/address")public String getAddress() {...}}public class CorporateCustomer extends Customer {@Path("/businessAddress")public String getAddress() {...}
}

访问下面的请求时，会调用 ShoppingStore 类的 getCustomer 方法，然后调用 Customer 类的 get() 方法。

GET /customer/123

类似地，下面的请求会返回 Customer 类的 getAddress() 方法的值。

GET /customer/123/address

CORS

在 Application 类中，注册一个单例的提供者类：

CorsFilter filter = new CorsFilter();
filter.getAllowedOrigins().add("http://localhost");

Content-Range Support

@Path("/")
public class Resource {@GET@Path("file")@Produces("text/plain")public File getFile(){return file;}
}Response response = client.target(generateURL("/file")).request().header("Range", "1-4").get();
Assert.assertEquals(response.getStatus(), 206);
Assert.assertEquals(4, response.getLength());
System.out.println("Content-Range: " + response.getHeaderString("Content-Range"));

快速了解RESTEasy相关推荐

resteasy_Tomcat 7上具有RESTeasy JAX-RS的RESTful Web服务– Eclipse和Maven项目
resteasy 开发Web服务的RESTful方法不断受到越来越多的关注,并且似乎正在将SOAP淘汰. 我不会讨论哪种方法更好,但是我相信我们都同意REST更轻量级. 在本教程中,我将向您展示如何使 ...
Tomcat 7上具有RESTeasy JAX-RS的RESTful Web服务-Eclipse和Maven项目
开发Web服务的RESTful方法不断受到越来越多的关注,并且似乎正在将SOAP淘汰. 我不会讨论哪种方法更好,但是我相信我们都同意REST更轻量级. 在本教程中,我将向您展示如何使用RESTeasy ...
swagger使用教程——快速使用swagger
Swagger使用教程--快速上手swagger 一.swagger简介官网:https://swagger.io/ 1.认识swagger swagger是一个规范和完整的框架,用于生成.描述.调 ...
快速启动Keycloak
目录下载启动包keycloak-15.0.2.zip 启动keycloak 创建admin用户登录控制台新建realm 新建用户新建client 测试client登录设置client为con ...
RestEasy的入门与使用
文章目录 RestEasy的入门与使用背景传统Servlet JAX-RS和JSR 为什么要看规范? 简单解读JSR370 Applications Resources Providers Res ...
快速排查feign.FeignException: status 500 …
feign.FeignException: status 500 - 总结一下feign报500的时候快速排查问题的方法, 这个bug容易出现的地方分别为: 1. 远程调用的时候feign的注册信息有 ...
python中如何对复杂的json数据快速查找key对应的value值（使用JsonSearch包）
前言之前在实际的项目研发中,需要对一些复杂的json数据进行取值操作,由于json数据的层级很深,所以经常取值的代码会变成类似这样: value = data['store']['book'][0] ...
如何利用python的newspaper包快速爬取网页数据
文章目录前言一个爬取新闻网页数据的神器小试牛刀如何快速安装 windows安装 Debian / Ubuntu安装 OSX安装体验更多的功能前言随着越来的进行自然语言处理相关方面的研究, ...
【快速上手mac必备】常用优质mac软件推荐(音视频、办公、软件开发、辅助工具、系统管理、云存储)
本文章的主要内容是我作为一名大四学生.准程序员.up主这三种身份来给大家推荐一下 mac 上好用的软件以及工具.本人也是从去年9月份开始从windows阵营转移到了mac阵营,刚开始使用的时候,也曾主 ...

快速了解RESTEasy