一、@Path
若希望一个Java类能够处理REST请求,则这个类必须至少添加一个@Path("/")的annotation;
对于方法,这个annotation是可选的,如果不添加,则继承类的定义。
(1)@Path里的值可以是一个复杂的表达式,例如@Path("{id}") ,其中 {id}表达式代码了一个模板参数;
一个模板参数是一个定义在@Path里的通配符,它以 { 开始,中间是一堆字母和数字的混合串(不能包含 / 字符),以 } 结尾。又如: @Path("{firstName}-{lastName}") .
(2)@Path也支持正则表达式,例如: @Path("{id: \\d+}") ,其中 \\d+ 表示一个数字。格式为: A : B
二、@Method
(1)一个方法上只有添加了某个Http Method的annotation,例如@GET,才有资格处理请求。
(2)对于资源的具体操作类型,由HTTP动词表示。常用的HTTP动词有下面五个(括号里是对应的SQL命令)。
- GET(SELECT):从服务器取出资源(一项或多项)。
- POST(CREATE):在服务器新建一个资源。
- PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
- PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
- DELETE(DELETE):从服务器删除资源。
还有两个不常用的HTTP动词。
- HEAD:获取资源的元数据。
- OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
下面是一些例子。
- GET /zoos:列出所有动物园
- POST /zoos:新建一个动物园
- GET /zoos/ID:获取某个指定动物园的信息
- PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
- PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
- DELETE /zoos/ID:删除某个动物园
- GET /zoos/ID/animals:列出某个指定动物园的所有动物
- DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
三:Accept和Content-Type的区别
四:@Produces 表示类或者方法返回的MIME数据类型。
有几种格式如下:
(1)@Produces("text/plain") 文本类型
(2)@Produces("text/html") Html类型
(3)@Produces({"application/xml"}) Xml类型
(4)@Produces({ "application/json"}) Json类型
可以一次注解两种或多种的MIME类型,格式如:{"application/xml", "application/json"}这表示两者都可以使用,但是选择的时候一般会选择前者,即application/xml,因为它第一次出现。
五:@Consumes
代表的是一个资源可以接受的 MIME 类型。
@Consumes
注释针对 Content-Type
请求头进行匹配,以决定方法是否能接受给定请求的内容。
六:@Queryparam与@Pathparam区别
@Queryparam:指定的是URL中的参数是以键值对的形式出现的,而在程序中 @QueryParam("from") int from则读出URL中from的值,
例如:URL输入为:users?from=100&to=200&orderBy=age&orderBy=name
@Pathparam:URL中只出现参数的值,不出现键值对
例如: /users/100
追加:
HTTP方法幂等性和安全性的分析:
HTTP协议规定了不同方法的安全特性和幂等特性,作为服务提供者的服务器必需为客户端提供这些特性。安全性,仅指该方法的多次调用不会产生副作用,不涉及传统意义上的“安全”,这里的副作用是指资源状态。即,安全的方法不会修改资源状态,尽管多次调用的返回值可能不一样(被其他非安全方法修改过)。幂等性,是指该方法多次调用返回的效果(形式)一致,客户端可以重复调用并且期望同样的结果。幂等的含义类似于编程语言中的setter方法[1],一次调用和多次调用产生的效果是一致的,都是对一个变量进行赋值。安全性和幂等性含义有些接近,容易搞混。