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

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();

}