@PathVariable与@QueryParam注解的区别及适用场景

两个注解都是Web框架中用来将请求参数绑定到接口方法入参的常用组件，核心区别集中在参数位置、匹配逻辑、语义定位三个维度：

• 绑定的参数位置不同
  @PathVariable 绑定的是URL路径段中的占位符值，也就是URI模板里被{}包裹的部分，参数本身是URL路径的层级组成段；@QueryParam 绑定的是URL中?之后拼接的查询串键值对，不属于路径的固定层级组成。
• 路径匹配逻辑不同
  只要@PathVariable对应的占位符缺参、值格式不匹配，整个URL就会直接匹配失败，返回404；@QueryParam对应的参数即使不传，路径本身依然可以正常匹配，框架只会将对应入参赋值为null或者预先设置的默认值。
• 语义定位不同
  @PathVariable对应的参数天然承担「资源定位」的作用，用来指向需要操作的具体目标资源；@QueryParam对应的参数承担「资源修饰/操作调整」的作用，用来描述对匹配到的资源要做的筛选、裁剪、排序等附加操作。

直观的代码对比如下（以Java Web通用写法为例）：

// @PathVariable 用法：路径里的{id}是占位符
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
  return userService.getById(id);
}
// 匹配请求格式：GET /users/101  路径段中的101会被自动绑定到id入参

// @QueryParam 用法：绑定?后面的查询键值对
@GetMapping("/users")
public List<User> getUserList(
  @QueryParam("page") Integer page,
  @QueryParam("size") Integer size,
  @QueryParam("role") String role
) {
  return userService.listByCondition(page, size, role);
}
// 匹配请求格式：GET /users?page=1&size=20&role=admin  三个键值对会分别绑定到对应入参

实际开发中不需要死记概念，按照参数承担的作用选择即可：

应当使用@PathVariable的场景 #

• 参数是定位目标资源的唯一核心标识，缺参就无法定位要操作的资源：比如用户ID、文章ID、订单号这类，把标识放在路径里符合REST风格的资源定位语义，比如查询ID为101的用户，/users/101的可读性远高于/users?id=101。
• 需要表达资源之间的层级从属关系：比如要表示「ID为32的文章下的ID为7的评论」，用/articles/32/comments/7的路径结构，层级和资源从属关系完全对应，仅看URL就能明确资源的归属逻辑。
• 公开资源页面对URL可读性、SEO友好度有要求：带核心标识的规整路径结构更方便用户记忆，也更利于搜索引擎抓取。

应当使用@QueryParam的场景 #

• 参数用来做分页、排序、筛选、搜索这类附加操作：比如列表接口的页码、每页条数、排序规则、筛选标签，这些参数不是定位资源的必须项，只是用来调整返回结果的范围和形式，比如/goods?category=laptop&sort=price_asc&page=2，表示取笔记本分类下按价格升序排列的第二页商品。
• 参数是可选传入、存在默认值的：比如搜索接口的关键词、时间范围筛选，用户不传这些参数时，接口默认返回全量第一页结果即可，用查询参数不需要为不同的参数组合编写多套路径映射。
• 需要传递多组非层级的可选参数：比如多标签筛选、多条件组合查询的场景，用键值对格式的查询参数拼接更灵活，不会把路径段搅得混乱难读。

避坑提醒：不要把非标识类参数硬塞进路径，比如写/articles/1/20来表示第一页20条文章，看到这个路径的人根本猜不到两个数字代表页码和页大小，语义完全模糊；也不要把资源核心ID全放到查询参数里，比如/getUser?uid=123这类写法，完全丢失了路径的资源定位语义。

内容的提问来源于stack exchange，提问作者Ankit Singh