（RESTFul）javax.ws.rs-api 常用注解

链接: link.

文章目录
@Path
@GET @POST @PUT @DELETE
@Consumes
示例
@Produces
示例
@PathParam
示例
@QueryParam
示例
@FormParam
示例
@FormDataParam
@HeaderParam
示例
@CookieParam
@MatrixParam
示例
@DefaultValue
示例
@BeanParam
示例
@Context
示例
@Encoded
@Path
标注class时，表明该类是个资源类，凡是资源类必须使用该注解
标注method时，表示具体的请求资源的路径
注解位置：类注解、方法注解

@GET @POST @PUT @DELETE
指明接收HTTP请求的方式属于get,post,put,delete中的哪一种，具体指定请求方式，是由客户端发起请求时指定。
注解位置：方法注解

@Consumes
指定HTTP请求的MIME类型，默认是*/*，表示任意的MIME类型。该注解支持多个值设定，可以使用MediaType来指定MIME类型。
MediaType的类型大致有：

application/xml
application/atom+xml
application/json
application/svg+xml
application/x-www-form-urlencoded
application/octet-stream
multipart/form-data
text/plain
text/xml
text/html
注解位置：方法注解

示例
@Path("{username"})
@Consumes({MediaType.APPLICATION_JSON})
public User getUser(@PathParam(“username”) String userName) {
…
}

@Produces
指定HTTP响应的MIME类型，默认是*/*，表示任意的MIME类型。同Consumes使用MediaType来指定MIME类型。
注解位置：方法注解

示例
@Path("{username"})
@Consumes({MediaType.APPLICATION_JSON})
@Produces(MediaType.APPLICATION_JSON)
public User getUser(@PathParam(“username”) String userName) {
…
}

@PathParam
配合@Path进行使用，可以获取URI中指定规则的参数。
注解位置：参数注解

示例
@GET
@Path("{username"})
@Produces(MediaType.APPLICATION_JSON)
public User getUser(@PathParam(“username”) String userName) {
…
}

// 浏览器请求http://ip:port/user/jack时，userName值为jack。
// 注意，这里的username并不是说Key是username, value是jack而是说/usr/后面跟着的东西就是username,这里username只是个变量
@QueryParam
用于获取GET请求中的查询参数，实际上是url拼接在?后面的参数。
注解位置：参数注解

示例
@GET
@Path("/user")
@Produces(“text/plain”)
public User getUser(@QueryParam(“name”) String name,
@QueryParam(“age”) int age) {
…
}

//当浏览器请求http://ip:port/user?name=rose&age=25时，name值为rose，age值为25。如果需要为参数设置默认值，可以使用@DefaultValue

@FormParam
用于获取POST请求且以form(MIME类型为application/x-www-form-urlencoded)方式提交的表单的参数。
注解位置：参数注解

示例
@POST
@Consumes(“application/x-www-form-urlencoded”)
public void post(@FormParam(“name”) String name) {
…
}
// 这应该是提交form表单中常见的方式，就不详述了。

@FormDataParam
用于获取POST请求且以form(MIME类型为multipart/form-data)方式提交的表单的参数，通常是在上传文件的时候。
注解位置：参数注解

@HeaderParam
用于获取HTTP请求头中的参数值。
注解位置：参数注解

示例
@GET
@Path("/user/get")
public Response getUser(@HeaderParam(“user-agent”) String userAgent) {
…
}
// 这里获取user-agent的值

@CookieParam
用于获取HTTP请求cookie中的参数值。
注解位置：参数注解

@GET
public String callService(@CookieParam(“sessionid”) String sessionid) {
…
}

@MatrixParam
可以用来绑定包含多个property (属性)=value(值) 方法参数表达式，用于获取请求URL参数中的键值对，必须使用";"作为键值对分隔符。
注解位置：参数注解

示例
@Path("/books")
public class BookService {
@GET
@Path("{year}")
public Response getBooks(@PathParam(“year”) String year,
@MatrixParam(“author”) String author,
@MatrixParam(“country”) String country) {
…
}
}
// 请求1：“/books/2012/”， 解析结果为：年份：2012，作者：null，国家：null
// 请求2：“/books/2012;author=andih”， 解析结果为：年份：2012，作者：andih，国家：null

注意MatrixParam与QueryParam的区别：
QueryParam请求url的格式为: url?key1=value1&key2=value2&…
MatrixParam请求url的格式为: url;key1=value1;key2=value2;…

@DefaultValue
配合前面的参数注解等使用，用来设置默认值，如果请求指定的参数中没有值，通过该注解给定默认值。
注解位置：参数注解

示例
@POST
@Path("/user/add")
@Consumes({MediaType.APPLICATION_FORM_URLENCODED})
@Produces({MediaType.APPLICATION_JSON})
public Response addUser(@FormParam(“username”) String userName, @DefaultValue(“0”) @FormParam(“age”) int age,@DefaultValue(“1”) @FormParam(“sex”) int sex){
…
}

注意：DefaultValue指定的值在解析过程中出错时(@DefaultValue(“test”) @QueryParam(“age”) int age)，将返回404错误。

@BeanParam
如果传递的较多，使用@FormParam等参数注解一个一个的接收每个参数可能显得太臃肿，可以通过Bean方式接收自定义的Bean，在自定义的Bean中字段使用@FormParam等参数注解。只需定义一个参数接收即可。
注解位置：参数注解

示例

public class MyBean {
   @FormParam("myData")
   private String data;
   @HeaderParam("myHeader")
   private String header;
   @PathParam("id")
   public void setResourceId(String id) {...}
   ...
 }

 @Path("myresources")
 public class MyResources {
   @POST
   @Path("{id}")
   public void post(@BeanParam MyBean myBean) {
	...
   }
```c
@Context
用来用来解析上下文参数，和Spring中的AutoWired效果类似。通过该注解可以获取ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse和HttpHeaders等信息。
注解位置：属性注解，参数注解

示例c
```c
@Path("/user") 
public class Resource { 
    @Context 
    HttpServletRequest req; 
    @Context 
    ServletConfig servletConfig; 
    @Context 
    ServletContext servletContext; 

    @GET 
    public String get(@Context HttpHeaders hh) { 
        MultivaluedMap<String, String> headerParams = hh.getRequestHeaders(); 
        Map<String, Cookie> pathParams = hh.getCookies(); 
    } 

@Encoded
禁止解码，客户端发送的参数是什么样，服务器就原样接收。