Java注解之@PathVariable，一文掌握@PathVariable注解知识(1)

🏆作者简介，普修罗双战士，一直追求不断学习和成长，在技术的道路上持续探索和实践。
🏆多年互联网行业从业经验，历任核心研发工程师，项目技术负责人。
🎉欢迎 👍点赞✍评论⭐收藏

🔎 SpringBoot 领域知识 🔎

链接	专栏
SpringBoot 注解专业知识学习一	SpringBoot 注解专栏

🏆 学习Java注解之@PathVariable

---

🔎 Java 注解@PathVariable学习(1)

---

🍁 01、@PathVariable 注解的作用是什么？

@PathVariable 注解的作用是将 URL 中的路径参数（Path parameters）绑定到方法的参数上。在 Spring MVC 中，我们可以通过在控制器（Controller）的方法参数上添加 @PathVariable 注解来获取 URL 中的变量值，并将其作为方法参数的值进行使用。

例如，假设我们有一个 RESTful API，用于获取用户信息的请求路径为 /users/{id}，其中 {id} 为用户的唯一标识。我们可以使用 @PathVariable 注解来将 URL 中的 id 变量值绑定到方法的参数上，从而在方法中可以直接使用该参数。

下面是一个示例：

@GetMapping("/users/{id}")
public String getUserInfo(@PathVariable("id") Long userId) {
    // 处理 userId 的逻辑
    return "User ID: " + userId;
}

在上述示例中，@PathVariable("id") 表示将 URL 中的 id 变量值绑定到方法的 userId 参数上。当请求路径为 /users/123 时，userId 参数的值将为 123。这样我们就可以在方法中使用 userId 参数进行相应的逻辑处理。

总结来说，@PathVariable 注解的作用是用于获取 URL 中的路径参数，并将其绑定到方法的参数上，方便在方法中使用。

---

🍁 02、@PathVariable 注解适用于哪种类型的 HTTP 请求？

@PathVariable 注解适用于使用 GET 或 DELETE 方法的 HTTP 请求。这是因为这两种方法都通过 URL（Uniform Resource Locator）传递参数，而 @PathVariable 注解正是用于从 URL 中提取路径参数值。

在 Spring MVC 中，我们可以通过在控制器方法参数上添加 @PathVariable 注解来指定要提取的路径参数，然后在方法体内进行相应的处理。

举个例子，假设我们有一个 RESTful API，用于删除用户的请求路径为 /users/{id}，其中 {id} 表示要删除的用户的唯一标识。我们可以使用 @PathVariable 注解将 URL 中的 id 参数值绑定到方法的参数上，然后在方法体内执行删除用户的逻辑。

下面是一个示例：

@DeleteMapping("/users/{id}")
public String deleteUser(@PathVariable("id") Long userId) {
    // 执行删除用户的逻辑
    return "User deleted successfully.";
}

在上述示例中，@PathVariable("id") 表示将 URL 中的 id 参数值绑定到方法的 userId 参数上，然后我们可以在方法内使用 userId 参数来执行删除用户的逻辑。

总结来说，@PathVariable 注解适用于使用 GET 或 DELETE 方法的 HTTP 请求，用于从 URL 中提取路径参数值。

除了适用于 GET 和 DELETE 方法的 HTTP 请求，@PathVariable 注解也适用于使用 PUT 和 PATCH 方法的 HTTP 请求。这些方法也可以将参数信息通过 URL 传递，因此我们可以使用 @PathVariable 注解来提取路径参数值。

PUT 方法通常用于更新资源，而 PATCH 方法通常用于部分更新资源。当我们需要在请求 URL 中传递路径参数，并在控制器方法中使用这些参数进行更新操作时，可以使用 @PathVariable 注解。

举个例子，假设我们有一个 RESTful API，用于更新用户信息的请求路径为 /users/{id}，其中 {id} 表示要更新的用户的唯一标识。我们可以使用 @PathVariable 注解将 URL 中的 id 参数值绑定到方法的参数上，然后在方法体内执行更新用户信息的逻辑。

下面是一个示例：

