java JAX-RS

说明：博客文章内容摘抄自于参考文章的文章内容，由参考文章整理所得。

一、简介

Java Web有很多成熟的框架，主要可以分为两类Web Application和Web Services。用于Web Application的框架包括官方的Servlet/JSP, JSTL/JSF以及第三方Struts/Spring MVC(action-based)。Web Services的项目又可以分为基于XML的（SOAP/WSDL）的和基于JSON的，Java Communitiy为这两种方式都定义了标准，Java EE5引入了JAX-WS(Java API for XML Web Services)-JSR224，Java EE6引入了JAX-RS(Java API for RESTful Web Services)-JSR331。RESTful Service由于轻量，好测试，有弹性等特点，越来越受欢迎。Jersey，RESTEasy都是JAX-RS标准的具体实现。

二、作用

JAX-RS：（Java API for RESTful Web Services）旨在定义一个统一的规范，使得 Java 程序员可以使用一套固定的接口来开发 REST 应用，避免了依赖于第三方框架。是一个Java编程语言的应用程序接口，支持按照表象化状态转变 (REST)架构风格创建Web服务Web服务。同时，JAX-RS 使用 POJO 编程模型和基于标注的配置，并集成了 JAXB，从而可以有效缩短 REST 应用的开发周期。

三、特点

与传统的 servlet 模型相比，JAX-RS 提供了一种可行的、更为简便、移植性更好的方式来在 Java 内实现 RESTful 服务。使用注释让您能够轻松提供 Java 资源的路径位置并将 Java 方法绑定到 HTTP 请求方法。一种可移植的数据绑定架构提供了一些本机的 Java 类型支持并允许进行序列化/反序列化处理的完全定制。javax.ws.rs.core.Application 子类的扩展以及 web.xml 内的相应清单表明了用最少的部署描述符配置就能进行轻松部署。

四、实现

JAX-RS 的具体实现由第三方提供，例如 Sun 的参考实现 Jersey、Apache 的 CXF 以及 JBoss 的 RESTEasy。

使用JAX-RS需要相关jar包，可去maven仓自行下载。

<dependency>
    <groupId>javax.ws.rsgroupId>
    <artifactId>javax.ws.rs-apiartifactId>
    <version>2.1-m09version>
dependency>

五、注解

1 资源类或方法的相对路径注解

（1）@Path

注释被用来描述根资源、子资源方法或子资源的位置，标注资源类或方法的相对路径。若希望一个Java类能够处理REST请求，则这个类必须至少添加一个@Path(“/”)的注解；对于方法，这个注解是可选的，如果不添加，则继承类的定义。Path也支持正则表达式，例如：@Path(“{id: \d+}”)

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;

@Path("/jaxrs")
public interface JAXRS {

    @GET
    @Path("/getPath")
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void pathClass();
}

2 请求方法注解

@GET，@PUT，@POST，@DELETE，标注方法是用的HTTP请求的类型，分别对应 4 种 HTTP 方法，用于对资源进行创建、检索、更新和删除的操作。HTTP GET 请求被映射到由 @GET 注释的方法；HTTP POST 请求被映射到由 @POST 注释的方法，以此类推。用户可能还需要通过使用 @HttpMethod 注释定义其自己的定制 HTTP 请求方法指示符。

*（1）@GET

@GET注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPGET请求。资源的行为由资源回应的HTTP方法决定。

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;

@Path("/jaxrs")
public interface JAXRS {

    @GET
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void getClass();
}   

*（2）@POST

@POST注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPPOST请求。资源的行为由资源回应的HTTP方法决定。

import javax.ws.rs.Path;
import javax.ws.rs.POST;
import javax.ws.rs.Produces;
import javax.ws.rs.Consumes;

@Path("/jaxrs")
public interface JAXRS {

