笔记：Jersey REST API 设计

Posted 2020-09-26 追寻自由的路途

• 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) {

  ?

  }

  ? ?

  ? ?