笔记:Jersey REST API 设计

时间:2021-08-24 20:46:05
  • 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 + "\tsex=" + 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 + "\tsex=" + 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 + "\tsex=" + sex + "\tcookie=" + 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) {

     

    }