    @POST
    @Consumes({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void postClass();
}  

（3）@PUT

@PUT注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPPUT请求。资源的行为由资源回应的HTTP方法决定。

（4）@DELETE

@DELETE注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPDELETE请求。资源的行为由资源回应的HTTP方法决定。

（5）@HEAD

@HEAD注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPHEAD请求。资源的行为由资源回应的HTTP方法决定。

（6）@OPTIONS

获取信息，关于资源的哪些属性是客户端可以改变的。

3 参数注入注解

每个资源方法最多只能有一个没有注解的参数。这个没有注解的参数为请求体（entity）的内容

（1）@PathParam

@PathParam注解是可以抽取并用在资源类中的一类参数。URIpath参数是从请求的URI中抽取的，而且参数的名称和@Path注解中定义的变量名对应。

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;

@Path("/jaxrs")
public interface JAXRS {

    @GET
    @Path("/getPathParam/{id}")
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void pathParamClass(@PathParam("id") String id);
} 

（2）@QueryParam

@QueryParam注解是可以抽取并在资源类中使用的一类参数。Query参数是从请求URI的查询参数中抽取的。

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.PathParam;

@Path("/jaxrs")
public interface JAXRS {

    @GET
    @Path("/getQueryParam")
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void queryParamClass(@PathParam("id") String id);
} 

4 内容协议注解

客户端在请求中告诉服务器它期望的返回消息体内容格式，包括使用什么数据格式，怎么编码，使用哪国语言，服务接口的哪个版本等。这种协议被称为Http Content Negotiation（Http内容协定，简称Conneg）。

（1）@Consumes

@Consumes注解是用来指定资源能够接受的客户发送的MIME媒体类型。

import javax.ws.rs.Path;
import javax.ws.rs.POST;
import javax.ws.rs.Produces;
import javax.ws.rs.Consumes;

@Path("/jaxrs")
public interface JAXRS {

    @POST
    @Consumes({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void consumesClass();
} 

（2）@Produces

@Produces注解用来指定资源能够生成并发送给客户端的MIME媒体类型，例如“text/plain”

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;

@Path("/jaxrs")
public interface JAXRS {

    @GET
    @Path("/getProduces")
    @Produces({ application/json;charset=UTF-8, application/xml;charset=UTF-8 })
    public void producesClass();
} 

六、异常处理

1 HTTP中定义的响应状态码

响应码	含义
100	继续
101	分组交换协议
200	OK
201	被创建
202	被采纳
203	非授权信息
204	无内容，返回值为null或void
205	重置内容
206	部分内容
300	多选项
301	目标永久性转移
302	目标暂时性转移
303	参见其他
304	未改动
305	使用代理
307	暂时重定向
400	错误请求
401	未授权
402	要求付费
403	禁止
404	未找到，网页/Path未找到
405	不允许的方法，请求的方法未找到
406	不被采纳，请求的期望返回交换类型不匹配
407	要求代理授权
408	请求超时
409	冲突
410	过期的
411	要求的长度
412	前提不成立
413	请求实例太大
414	请求URL太大
415	不支持的媒体类型
416	无法满足的请求范围
417	失败的预期
500	内部错误
501	未被使用
502	网关错误
503	不可用的服务
504	网关超时
505	HTTP版本未被支持

2 WebApplicationException

WebApplicationException是一个内置的、非检测异常，支持传入Response对象或者状态码。

当JAX-RS碰到一个WebApplicationException抛出时，它会捕获这个异常，调用getRespnse()方法获取Response，发回给客户端。如果应用以一个状态码或者Response初始化了WebApplicationException，则这个状态码或者Response将被用来创建真正的Http响应；否则会直接返回500服务器内部错误给客户端。

    @GET
    @Path("/error/{id}")
    @Produces("application/xml")
    public void errorClass(@PathParam("id") int id) {
        throw new WebApplicationException("404");
    }

参考文章

RESTful和JAX-RS
Spring MVC与JAX-RS比较与分析
JAX-RS及标注
JAX-RS详解
JAX-RS规范基础
使用JAX-RS创建RESTful Web Service

GitHub

JAX-RS API

Maven

javax.ws.rs