Spring MVC:@PathVariable 注解详解

Spring MVC @PathVariable 注解详解

适用范围:Spring MVC / Spring Boot Web(@RestController / @Controller)

@PathVariable 用于将 URL 模板变量(URL path 中的占位符)绑定到控制器处理方法的参数上。它是实现 RESTful 风格接口的核心注解之一。


1. 基本用法

在 @RequestMapping(或其变体如 @GetMapping, @PostMapping)的路径中使用 {variableName} 定义占位符,然后在方法参数中使用 @PathVariable 引用它。

1.1 简单示例

java 复制代码
@GetMapping("/users/{id}")
public String getUserById(@PathVariable("id") Long userId) {
    return "User ID: " + userId;
}
  • URL 示例 :GET /users/123
  • 结果 :userId 参数将被赋值为 123。

1.2 参数名一致时可省略

如果路径变量名与方法参数名完全一致,可以省略注解中的名称:

java 复制代码
@GetMapping("/users/{id}")
public String getUserById(@PathVariable Long id) { // 自动匹配 {id}
    return "User ID: " + id;
}

2. 实例

java 复制代码
@PostMapping("/delete/{documentId}")
public BaseResponse<String> deleteDocument(@PathVariable Long documentId) {
    // ...
    knowledgeDocumentService.deleteDocument(documentId);
    return BaseResponse.success(MessageConstant.DELETE_SUCCESS);
}
  • 请求方式 :POST /delete/1001
  • 含义 :URL 最后的 1001 会被自动提取并赋值给 documentId。

3. 常见属性

属性 类型 默认值 说明
value / name String "" 指定绑定的路径变量名称。
required boolean true 是否必须包含该路径变量。如果为 true 且路径中缺失,会报 404。

示例:

java 复制代码
@GetMapping("/users/{id}")
public String demo(@PathVariable(name = "id", required = true) Long userId) {
    return "ok";
}

4. @PathVariable vs @RequestParam

这两者经常被混淆,它们的区别主要在于 参数在 URL 中的位置:

特性 @PathVariable @RequestParam
位置 URL 路径的一部分 (Path) URL 查询字符串 (Query String)
风格 RESTful 风格 传统查询参数风格
示例 URL /users/123 /users?id=123
定义方式 @GetMapping("/users/{id}") @GetMapping("/users")
场景 标识资源 ID、分类等固定结构 过滤、排序、分页、可选搜索条件

4.1 前端请求代码示例(对比)

下面用前端常见的 fetch(原生)与 axios(第三方库)分别演示两种传参方式。

A. @PathVariable:参数在路径中

后端接口示例:

java 复制代码
// GET /admin/knowledge/detail/{documentId}
@PostMapping("/detail/{documentId}")
public BaseResponse<KnowledgeDocument> getDocumentDetail(@PathVariable Long documentId) {
    // ...
}

前端(fetch):

js 复制代码
const documentId = 1001;
fetch(`/admin/knowledge/detail/${documentId}`, {
  method: 'POST',
});

前端(axios):

js 复制代码
import axios from 'axios';

const documentId = 1001;
axios.post(`/admin/knowledge/detail/${documentId}`);
B. @RequestParam:参数在查询字符串中

后端接口示例:

java 复制代码
// POST /admin/knowledge/list?current=1&pageSize=10&name=xxx&type=pdf
@PostMapping("/list")
public BaseResponse<Page<KnowledgeDocument>> listDocuments(
        @RequestParam(defaultValue = "1") int current,
        @RequestParam(defaultValue = "10") int pageSize,
        @RequestParam(value = "name", required = false) String name,
        @RequestParam(value = "type", required = false) String type) {
    // ...
}

前端(fetch):

js 复制代码
const params = new URLSearchParams({
  current: '1',
  pageSize: '10',
  name: '饲养指南',
  type: 'pdf',
});

fetch(`/admin/knowledge/list?${params.toString()}`, {
  method: 'POST',
});

前端(axios):

js 复制代码
import axios from 'axios';

axios.post('/admin/knowledge/list', null, {
  params: {
    current: 1,
    pageSize: 10,
    name: '饲养指南',
    type: 'pdf',
  },
});

5. 进阶用法

5.1 多个路径变量

java 复制代码
@GetMapping("/category/{catId}/product/{prodId}")
public String getProduct(
        @PathVariable Long catId,
        @PathVariable Long prodId) {
    return "Category: " + catId + ", Product: " + prodId;
}

5.2 Map 接收所有路径变量(可选)

当路径变量较多时,可以用 Map 一次性接收:

java 复制代码
@GetMapping("/users/{userId}/orders/{orderId}")
public String demo(@PathVariable Map<String, String> vars) {
    return vars.toString();
}

6. 一句话总结

  • @PathVariable 是从 URL 路径 取值(如 /api/item/1)。
  • 它让 URL 看起来更简洁、更符合 RESTful 规范。
  • 操作特定资源(查单条、删除、更新)时,通常优先选 @PathVariable。
相关推荐
Highcharts.js4 小时前
Highcharts漏斗图表使用配置指南
java·开发语言·javascript·信息可视化·highcharts·漏斗图
武昌库里写JAVA8 小时前
SpringBoot+Vue 项目介绍
java·javascript·git·sql·ai
学长毕设9 小时前
基于SpringBoot的儿童慈善捐赠管理系统-附源码
java·spring boot·后端
慧一居士9 小时前
@RestControllerAdvice 的注解作用和使用
java
学长毕设10 小时前
基于SpringBoot非遗文化展示与传播平台设计与实现-附源码
java·spring boot·后端
金銀銅鐵12 小时前
用 Swing 重做操作数栈演示
java·jvm·后端
琳少_12 小时前
java程序开发笔记
java·开发语言·数据库·笔记
叼烟扛炮14 小时前
[LangChain] 学习笔记(15):为什么你的重试没用——429、抖动、fallback 与熔断
java·服务器·前端
文丑颜不良啊15 小时前
LeetCode3401~3420题目解析
java·leetcode
文丑颜不良啊16 小时前
LeetCode3421~3440题目解析
java·leetcode