@PutMapping("/users/{id}")
public String updateUser(@PathVariable("id") Long userId, @RequestBody UserDto userDto) {
    // 执行更新用户信息的逻辑
    return "User updated successfully.";
}

在上述示例中，@PathVariable("id") 表示将 URL 中的 id 参数值绑定到方法的 userId 参数上。同时，我们还可以通过 @RequestBody 注解将请求体中的 JSON 数据绑定到 userDto 参数上，以便进行用户信息的更新。

总结来说，除了适用于 GET 和 DELETE 方法的 HTTP 请求，@PathVariable 注解也适用于使用 PUT 和 PATCH 方法的 HTTP 请求，用于从 URL 中提取路径参数值。这样可以方便地在控制器方法中使用这些参数来执行相应的操作。

除了适用于使用 GET、DELETE、PUT 和 PATCH 方法的 HTTP 请求，@PathVariable 注解还适用于使用 HEAD 和 OPTIONS 方法的 HTTP 请求，这些方法也可以在 URL 中传递路径参数。

HEAD 方法通常用于检查资源是否存在，而 OPTIONS 方法通常用于获取资源支持的 HTTP 方法列表。当我们需要在请求 URL 中传递路径参数，并在控制器方法中使用这些参数进行处理时，可以使用 @PathVariable 注解。

举个例子，假设我们有一个 RESTful API，用于获取用户信息的请求路径为 /users/{id}，其中 {id} 表示要获取的用户的唯一标识。我们可以使用 @PathVariable 注解将 URL 中的 id 参数值绑定到方法的参数上，然后在方法体内执行获取用户信息的逻辑。

下面是一个示例：

@HeadMapping("/users/{id}")
public ResponseEntity<Void> checkUserExistence(@PathVariable("id") Long userId) {
    // 执行检查用户是否存在的逻辑
    if (userExist(userId)) {
        return ResponseEntity.ok().build();
    } else {
        return ResponseEntity.notFound().build();
    }
}

在上述示例中，@HeadMapping 注解表示该控制器方法使用 HEAD 方法处理请求。同时，@PathVariable("id") 表示将 URL 中的 id 参数值绑定到方法的 userId 参数上。然后我们可以在方法内使用 userId 参数执行检查用户是否存在的逻辑。

总结来说，@PathVariable 注解适用于使用 GET、DELETE、PUT、PATCH、HEAD 和 OPTIONS 方法的 HTTP 请求，用于从 URL 中提取路径参数值。这样可以方便地在控制器方法中使用这些参数来执行相应的操作。

---

🍁 03、@PathVariable 注解和 @RequestParam 注解之间的主要区别是什么？

@PathVariable 注解和 @RequestParam 注解是用于从 URL 中获取参数值的 Spring MVC 注解，它们的主要区别如下：

1. 用法不同：

   • @PathVariable 注解用于从 URL 的路径中提取参数值。它将路径中的变量和注解中的参数名称进行匹配，然后将对应的值绑定到方法的参数上。例如，/users/{id} 中的 {id} 可以通过 @PathVariable("id") 注解的方式来获取值。
   • @RequestParam 注解用于从 URL 的查询参数中（即 ?key=value）提取参数值。它需要指定参数名称，并将参数值绑定到方法的参数上。例如，/users?id=123 中的 id=123 可以通过 @RequestParam("id") 注解的方式来获取值。

2. 参数位置不同：

   • @PathVariable 注解通常搭配在方法参数上作为路径的一部分。它对应于 URL 的路径变量，如 /users/{id} 中的 {id}。
   • @RequestParam 注解通常搭配在方法参数上作为查询参数的一部分。它对应于 URL 的查询参数，如 /users?id=123 中的 id=123。

3. 是否必需：

   • @PathVariable 注解默认情况下是必需的，即必须从 URL 中提取到参数值，否则将抛出异常。
   • @RequestParam 注解默认情况下是非必需的，即如果未传递该参数，方法参数将绑定为 null 或者使用预设的默认值。

综上所述，@PathVariable 注解用于从 URL 的路径中提取参数值，而 @RequestParam 注解用于从 URL 的查询参数中提取参数值。它们在用法、参数位置和是否必需等方面存在主要的区别。根据具体的需求和实际情况，可以选择使用适当的注解来获取参数值。

