1. 简介
Jersey 是一个用于构建 RESTful Web 服务的流行 Java 框架。
在本文中，我们将通过一个简单的 Jersey 项目来探索如何读取不同类型的请求参数。
2. 项目搭建
我们使用 Maven archetype 快速生成一个可用的 Jersey 项目：
mvn archetype:generate -DarchetypeArtifactId=jersey-quickstart-grizzly2 \
-DarchetypeGroupId=org.glassfish.jersey.archetypes \
-DinteractiveMode=false \
-DgroupId=com.example \
-DartifactId=simple-service \
-Dpackage=com.example \
-DarchetypeVersion=2.28
该项目默认使用 Grizzly 容器运行，服务地址为：http://localhost:8080/myapp。
接下来我们添加一个 ItemsController 类，用于后续参数测试：
@Path("items")
public class ItemsController {
// 接口方法将写在这里
}
另外，Jersey 也支持与 Spring 集成使用控制器，有兴趣可以进一步探索。
3. 支持的参数类型
在开始介绍参数读取之前，先了解下 Jersey 支持的参数类型：
✅ 支持的参数类型包括：
- 基本数据类型：如
float、char等 - 含有单个
String参数构造函数的类 - 上述类型的集合类，如
List、Set、SortedSet等
⚠️ 高级用法：我们也可以通过实现 ParamConverterProvider 接口（JAX-RS SPI），自定义参数转换逻辑。
4. Cookie 参数
使用 @CookieParam 注解可以获取请求中的 Cookie 值：
@GET
public String jsessionid(@CookieParam("JSESSIONID") String jsessionId) {
return "Cookie parameter value is [" + jsessionId + "]";
}
测试命令：
curl --cookie "JSESSIONID=5BDA743FEBD1BAEFED12ECE124330923" http://localhost:8080/myapp/items
返回结果：
Cookie parameter value is [5BDA743FEBD1BAEFED12ECE124330923]
5. Header 参数
使用 @HeaderParam 可以读取 HTTP 请求头：
@GET
public String contentType(@HeaderParam("Content-Type") String contentType) {
return "Header parameter value is [" + contentType + "]";
}
测试命令：
curl --header "Content-Type: text/html" http://localhost:8080/myapp/items
返回结果：
Header parameter value is [text/html]
6. 路径参数（Path Parameters）
RESTful API 中经常使用路径参数传递信息，通过 @PathParam 可以提取路径中的值：
@GET
@Path("/{id}")
public String itemId(@PathParam("id") Integer id) {
return "Path parameter value is [" + id + "]";
}
测试命令：
curl http://localhost:8080/myapp/items/3
返回结果：
Path parameter value is [3]
7. 查询参数（Query Parameters）
查询参数常用于传递可选信息，使用 @QueryParam 读取：
@GET
public String itemName(@QueryParam("name") String name) {
return "Query parameter value is [" + name + "]";
}
测试命令：
curl http://localhost:8080/myapp/items?name=Toaster
返回结果：
Query parameter value if [Toaster]
8. 表单参数（Form Parameters）
POST 请求中常使用表单提交数据，Jersey 中使用 @FormParam 获取表单字段：
@POST
public String itemShipment(
@FormParam("deliveryAddress") String deliveryAddress,
@FormParam("quantity") Long quantity) {
return "Form parameters are [deliveryAddress=" + deliveryAddress + ", quantity=" + quantity + "]";
}
测试命令：
curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
-d 'deliveryAddress=Washington nr 4&quantity=5' \
http://localhost:8080/myapp/items
返回结果：
Form parameters are [deliveryAddress=Washington nr 4, quantity=5]
9. 矩阵参数（Matrix Parameters）
矩阵参数是一种灵活的 URL 参数形式，可插入 URL 的任意位置，格式如：
http://localhost:8080/myapp/items;colors=blue,red
使用 @MatrixParam 可以读取此类参数：
@GET
public String itemColors(@MatrixParam("colors") List<String> colors) {
return "Matrix parameter values are " + Arrays.toString(colors.toArray());
}
测试命令：
curl http://localhost:8080/myapp/items;colors=blue,red
返回结果：
Matrix parameter values are [blue, red]
10. Bean 参数（Bean Parameters）
Jersey 支持将多个参数封装到一个 Java Bean 中，使用 @BeanParam 注解实现：
public class ItemOrder {
@HeaderParam("coupon")
private String coupon;
@PathParam("itemId")
private Long itemId;
@FormParam("total")
private Double total;
// getter & setter
@Override
public String toString() {
return "ItemOrder {coupon=" + coupon + ", itemId=" + itemId + ", total=" + total + '}';
}
}
接口方法中使用 @BeanParam 注入：
@POST
@Path("/{itemId}")
public String itemOrder(@BeanParam ItemOrder itemOrder) {
return itemOrder.toString();
}
测试命令：
curl -X POST -H 'Content-Type:application/x-www-form-urlencoded' \
--header 'coupon:FREE10p' \
-d total=70 \
http://localhost:8080/myapp/items/28711
返回结果：
ItemOrder {coupon=FREE10p, itemId=28711, total=70}
11. 总结
本文通过搭建一个简单的 Jersey 项目，演示了如何在 Jersey 中读取各种类型的请求参数，包括：
| 参数类型 | 注解 | 使用场景 |
|---|---|---|
| Cookie | @CookieParam |
读取客户端 Cookie 值 |
| Header | @HeaderParam |
获取 HTTP 请求头字段 |
| 路径参数 | @PathParam |
RESTful URL 中的动态值 |
| 查询参数 | @QueryParam |
URL 中的可选参数 |
| 表单参数 | @FormParam |
POST 表单提交 |
| 矩阵参数 | @MatrixParam |
更灵活的 URL 参数 |
| Bean 参数 | @BeanParam |
将多个参数封装为对象 |
掌握这些参数处理方式，能帮助你在开发 RESTful 接口时更高效地处理请求数据。