JAX-RS（Java API for RESTful Web Services）常用注解

概述

JAX-RS（Java API for RESTful Web Services）是Java 提供用于开发RESTful Web 服务基于注解的 API，旨在定义一个统一的规范，使得 Java 程序员可以使用一套固定的接口来开发 REST 应用，避免了依赖于第三方框架。同时，JAX-RS 使用 POJO 编程模型和基于标注的配置，并集成了 JAXB，从而可以有效缩短 REST 应用的开发周期，Jersey，RESTEasy都是JAX-RS标准的具体实现框架。

常用注解

1、请求路径

@Path：用来标注资源类或者方法的URI路径，URI路径模板是URI语法中嵌入的变量的URI。这些变量在运行时被替换，以便资源对基于被替换的URI的请求作出响应，变量用花括号"{}"表示，如：@Path("/users/{username}")。

URI路径模板还支持正则表达式，如：@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")

2、Http请求类型

@GET，@PUT，@POST，@DELETE

这四个注解标注方法是HTTP请求的类型，分别对应 4 种 HTTP 方法，用于对资源进行创建、检索、更新和删除的操作。

3、返回和接收的MIME媒体类型

（1）@Produces：标注在资源类的方法上，表示返回的MIME媒体类型

如：@Produces(MediaType.APPLICATION_JSON)

（2）@Consumes：标注在资源类的方法上，表示可接受请求的MIME媒体类型

如：@Consumes(MediaType.APPLICATION_XML)

4、Http请求参数处理相关注解

这些注解用来标注方法的参数来自于HTTP请求的不同位置

（1）@PathParam：绑定@path中的url参数到@PathParam标注的方法参数中

@Component
@Path("userMgr")
public class UserMgrResource {
@GET
@Path("/getUserById/{id}/{name}")
public String getUserInfoId(@PathParam("id") int id,
@PathParam("name") String name) {
return "Receive name is:" + name + ",id is:" + id;
}
}

URI Pattern : /userMgr/getUserById/100/feinik

返回： Receive name is:feinik,id is:100

（2）@QueryParam：绑定Http请求参数到资源类的方法参数中

@GET
@Path("getUserByName")
public String getUserInfo(@QueryParam("name") String name) {
return "Receive name is:" + name;
}

URI Pattern : /userMgr/getUserByName?name=feinik

返回： Receive name is:feinik

（3）@QueryParam： 注解还可以配合 @DefaultValue 注解来使用，当@QueryParam注解的方法参数没有传递时，默认使用@DefaultValue中的默认值，可防止Null空值。

@GET
@Path("getUserByName")
public String getUserInfo(@DefaultValue("fei")@QueryParam("name") String name) {
return "Receive name is:" + name;
}

URI Pattern : /userMgr/getUserByName

返回： Receive name is:fei

（4）@HeaderParam： 绑定Http请求header头中的参数到资源类的方法参数中

@GET
@Path("getHeader")
public String getHeader(@HeaderParam(HttpHeaders.CONTENT_TYPE) String contentType) {
return "Receive header contentType is:" + contentType;
}

（5）@CookieParam： 绑定Http请求的cookie参数到资源类的方法参数中

@GET
@Path("getCookie")
public String getCookie(@CookieParam("sessionId") String sessionId) {
return "Receive header sessionId is:" + sessionId;
}

（6）@MatrixParam： 绑定url中的参数到资源类的方法参数中，如：URL：/getMatrix;name=feinik，Matrix参数是name=feinik，在URL中以‘；’分割

@GET
@Path("getMatrix")
public String getMatrix(@MatrixParam("name") String name,
@MatrixParam("address") String address) {
return "Receive name is:" + name + ", address is:" + address;
}

URI Pattern : /userMgr/getMatrix;name=feinik;address=北京

返回： Receive name is:feinik, address is:北京

（7）@FormParam： 绑定HTML中的表单参数到资源类的方法参数中

（8）@Context： 注入辅助对象或信息对象，如 HttpServletRequest，ServletContext 等

@GET
@Path("testContext")
public String getMatrix(@Context HttpServletRequest request) {
return "Context path is:" + request.getContextPath();
}