1. HTTP Methods
HTTP方法映射到资源的CRUD(创建、读取、更新和删除)操作,基本模式如下:
@GET:读取/列出/检索单个或资源集合。该注解标记的方法表明用于处理GET请求,GET方法是幂等且安全的。
@POST:新建资源。该注解标记的方法表明处理POST请求,POST方法表明是一种创建操作的方法,POST方法是一种写操作的HTTP请求,RPC中的写操作均是使用post方法,而在REST中我们只是使用POST方法来添加资源。
@PUT:更新现有资源或资源集合。
@DELETE:删除资源或资源集合。该注解标记的方法表明这个方法执行的是一个删除资源的操作,其返回值可以是void,即没有返回值。
2. @Path
该注解可以标记在类名之上,也可以标记在方法名上。该注解接收一个value参数,表示定义资源的地址。另外,资源地址相同,但是HTTP方法不同的两个方法是完全两个不同的REST接口,HTTP方法和资源地址相结合在一起才可以完成对一个资源的定位。
@Path有两个作用:
(1)标注class,表明该类是个资源类。凡是资源类,必须使用@Path注解,不然jersey无法扫描到该资源类。
(2)标注method,表示具体的请求资源的路径
例:
@Component
@Path("/weclome")
public class JerseyResource {
@GET
@Path("/wrong")
public void getPage(@Context HttpServletRequest request) {
System.out.println("这是一个get方法!");
}
@POST
@Path("/wrong")
public void postPage(@Context HttpServletRequest request) {
System.out.println("这是一个post方法!");
}
}
以上面这个类为例,虽然@Path的组合是"/weclome/wrong",但是由于HTTP方法不同,因此,执行的方法体也是不同的。
3. @Produces
@Produces注释用来指定将要返回给客户端的数据标识类型(MIME)。@Produces可以作为class(类)注释,也可以作为方法注释,方法的@Produces注释将会覆盖class(类)的注释。@Produces定义了服务器端生产的媒体类型,即服务器端产生的响应实体的媒体类型,同样也可以是xml、json等媒体类型。
a. 返回给client字符串类型(text/plain)
@Produces(MediaType.TEXT_PLAIN)
b. 返回给客户端为json类型(application/json)
@Produces(MediaType.APPLICATION_JSON)
c. 指定多个MIME类型
@Produces({“application/json”,“application/xml”})
例:图-1
4. @Consumes
@Consumes与@Produces相反,用来指定可以接受客户端发送过来的MIME类型,同样可以用于class或者method,也可以指定多个MIME类型,一般用于@PUT,@POST。在服务器端,@Consumes定义了服务器端要消费的媒体类型,也就是说消费客户端请求实体的媒体类型,可以是xml、json等类型。
a. 接受client参数为字符串类型
@Consumes(MediaType.TEXT_PLAIN)
b. 接受client参数为json类型
@Consumes(MediaType.APPLICATION_JSON)
5. @QueryParam
该注解表明是一个查询条件,查询条件决定了方法的作用域,查询参数组成了查询条件。Jersey中使用@QueryParam注解来定义查询参数。另外注解@QueryParam还可以和注解@DefaultVaule一起使用,注解@DefaultValue的作用则是预置一个默认值,当请求中不包括该参数时候使用这个默认值。
例:如图-1
6. @DefaultValue
参数@QueryParam的默认值。
@Path("/users")
public class UserService {
@GET
@Path("/query")
public Response getUsers(
@DefaultValue("1000") @QueryParam("from") int from,
@DefaultValue("999")@QueryParam("to") int to,
@DefaultValue("name") @QueryParam("orderBy") List<String> orderBy) {
return Response
.status(200)
.entity("getUsers is called, from : " + from + ", to : " + to
+ ", orderBy" + orderBy.toString()).build();
}
URL:users/query
输出:getUsers is called, from : 1000, to : 999, orderBy[name]
7. @PathParam
该注解定义路径的参数信息,每一个参数都对应一个子资源。
Path("/users")
public class UserService {
@GET
@Path("{year}/{month}/{day}")
public Response getUserHistory(
@PathParam("year") int year,
@PathParam("month") int month,
@PathParam("day") int day) {
String date = year + "/" + month + "/" + day;
return Response.status(200).entity("getUserHistory is called, year/month/day : " + date).build();
}
}
输入/users/2011/06/30,输出为: getUserHistory is called, year/month/day : 2011/6/30
要注意的是,跟@pathparam不同,@queryparam中,指定的是URL中的参数是以键值对的形式出现的,而在程序中@QueryParam("id") String id则从URL读出中id的值, 而@pathparem中,URL中只出现参数的值,不出现键值对,自动匹配。
8. @Context
该注解用来解析上下文参数。(@Context HttpRequest request)。通过@Context可以获得以下信息:UriInfo、ServletConfig、ServletContext、HttpServletRequest、HttpServletResponse和HttpHeaders等。
例1:
@GET
@Path("test_get")
@Produces("text/plain")
public String getTest1(@PathParam("name") String name, @Context HttpServletRequest request){
System.out.println("name:"+name);// null
String result;
result = request.getParameter("name");
System.out.println("name="+result); //houfeng
result+= "--------"+request.getContextPath();
return result;
}
例2:
@Path("/users")
public class UserService {
@GET
@Path("/query")
public Response getUsers(@Context UriInfo info) {
String from = info.getQueryParameters().getFirst("from");
String to = info.getQueryParameters().getFirst("to");
List<String> orderBy = info.getQueryParameters().get("orderBy");
return Response.status(200).entity("getUsers is called, from : " + from + ", to : " + to
+ ", orderBy" + orderBy.toString()).build();
}
URL:users/query?from=100&to=200&orderBy=age&orderBy=name
输出为: getUsers is called, from : 100, to : 200, orderBy[age, name]
注意这里把orderby后的两个参数读入为LIST处理了.
9. @FormParam
获取post请求中表单中的数据。
@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("name") String name) {
// Store the message
}
参考:https://blog.csdn.net/ilovewqf/article/details/50515925
10. @BeanParam
获取请求参数中的数据,用实体Bean进行封装。如果传递的参数较多,可以自己写个bean,bean中的字段使用@PathParam、@QueryParam、@FormParam、@FormDataParam、@MatrixParam、@HeaderParam、@CookieParam来注解。而在resouces中具体方法参数中就可以使用@BeanParam来注解这个自定义的bean。
@POST
@Consumes("application/x-www-form-urlencoded")
public void update(@BeanParam User user) {
// Store the user data
}
参考:http://1197581932.iteye.com/blog/2400844
11. @XmlRootElement
一般标注在实体类上,表示把该类bean转化成XML,说明这个是XML的根节点。
参考:https://blog.csdn.net/kkkloveyou/article/details/21415735
@XmlAttribute用来注释实体类属性
例:
@XmlRootElement
public class Book implements Serializable {
@XmlAttribute(name = "bookId")
public Long getBookId(){
return bookId;
}
@XmlAttribute(name = "bookName")
public String getBookName(){
return bookName;
}
@XmlAttribute(name = "publisher")
public String getPublisher(){
return publisher;
}
12. @Encoded
禁止解码,客户端发送的参数是什么样,服务器接收到的参数就是什么样
13. @Singleton
表示单例模式。默认情况下,资源类的生命周期是per-request,也就是系统会为每个匹配资源类URI的请求创建一个实例,这样的效率很低,可以对资源类使用@Singleton注解,这样在应用范围内,只会创建资源类的一个实例。
14. @PerSession
每一个 session 请求, 就产生一个 rest 资源实例 , 直到这个 session 消毁,这个 rest 资源才会消失 。session, 使用 @PerSession注解。
15. application/json 和 application/x-www-form-urlencoded的区别
application/x-www-form-urlencoded:Jquery的Ajax请求默认方式,这种方式的好处就是浏览器都支持,在请求发送过程中会对数据进行序列化处理,以键值对形式?key1=value1&key2=value2,然后把这个字串append到url后面,用?分割,加载这个新的url方式发送到服务器。如果用Jquery,它内部已经进行了处理,如果自己写原生的Ajax请求,就需要自己对数据进行序列化。
application/json:application/json作为请求content-type,告诉服务器请求的主题内容是json格式的字符串,服务器端会对json字符串进行解析,这种方式的好处就是前端人员不需要关心数据结构的复杂度,只要是标准的json格式就能提交成功
参考:
Jersey中的常用注解总结:https://www.cnblogs.com/wrong5566/p/5985001.html
jersey常用的注解类型:https://blog.csdn.net/qq383264679/article/details/50847295
JAX-RS之@QueryParam和@DefaultValue:http://jackyrong.iteye.com/blog/1128364
jersey获取各个参数的总结:https://blog.csdn.net/itchiang/article/details/50582979
jersey学习:注解解析(系列三):https://www.cnblogs.com/bella-fly/articles/5237812.html
Java Jersey使用總結:https://my.oschina.net/mlongbo/blog/152548#OSC_h4_21
Jersey 入门与Javabean:https://www.cnblogs.com/xinsheng/p/3897289.html
HTTP中application/x-www-form-urlencoded字符说明:https://blog.csdn.net/qq_28702545/article/details/51719199
application/json 和 application/x-www-form-urlencoded的区别:
https://blog.csdn.net/mm_gg_201512/article/details/72830000
选application/x-www-form-urlencoded还是application/json?:
https://blog.csdn.net/HEL_WOR/article/details/52123712
关于Content-Type中application/x-www-form-urlencoded 和 multipart/form-data的区别及用法:
https://www.cnblogs.com/kaibin/p/6635134.html
MediaType是application/x-www-form-urlencoded的接口测试方法: