Jersey 开发RESTful（八）Jersey参数绑定

【原创文章，转载请注明原文章地址，谢谢！】

在所有的Web类应用中，参数的绑定都是一个非常重要的话题，本章中，就来看看Jersey中的参数绑定方式。

绑定路径参数

我们已经知道路径参数在针对某个资源，或者有子资源的情况下使用，比如/depts/1/emps/，查询id为1的部门下的所有员工。在Jersey中，使用@PathParam完成路径参数绑定：

/**
 * 映射url中的路径参数
 * 
 * @param id
 * @return
 */
@GET
@Path("{id}")
public String pathParam(@PathParam("id") Long id) {
    System.out.println(id);
    return "success";
}

当然也可以对多个路径参数进行绑定：

/**
 * 对多个路径参数进行绑定
 * @param id
 * @param month
 * @return
 */
@GET
@Path("{id}/summary/{month}")
public String pathParam2(@PathParam("id") Long id,@PathParam("month")int month) {
    System.out.println(id);
    System.out.println(month);
    return "success";
}

映射普通请求参数

在实际开发中，类似对资源的查询等操作，需要通过GET方法获取请求中的查询参数内容。Jersey提供了@QueryParam注解完成参数绑定。

/**
 * 映射请求参数，需要是GET/POST请求
 * 
 * @param name
 * @return
 */
@GET
@Path("/query")
public String queryParam(@QueryParam("name") String name) {
    System.out.println(name);
    return "success";
}

要触发这个请求，必须使用GET[POST] /params/query?name=wolfcode来请求。那么@QueryParam就可以把wolfcode正确的注入到name参数中。

映射表单提交参数

使用表单提交是互联网应用再常见不过的方式，在SpringMVC中，提供了各种牛逼的能力来把表单中的数据映射到方法的参数，模型中，但是在这块上，Jersey同样很强大，但是稍微使用复杂一点。要演示表单提交参数绑定，我们先创建一个简单的Employee类：

@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class Employee {

    private Long id;
    private String name;
    private int age;
}

需求：根据提交的数据创建一个Employee对象。

/**
 * 映射表单提交参数，要求请求是POST,PUT,并且编码格式必须是x-www-form-urlencoded
 * 
 * @param name
 * @param age
 * @return
 */
@PUT
@Path("/form")
@Produces(MediaType.APPLICATION_JSON)
public Employee formParam(@FormParam("name") String name, @FormParam("age") int age) {
    return new Employee(1L, name, age);
}

普通值绑定

第一种方式，在Jersey中，提供了一个@FormParam注解来完成表单中内容到参数的绑定（API文档解释，是绑定一个请求实体中的表单参数到资源方法参数 Binds the value(s) of a form parameter contained within a request entity body to a resource method parameter）。
注意几个点：
1，@FormParam注解只能接受x-www-form-urlencoded编码格式的form表单提交，这个是必要条件；
2，@FormParam注解能够完成的绑定类型有，

• 简单类型；
• 绑定到一个对象，要求这个对象的类有一个接受单个String类型的构造器；
• 绑定到一个对象，要求这个对象的类有一个valueOf(String)或者fromString(String)的静态的构建方法，比如

public static Employee valueOf(String name){
   return new Employee(name);
}

• 提供一个ParamConverterProvider（这个后面讲Provider）；
• 可以绑定到一个List，Set上面，例如：

@POST
@Path("/hobby")
@Produces(MediaType.APPLICATION_JSON)
public Employee formParam(@FormParam("hobby") Set hobbies) {
    System.out.println(hobbies);
    return new Employee();
}

那么，使用POST param/hobby?hobby=java&hobby=haha&hobby=hehe 就可以完成Set的绑定（注意表单编码格式一定是x-www-form-urlencoded）。

另外，@FormParam可以配合一个@DefaultValue标签来设置默认值，简单演示：

@PUT
@Path("/form")
@Produces(MediaType.APPLICATION_JSON)
public Employee formParam(@FormParam("name") String name, 
                          @DefaultValue("18") @FormParam("age") int age) {
    return new Employee(1L, name, age);
}

