- REST 统一接口
REST 使用 HTTP 协议的通用方法作为统一接口的标准词汇，REST 服务所提供的方法信息都在 HTTP 方法里，每一种HTTP请求方法都可以从安全性和幂等性两方面考虑，这对正确理解HTTP请求方法和设计统一接口具有决定性的意义，安全性是指系统对接口的访问，不会使服务器端资源的状态发生改变；幂等性是指系统对同一REST接口的多次访问，得到的资源状态是相同的，以下是各个方法的安全性和幂等性要求：
方法名称 | 安全性 | 幂等性 | 说明 |
GET | Y | Y | GET 方法是只读的 |
PUT | N | Y | PUT 方法是一种写操作的HTTP请求，PUT方法是幂等性的，即多次插入或者更新同一份数据，如果每次提交到服务器端，都会为数据添加一个新的主键值，那么就不是幂等性的，因此需要使用POST 方法 |
DELETE | N | Y | DELETE 方法是幂等的，即多次删除同一份数据，在服务器端的改变相同，执行删除的方法其返回值可以定义为 void，无返回值的方法，返回的响应实体为空，HTTP状态码为204 |
POST | N | N | POST 方法是写操作的HTTP请求，RPC 的所有写操作均使用 POST 方法，REST 只使用 HTTP 的POST 方法增加资源 |
- 资源地址设计
资源地址的设计对整个REST式的Web服务至关重要，涉及系统的可用性、可维护性和可扩展性等诸多方面的表现，资源地址的路径变量是用来表达逻辑上的层次结构的，资源和子资源的形式是自左至右、斜杠分割的名词，一个典型的URI包括协议名称、主机名称、服务端口、资源地址和查询字符串等组成，URI 组成如下：
http://localhost:8080/rest-demo/webapi/demos/demo?id=1
其中 rest-demo 表示 ContextPath（上下文路径）通常和部署服务器的配置或者REST服务的web.xml配置有关；webapi 表示 ServletPath 是 Servlet 名称，与 REST 服务中定义的 @ApplicationPath 注解或者web.xml 的配置有关；demos/demo 为资源地址，与资源类、子类以及类中的方法定义的@Path注解有关。需要注意的是，资源地址并不能唯一定位一个资源，只有资源地址和HTTP方法才能唯一定位资源。
在路径变量里可以使用标点符合以辅助增强逻辑清晰性，作为资源地址的查询变量，用来表达算法的输入，实现对方法的作用域的约束，标点符号说明如下：
- 问号（？）是用来分割资源地址和查询字符串的，与符号（&）是用来分割查询条件的参数， 示例代码如下：
GET /demos?start=0&size=10
- 逗号（，）是用来分割有次序的作用域信息，这种顺序可以是约定俗成的，比如先经度后纬度等，示例代码如下：
GET /demos/01,2002-12,2014
这段代码表示查询2002年1月到2014年12月的数据，这个例子中还是用了连字符（-）
- 分号（；）是用来分割无序的作用域信息，通常这些信息是逻辑上并列存在的，示例代码如下:
GET /demos/name;program=java;type=web
- 路径变量注解
- @QueryParam 注解
查询条件决定了方法的作用域，查询参数组成了查询条件，使用@QueryParam注解来定义查询参数，使用示例如下：
接口描述 | 资源地址 |
分页查询列表数据 | /demos?start=10&size=100 |
查询单项数据 | /demos/demo?id=12 |
分页查询注解示例：
Public DemoList getBypaging(@QueryParam("start") final int start,@DefaultValue("100") @QueryParam("size") final int size){
// 查询代码
}
查询单项数据注解示例：
Public Demo getEntity(@QueryParam("id") final int id){
// 查询代码
}
注解@QueryParam 可以和注解@DefaultValue 一起使用，注解 @DefaultValue 的作用是预置一个默认值，当请求不包含参数时，使用该默认值
- @PathParam参数
用来定义路径参数，每个参数对应一个子资源，使用示例如下：
接口描述 | 资源地址 |
基本路径参数 | /demos/eric |
带标点符号的资源路径 | /demos/01,2012-12,2014 |
子资源变长的资源路径 | /demos/d/e/m/o /demos/q2/restful;program=java;type=web |
@Path 注解来定义资源路径，需要一个value参数来解析资源路径，该参数除了使用静态定义的方式外，也可以使用动态变量的方式，其格式为：{参数名称：正则表达式}。
基本路径参数注解示例：
@GET
@Path("eric")
Public string get(){
// 查询代码
}
带标点符号的资源路径注解示例：
@GET
@Path("{from:[0-9]{2},[0-9]{4}}-{to:[0-9]{2},[0-9]{4}}")
Public string getByCondition(@PathParam("from") string fromString,@PathParam("to") string toString){
// 查询代码
}
路径区间（PathSegment）是对资源地址更灵活的支持，使资源类的一个方法可以支持更广泛的资源地址请求，例如，固定子资源和动态子资源两个部分，对于动态匹配变长的子资源地址，PathSegment 类型的参数结合正则表达式很容易处理，示例如下：
@GET
@Path("{p:.+}/m/{n:[a-zA-Z]+}")
Public string getByAddress(@PathParam("p") final List<PathSegment> p,@PathParam("n") final string n){
Final StringBuilder result = new StringBuilder();
for(final PathSegment path : p){
result.append(path.getPath()).append("-");
}
return result.toString();
}
对于查询参数动态给定的场景，可以定义PathSegment作为参数类型，通过 getMatrixParameters方法获取 MultivaluedMap 类型的查询参数信息，示例代码如下：
@Path("q2/{condition}")
@GET
public String get(@PathParam("condition") final PathSegment condition) {
StringBuilder stringBuilder = new StringBuilder();
final MultivaluedMap<String, String> map = condition.getMatrixParameters();
final Iterator<Map.Entry<String, List<String>>> iterator = map.entrySet().iterator();
while (iterator.hasNext()) {
Map.Entry<String, List<String>> entry = iterator.next();
stringBuilder.append(entry.getKey()).append("=");
stringBuilder.append(entry.getValue()).append(" ");
}
return stringBuilder.toString();
}
上例是通过编程的方式调用PathSegment类的getMatrixParameters()方法来查询获取参数信息，还可以通过@MatrixParam注解来逐一定义参数，示例代码如下：
@Path("q3/{condition}")
@GET
public String get(@MatrixParam("program") String program, @MatrixParam("type") String type) {
StringBuilder stringBuilder = new StringBuilder();
stringBuilder.append("program="+program).append("&type=").append(type);
return stringBuilder.toString();
}
- @FormParam 注解
该注解用于定义表单参数，相应的REST方法用以处理请求实体媒体类型为 Content-Type:application/x-www-form-urlencoded的请求，示例代码如下：
@Path("create")
@POST
@Produces(MediaType.APPLICATION_JSON)
public DemoResult create(@FormParam("name") String name, @FormParam("sex") String sex) {
DemoResult result = new DemoResult();
result.setHasError(false);
result.setMessage("创建 name=" + name + " sex=" + sex);
return result;
}
默认情况下，会对表单参数进行自动解码，也可以使用@Encoded注解来禁用自动解码
- @BeanParam 注解
该注解用于自定义参数组合，使REST方法可以使用简洁的参数形式完成复杂的接口设计，示例代码如下：
- 自定义参数类：
public class CreateParam {
@FormParam("name")
private String name;
@FormParam("sex")
private String sex;
// getter 和 setter 方法
}
- REST服务方法：
@Path("createparam")
@POST
public DemoResult createByBeanPraam(@BeanParam CreateParam createParam) {
DemoResult result = new DemoResult();
result.setHasError(false);
result.setMessage("创建 name=" + name + " sex=" + sex);
return result;
}
- @CookieParam 注解
该注解用以匹配Cookie中的键值对Cookie中的键值对信息，示例代码如下：
@Path("createbycookie")
@POST
public DemoResult createByCookie(@FormParam("name") String name, @FormParam("sex") String sex,
@CookieParam("dir") String bir) {
DemoResult result = new DemoResult();
result.setHasError(false);
result.setMessage("创建 name=" + name + " sex=" + sex + " cookie=" + bir);
return result;
}
- @Context 注解
该注解来解析上下文参数，REST服务中，有多种元素可以通过@Context注解作为上下文参数使用，示例代码如下：
@Path("context")
@GET
public String get(@Context Application application, @Context Request request,
@Context Providers provider, @Context UriInfo uriInfo,
@Context HttpHeaders httpHeaders) {
}