说明：博客文章内容摘抄自于参考文章的文章内容，由参考文章整理所得。
一、简介
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仓自行下载。
<!-- https://mvnrepository.com/artifact/javax.ws.rs/javax.ws.rs-api -->
<dependency>
<groupId>javax.ws.rs</groupId>
<artifactId>javax.ws.rs-api</artifactId>
<version>2.1-m09</version>
</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