快速了解RESTEasy

什么是 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) {...}


@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) {

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" 

Last name: 

 input type="text" name="lastname" 

 /form 

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

@Path("/")

public class NameRegistry {

 @Path("/resources/service")

 @POST

 public 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

另外，也可以设置 prefix 参数，映射到 map 和 list：

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 {

 @POST

 public String stringBook(String book) {...}

 @Consumes("text/xml")

 @POST

 public String jaxbBook(Book book) {...}

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

 POST /library

 content-type: text/plain

 thsi sis anice book

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

POST /library

content-type: text/xml

 book name="EJB 3.0" author="Bill Burke"/ 

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

例如，对下面的代码：

@Produces("text/*")

@Path("/library")

public class Library {

 @GET

 @Produces("application/json")

 public String getJSON() {...}

 @GET

 public 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 

如果你调用 /foo/bar.xml.en 的 GET 请求，则等同于发送下面的请求：

GET /foo/bar

Accept: application/xml

Accept-Language: en-US

另外，你也可以设置参数映射，通过参数指定 content-type。修改 web.xml：

 web-app 

 display-name Archetype Created Web Application /display-name 

 context-param 

 param-name resteasy.media.type.param.mapping /param-name 

 param-value someName /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")

 @PUT

 public 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 object

 return cust;

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

GET /customer/123

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

GET /customer/123/address

在 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"));

Jersey 2.x Glassfish 中基于 Servlet 的应用 如果你使用的是 Glassfish 作为你应用服务器，你不需要在你的引用中包含引用任何东西，所有你需要的都已经包含进去了。 你只需要定义 JAX-RS API 以便于你能够对你的应用进行编辑，使用 （provided）依赖。
Spring Cloud是当前炙手可热的微服务开发框架。它的功能强大，组件丰富，设计优雅。目前Spring Cloud还在不断发展之中。 Spring Cloud即将发布Spring Cloud Edgware 版本。
Spring+CXF+Maven发布Webservice 使用CXF发布WebService简单又快速，还可以与Spring集成，当Web容器启动时一起发布WebService服务。本例是简单的客户端给服务端发送订单信息，服务端返回订单转为json的字符串。 1.使用maven管理jar包，首先在maven添加使用到的cxf jar包依赖,到CXF官网上找到Maven的依赖内容。
前段时间一直在做公司的微服务项目，技术栈主要是Spring Boot+Thrift，感觉使用Spring Boot确实太方便了： 1. 无xml配置。
JAX-RS(基于Jersey) + Spring 4.x + MyBatis构建REST服务架构 0. 大背景 众所周知，REST架构已经成为现代服务端的趋势。 很多公司，已经采用REST作为App, H5以及其它客户端的服务端架构。 1. 什么是JAX-RS? JAX-RS是JAVA EE6 引入的一个新技术。
雨客 微博@JavaChen，这里的所有博客文章来自http://blog.javachen.com/。
杜万-Java reactive programming - Reactor 3 and Spring WebFlux 立即下载