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 简单示例

@GetMapping("/users/{id}")
public String getUserById(@PathVariable("id") Long userId) {
    return "User ID: " + userId;
}

• URL 示例 ：GET /users/123
• 结果 ：userId 参数将被赋值为 123。

1.2 参数名一致时可省略

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

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

---

2. 实例

@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。

示例：

@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：参数在路径中

后端接口示例：

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

前端（fetch）：

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

前端（axios）：

import axios from 'axios';

const documentId = 1001;
axios.post(`/admin/knowledge/detail/${documentId}`);

B. @RequestParam：参数在查询字符串中

后端接口示例：

// 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）：

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

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

前端（axios）：

import axios from 'axios';

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

---

5. 进阶用法

5.1 多个路径变量

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

5.2 Map 接收所有路径变量（可选）

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

@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。