以下是@PathVariable注解和@RequestParam注解之间的区别的表格说明：

区别	@PathVariable 注解	@RequestParam 注解
用法	从 URL 的路径中提取参数值	从 URL 的查询参数中提取参数值
参数位置	路径变量	查询参数
是否必需	默认为必需	默认为非必需
用法示例	@GetMapping("/users/{id}") public ResponseEntity getUser(@PathVariable("id") Long id)	@GetMapping("/users") public ResponseEntity getUsers(@RequestParam("page") int page)
示例 URL	/users/123	/users?page=2
参数位置在 URL 中	路径中的一部分	查询参数的一部分

以上表格总结了@PathVariable注解和@RequestParam注解之间的主要区别。@PathVariable用于从URL的路径中提取参数值，它是路径的一部分；而@RequestParam用于从URL的查询参数中提取参数值，它是查询参数的一部分。此外，@PathVariable默认是必须的，而@RequestParam默认是非必需的。根据需求选择合适的注解来获取参数值。

---

🍁 04、@PathVariable 注解可以绑定到哪些数据类型？

@PathVariable 注解可以绑定到多种数据类型，包括但不限于以下几种常用的数据类型：

1. 基本数据类型：int、long、double、boolean 等。
2. 包装类：Integer、Long、Double、Boolean 等。
3. 字符串：String。
4. UUID：java.util.UUID。
5. 枚举类型：定义的枚举类型。
6. 自定义类型：可以通过自定义类型转换器或构造函数来将路径变量值转换为自定义类型。

需要注意的是，@PathVariable 注解的参数类型应与路径变量的数据类型相匹配或可进行适当的类型转换。如果无法进行类型转换，会发生类型不匹配的异常。对于自定义类型，需要确保有相应的类型转换器或构造函数来进行转换。

以下是一些使用 @PathVariable 注解的示例：

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
    // ...
}

@GetMapping("/products/{category}/{id}")
public ResponseEntity<Product> getProductByCategoryAndId(
    @PathVariable("category") String category,
    @PathVariable("id") int id) {
    // ...
}

@GetMapping("/orders/{orderId}")
public ResponseEntity<Order> getOrder(@PathVariable("orderId") UUID orderId) {
    // ...
}

可以根据实际情况选择适当的数据类型来绑定 @PathVariable 注解。

---

🍁 05、在 Spring MVC 中，@PathVariable 注解是如何解决 RESTful API 中的 URL 变量的？

在 Spring MVC 中，@PathVariable 注解用于解决 RESTful API 中的 URL 变量。

RESTful API 中，通过 URL 中的变量作为参数来请求资源。例如，查询用户信息时可以使用如下 URL：

https://example.com/users/{userId}

其中 {userId} 即为 URL 的变量，用于接收实际的用户 ID 值。在 Spring MVC 中，使用 @PathVariable 注解可以将 URL 的变量绑定到方法参数上，从而获取实际的参数值。

以下是一个使用 @PathVariable 注解的简单示例：

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
    User user = userService.getUserById(id);
    return ResponseEntity.ok(user);
}

这个示例中，getUserById 方法使用 @PathVariable 注解将 URL 变量 id 绑定到 Long 类型的参数上，从而获取实际的用户 ID 值。最终返回该用户的信息。

因此，@PathVariable 注解解决了 RESTful API 中 URL 变量的问题，它使得开发者能够轻松地获取 URL 中的变量值并且进行相关操作。

---

🍁 06、当 RESTful URL 中的路径参数变量值含有"/"时，@PathVariable 注解如何解决？

当 RESTful URL 中的路径参数变量值含有 “/” 时，@PathVariable 注解默认情况下是不会解析该 “/” 的，因为 “/” 在 URL 中具有特殊含义，会被用作路径分隔符。

但是，如果想要将含有 “/” 的路径参数进行解析，可以使用 @PathVariable 注解的属性 path 来指定对路径参数进行全局匹配，而不仅仅是匹配 “/” 前面的部分。

以下是一个示例，展示了如何在路径参数变量值含有 “/” 时使用 @PathVariable 注解来解决：

