Spring 中可选路径变量的使用

1. 概述

本文将深入探讨如何在 Spring 中实现路径变量（Path Variable）的可选化。我们会先回顾 Spring 是如何绑定 @PathVariable 参数的，然后重点介绍在不同 Spring 版本中让路径变量变为可选的几种方式。

如果你对路径变量的基础概念还不熟悉，建议先阅读我们关于 Spring MVC 的文章快速回顾一下。

2. Spring 如何绑定 @PathVariable 参数

默认情况下，Spring 会尝试将处理器方法中标记了 @PathVariable 的所有参数，与 URI 模板中的同名变量进行绑定。如果绑定失败，该请求将不会被路由到这个处理方法。

举个例子，下面这个 getArticle 方法试图（但失败了）让 id 成为可选的路径变量：

@RequestMapping(value = {"/article/{id}"})
public Article getArticle(@PathVariable(name = "id") Integer articleId) {
    if (articleId != null) {
        //...
    } else {
        //...
    }
}

这个方法本意是想同时处理 /article 和 /article/{id} 两种请求。当请求 /article/123 时，articleId 能成功绑定为 123 ✅。

但问题来了：当你访问 /article 时，Spring 会直接抛出 500 错误 ❌，异常如下：

org.springframework.web.bind.MissingPathVariableException:
  Missing URI template variable 'id' for method parameter of type Integer

原因很简单：URI 中没有 id，Spring 找不到值去填充 articleId 参数，于是直接放弃调用该方法。

⚠️ 所以我们必须明确告诉 Spring：某些 @PathVariable 是可选的，即使 URI 中没有对应变量也不要报错。

接下来就看看几种靠谱的解决方案。

3. 让路径变量变为可选的方式

3.1. 使用 @PathVariable 的 required 属性（推荐）

从 Spring 4.3.3 开始，@PathVariable 注解新增了一个 required 属性，用来声明该变量是否必须存在。

✅ 正确写法如下：

@RequestMapping(value = {"/article", "/article/{id}"})
public Article getArticle(@PathVariable(required = false) Integer articleId) {
   if (articleId != null) {
       // 处理有 ID 的情况
   } else {
       // 处理无 ID 的情况（返回默认文章等）
   }
}

关键点：

required = false 表示这个路径变量可选
如果 URI 包含 {id}，articleId 就会被赋值
如果没有，articleId 为 null，不会抛异常

⚠️ 注意：required = true 是默认行为，一旦缺失就会抛 MissingPathVariableException。

这个方式简单粗暴，适合绝大多数场景，建议优先使用。

3.2. 使用 Optional 类型参数（函数式风格）

如果你的项目用的是 Spring 4.1+ 并且支持 **JDK 8+**，可以考虑使用 Optional<T> 作为参数类型，代码更“现代”一些：

@RequestMapping(value = {"/article", "/article/{id}"})
public Article getArticle(@PathVariable Optional<Integer> optionalArticleId) {
    if (optionalArticleId.isPresent()) {
        Integer articleId = optionalArticleId.get();
        // 处理有 ID 的情况
    } else {
        // 处理无 ID 的情况
    }
}

Spring 会自动把路径变量封装进 Optional：

有值 → Optional.of(value)
无值 → Optional.empty()

你可以用 isPresent()、get() 或 orElse() 等方法安全地操作值，避免空指针。

✅ 优点：语义清晰，符合函数式编程习惯
❌ 缺点：对老项目不友好，需要 JDK 8 支持

3.3. 使用 Map 接收所有路径变量（灵活但啰嗦）

从 Spring 3.2 开始，允许用 Map<String, String> 接收所有路径变量，适合变量较多或动态场景：

@RequestMapping(value = {"/article", "/article/{id}"})
public Article getArticle(@PathVariable Map<String, String> pathVarsMap) {
    String articleIdStr = pathVarsMap.get("id");
    if (articleIdStr != null) {
        Integer articleId = Integer.valueOf(articleIdStr);
        // 处理有 ID 的情况
    } else {
        // 处理无 ID 的情况
    }
}

要点：

所有路径变量都以键值对形式存入 Map
值的类型是 String，需要手动转换（如 Integer.valueOf）
适合处理多个可选路径变量的复杂场景

⚠️ 踩坑提醒：类型转换可能抛 NumberFormatException，记得加 try-catch 或做校验。

3.4. 拆分为两个独立接口（兼容老版本）

如果你还在用很老的 Spring 版本（早于 4.1），required 和 Optional 都不可用，那就只能“暴力拆分”：

// 处理带 ID 的请求
@RequestMapping(value = "/article/{id}")
public Article getArticle(@PathVariable(name = "id") Integer articleId) {
    //...
}

// 处理不带 ID 的请求
@RequestMapping(value = "/article")
public Article getDefaultArticle() {
    // 返回默认文章或其他逻辑
}

✅ 优点：兼容性最好，逻辑清晰
❌ 缺点：代码重复，维护成本高，URL 映射变多

适合无法升级 Spring 版本的遗留系统。

4. 总结

方式	Spring 版本	推荐度	适用场景
`required = false`	4.3.3+	✅✅✅	绝大多数情况，首选
`Optional<T>`	4.1+ + JDK 8	✅✅	追求代码优雅，函数式风格
`Map<String, String>`	3.2+	✅	多变量、动态路径场景
拆分接口	任意版本	⚠️	老系统兼容，迫不得已

📌 最终建议：

新项目直接用 @PathVariable(required = false)，简单高效
已用 JDK 8 的项目可尝试 Optional，提升代码可读性
老系统实在没法升级，再考虑拆方法或 Map 方式

完整示例代码已托管至 GitHub：

https://github.com/eugenp/tutorials/tree/master/spring-web-modules/spring-mvc-basics-4

Persistence

REST

Security