当@FormParam绑定失败即可使用@DefaultValue设置的值。

绑定到对象

在SpringMVC中，我们更常见的是直接把请求参数绑定到一个我们需要的模型或者VO中。在Jersey中，使用@FormParam注解无法完成，可以使用@BeanParam和@FormParam配合使用：

首先修改Employee对象：

@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class Employee {

    private Long id;
    @FormParam("name")
    private String name;
    @FormParam("age")
    private int age;
}

注意，我们把@FormParam标签移动到了Employee的对应属性上。当然在实际开发中，更多应该是在VO对象类中；

/**
 * 直接映射到模型，要求请求是POST,PUT,并且编码格式必须是x-www-form-urlencoded
 * 
 * @param e
 * @return
 */
@POST
@Path("/formpojo")
@Produces(MediaType.APPLICATION_JSON)
public Employee formPojoParam(@BeanParam Employee e) {
    e.setId(2L);
    return e;
}

然后，再使用Jersey提供了@BeanParam注解，完成请求参数到自定义模型的绑定。注意，在自定义模型中，不光可以使用@FormParam，可以使用@XXXParam，比如前面提到过的@PathParam。

直接获取表单内容

前面介绍过使用@FormParam和@BeanParam来获取表单中的数据，下面再介绍一种通过直接获取表单内容的方式：

/**
 * 使用MultivaluedMap直接获取POST表单编码格式必须是x-www-form-urlencoded的表单内容
 * 
 * @param fs
 * @return
 */
@POST
@Path("/formui2")
public String formPojoParam(MultivaluedMap fs) {
    System.out.println(fs);
    return "success";
}

那么获取到的MultivaluedMap类型中，就包含了表单里面所有的参数内容，每一个Entry的类型是，这点需要注意。

映射请求头参数

从请求头中获取一些参数，比如请求头中自定义的token等信息，可以直接使用Jersey提供的@HeaderParam注解完成：

/**
 * 通过@HeaderParam获取请求头内容
 */
@GET
@Path("/head")
public String headParam(@HeaderParam("token") String token) {
    System.out.println(token);
    return "success";
}

那么在请求的时候，我们可以在头信息中添加：

image.png

就可以正常看到后台把token绑定到token参数中。需要注意的是，@DefaultValue标签都是可以和这些@XXXParam配合使用的，并且也可以添加到需要绑定的模型属性上的。

绑定矩阵参数

矩阵参数听着很奇怪，其实很简单，比如我们在做分页的时候，可以使用类似这样的请求：
/resource;pageSize=10;currentPage=2
注意，这个请求并不是普通的参数提交方式，按照普通的方式，应该是：
/resource?pageSize=10¤tPage=2
注意查看两者的区别。
那么使用矩阵参数有什么好处呢？在REST架构中，矩阵参数可以把这些参数一起看做一个资源，意思就是上面的两个连接中，第一个URI可以看做第二页，每页10条resource资源，把这个整体作为一个资源去看待；又比如这样一个资源：
/players/ladder;level=king
就可以看成天梯中等级为王者的玩家，把这个概念直接作为一个资源整体看待。

理解了矩阵参数，Jersey提供了@MatrixParam标签来完成矩阵参数的绑定：

/**
 * 从请求路径中分离出key=value的值
 * 
 * @param currentPage
 * @param pageSize
 * @param keyword
 * @return
 */
@GET
@Path("/matrix")
public String matrix(@MatrixParam("currentPage") int currentPage, @MatrixParam("pageSize") int pageSize,
        @MatrixParam("keyword") String keyword) {
    System.out.println("currentPage:" + currentPage);
    System.out.println("pageSize:" + pageSize);
    System.out.println("keyword:" + keyword);
    return "success";
}

那么，当我们做出请求

image.png

就可以正确的分别解析出其中的pageSize,currentPage和keyword参数。但是需要注意一点，Jersey只能解析出处于最后一个路径中的矩阵参数。

小结

至此，Jersey提供的最基本的几种请求参数绑定方式介绍完毕，下一结介绍@Context注解的使用。

WechatIMG7.jpeg