@GetMapping("/products/{category}/{id}")
public ResponseEntity<Product> getProductByCategoryAndId(
    @PathVariable("category") String category,
    @PathVariable(path = "id") String productId) {
    // ...
}

在这个示例中，getProductByCategoryAndId 方法使用了两个 @PathVariable 注解。对于路径参数 category，不需要明确设置 path 属性，因为我们希望其默认进行路径分隔符的匹配。而对于路径参数 id，我们设置了 path 属性为 “id”，告诉 Spring MVC 在解析路径参数时，将整个路径参数进行全局匹配，包括其中的 “/”。

例如，当请求的 URL 为 “/products/electronics/12345” 时，@PathVariable("category") 将匹配到 “electronics”，而 @PathVariable(path = "id") 将匹配到 “12345”，包括其中的 “/”。

通过设置 path 属性，开发者可以灵活地处理 RESTful URL 中路径参数变量值含有 “/” 的情况，使得 @PathVariable 注解可以正确解析路径参数的值。

---

🍁 07、@PathVariable 有 name 属性吗？

在 Spring MVC 中，@PathVariable 注解实际上没有 name 属性。正确的是它有一个 value 属性，用于指定 URL 中路径变量的名称。在使用 @PathVariable 注解时，可以省略 value 属性，此时默认会使用方法参数的名称作为路径变量的名称。

以下是一个示例，展示了如何使用 @PathVariable 注解的 value 属性：

@GetMapping("/users/{userId}")
public ResponseEntity<User> getUserById(@PathVariable(value = "userId") Long id) {
    User user = userService.getUserById(id);
    return ResponseEntity.ok(user);
}

在这个示例中，getUserById 方法使用了 @PathVariable 注解，并通过 value 属性将路径变量名称指定为 “userId”。这样，在接收到请求时，Spring MVC 将会查找 URL 中的 “userId” 路径变量，并将其值赋给 id 参数。

总之，Spring MVC 中的 @PathVariable 注解没有 name 属性，正确的属性是 value，用于指定 URL 中的路径变量名称。

---

🍁 08、@PathVariable 的 value 属性有什么作用？

在 Spring MVC 中，@PathVariable 注解的 value 属性用于指定 URL 中路径变量的名称。路径变量是指 URL 中的占位符，通过占位符可以从 URL 中提取出具体的数值，并将其绑定到方法参数上。

例如，考虑以下的请求映射：

@GetMapping("/users/{userId}")
public ResponseEntity<User> getUserById(@PathVariable("userId") Long id) {
    User user = userService.getUserById(id);
    return ResponseEntity.ok(user);
}

在上述示例中，@PathVariable 注解的 value 属性被设置为 “userId”。这意味着在接收到 /users/123 的请求时，Spring MVC 将会提取出路径变量 “123” 并将其绑定到 id 参数上。

需要注意的是，value 属性是可选的，如果省略该属性，则默认使用方法参数的名称作为路径变量的名称。例如，以下示例中的 value 属性被省略了：

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {
    User user = userService.getUserById(id);
    return ResponseEntity.ok(user);
}

在这个示例中，@PathVariable 注解没有指定 value 属性，但占位符的名称默认为 “id”，与方法参数的名称相同。

因此，value 属性使我们能够显式地指定路径变量的名称，从而增加代码的可读性和灵活性。

---

🍁 09、@PathVariable 注解在什么时候会抛出异常？

@PathVariable 注解在以下情况下可能会抛出异常：

1.当请求的 URL 中没有对应的路径变量时，会抛出 MissingPathVariableException 异常。

例如，如果定义了以下的请求映射，但请求的 URL 中没有提供对应的路径变量值：

@GetMapping("/users/{userId}")
public ResponseEntity<User> getUserById(@PathVariable("userId") Long id) {
    // ...
}

请求 /users/ 或 /users 等没有提供 userId 的值的 URL，会导致 MissingPathVariableException 异常。

2.当路径变量无法正确解析为方法参数的类型时，会抛出 MethodArgumentTypeMismatchException 异常。

例如，如果路径变量为字符串类型，但方法参数为整数类型，则会引发类型不匹配的异常：

@GetMapping("/users/{userId}")
public ResponseEntity<User> getUserById(@PathVariable("userId") Integer id) {
    // ...
}

请求 /users/abc 等将路径变量 “abc” 解析为整数时会引发 MethodArgumentTypeMismatchException 异常。

3.在URL路径中包含特殊字符时，可能会引发IllegalArgumentException异常。

有时候，URL路径中的变量值可能包含特殊字符，例如斜杠(/)、问号(?)、百分号(%)等。默认情况下，Spring MVC会将这些特殊字符进行编码处理，使其满足URL规范。但是，如果你在@PathVariable注解的value属性中指定了正则表达式，并且这个正则表达式未对特殊字符进行处理，那么就有可能抛出IllegalArgumentException异常。

例如，考虑以下的请求映射：

@GetMapping("/users/{id:.+}")
public ResponseEntity<User> getUserById(@PathVariable("id") String id) {
    // ...
}

在这个示例中，@PathVariable注解的value属性指定了正则表达式".+"，该正则表达式表示接受任意字符串。然而，如果传入的id参数中包含特殊字符，例如包含斜杠(/)，那么就会引发IllegalArgumentException异常。

为了解决这个问题，可以对路径变量进行进一步的处理，例如使用URL解码或替换特殊字符，以确保路径变量的准确性。

为了处理这些异常情况，你可以使用 Spring MVC 提供的异常处理机制，例如使用 @ExceptionHandler 注解来处理特定的异常，或者使用全局异常处理器来处理所有异常。

总之，@PathVariable 注解在缺少路径变量或者无法正确解析路径变量为方法参数类型时会抛出异常，可以通过 Spring MVC 的异常处理机制进行处理。

---

🍁 10、怎样在控制器方法中定义多个 @PathVariable 注解？

在一个控制器方法中定义多个 @PathVariable 注解很简单，只需在方法参数中添加多个 @PathVariable 注解，并指定每个注解对应的 URL 路径变量名称即可。

例如，下面的示例代码中，控制器方法 getUserByIdAndName 中定义了两个 @PathVariable 注解，分别对应路径变量 {id} 和 {name}：

@GetMapping("/users/{id}/{name}")
public ResponseEntity<User> getUserByIdAndName(@PathVariable("id") Long id, 
                                                @PathVariable("name") String name) {
    // ...
}

在上述示例代码中，@PathVariable 注解的 value 属性值指定了 URL 路径变量的名称，它们分别对应了方法参数 id 和 name，在处理请求时，Spring MVC 会将它们对应到请求 URL 中的路径变量。

注意，在定义多个 @PathVariable 注解时，要确保每个注解都指定了对应的路径变量名称，以便正确地将 URL 路径变量映射到控制器方法的参数上。

在控制器方法中定义多个 @PathVariable 注解时，还有几点需要注意：

1. 路径变量的顺序要与请求 URL 中路径变量的顺序一致，以确保正确映射。例如，如果请求的 URL 是 /users/123/john，则方法参数中的 id 对应路径变量 123，name 对应路径变量 john。

2. 可以选择性地在 @PathVariable 注解中指定路径变量的名称，例如 @PathVariable("id")。如果注解中未指定名称，则默认使用方法参数名作为路径变量的名称。

3. 如果路径变量名称与方法参数名称相同，可以省略 @PathVariable 注解中的名称，例如 @PathVariable Long id。在这种情况下，框架会自动将路径变量映射到相同名称的方法参数上。

例如，下面的示例代码演示了这些注意事项：

@GetMapping("/users/{id}/{name}")
public ResponseEntity<User> getUserByIdAndName(@PathVariable Long id, 
                                                @PathVariable("name") String userName) {
    // ...
}

在上述示例中，@PathVariable 注解的名称与方法参数名称相同，因此可以省略名称的指定。id 对应路径变量 id，userName 对应路径变量 name。

总结一下，为了在控制器方法中定义多个 @PathVariable 注解，确保路径变量的顺序与请求 URL 中的路径变量顺序一致，可以选择性地指定注解中的路径变量名称，或者省略名称的指定如果路径变量和方法参数名称相同。