接口参数校验之路径变量：@PathVariable

一、引言

1. 描述在RESTful API设计中路径变量的重要性，以及Spring MVC框架中的@PathVariable注解的作用。
2. 简述为何进行接口参数校验具有必要性，尤其是对于路径变量这一特殊类型的参数。

1. 在 RESTful API 设计中，路径变量的重要性

在 RESTful API 设计中，路径变量扮演着至关重要的角色。遵循REST原则，URL被设计为表述资源的唯一地址，其中路径变量作为动态部分，使得API能够更加灵活地定位和操作具体资源。例如，在一个用户管理API中，/users/{userId}中的{userId}就是路径变量，它可以用于标识和操作特定的用户信息。

2. Spring MVC框架中的@PathVariable注解的作用

Spring MVC框架为此提供了一个强大的注解——@PathVariable。通过在控制器方法参数上使用此注解，开发人员可以方便地将请求URL中的路径变量映射到方法参数，从而实现对动态资源的精准获取与处理。如@GetMapping("/users/{userId}") public User getUser(@PathVariable String userId)，这样当客户端访问/users/123时，服务端就能够自动将"123"注入到userId参数中。

3. 接口参数校验的必要性

接口参数校验是保障系统安全性和稳定性的重要环节。对于路径变量这类特殊类型的参数，其校验显得更为关键。由于路径变量直接体现在URL中，如果不对它们进行有效校验和过滤，可能会导致以下问题：

1. 安全风险：恶意攻击者可能尝试通过构造非法或不存在的路径变量值来访问未经授权的资源，甚至执行SQL注入等攻击。
2. 逻辑错误：若路径变量对应的数据类型不匹配或者值不在预期范围内，可能会引发运行时异常，影响系统的正常运行和服务质量。

因此，确保对接口路径变量进行严谨的校验，不仅有助于提升API的安全性，还能减少因数据异常造成的程序错误，保证服务的稳定性和健壮性。

二、@PathVariable基础概念解析

1. 定义：详细解释@PathVariable注解的含义及应用场景，展示如何在控制器方法中使用它来绑定URL路径模板中的变量。
2. 示例代码：提供一段示例代码展示如何在实际接口开发中使用@PathVariable获取并处理路径参数。

在Spring MVC框架中，@PathVariable注解是一个用于从请求URL路径中提取并绑定动态参数的关键工具。其含义是将URL模板中的特定部分映射到控制器方法的参数上，使得开发者能够根据实际传入的路径变量值来执行不同的业务逻辑。

1. 定义与应用场景

当设计RESTful API时，通常会使用路径变量来标识资源的唯一性或描述资源的某种属性。例如，一个获取用户信息的API可能设计为/users/{userId}，其中{userId}就是一个路径变量，代表要查询的具体用户的ID。通过在控制器方法参数前添加@PathVariable注解，并指定一个与路径模板中变量名相匹配的名称，Spring MVC就能自动将请求URL中的对应部分赋值给该参数。

2. 示例代码

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @GetMapping("/users/{userId}")
    public User getUser(@PathVariable("userId") String userId) {
        // 这里可以调用服务层方法，根据userId获取用户信息
        return userService.getUserById(userId);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

在这个例子中，@PathVariable("userId")告诉Spring MVC框架，应该从请求URL /users/{任意数字} 中提取出userId部分，并将其转换为String类型，然后传递给getUser方法作为参数。这样，每当客户端发起如/users/123的GET请求时，服务器将会执行获取ID为123的用户信息的操作。

三、@PathVariable参数校验的重要性

1. 阐述未对@PathVariable进行有效校验可能导致的安全隐患，例如非法数据注入、资源越权访问等问题。
2. 分析在业务逻辑层面对路径变量进行校验的局限性和不足。

1. 安全隐患分析

未对@PathVariable进行有效校验，会使得系统暴露在一系列安全风险之下。例如：

• 非法数据注入：如果路径变量没有经过严格的类型转换和格式校验，恶意用户可能通过构造特殊的输入值来尝试SQL注入或其他类型的注入攻击。比如，在一个类似/users/{id}的接口中，若不对id做整数校验，攻击者可能会传入精心设计的SQL语句片段，企图绕过数据库层的安全防护。
• 资源越权访问：假设URL中的路径变量代表的是资源ID，如果没有进行有效的存在性和权限校验，任何知道或猜测到正确ID的用户都可能获取或者操作不属于他们自己的资源，从而导致信息泄露或破坏。

2. 业务逻辑层校验局限性与不足

在业务逻辑层进行路径变量的校验虽然可以实现一定程度的数据合法性检查，但这种做法存在以下问题：

• 分散式处理：将校验逻辑分散到各个业务方法中，不仅重复劳动且不易于维护，违反了DRY（Don’t Repeat Yourself）原则。
• 异常处理不统一：不同控制器或服务方法中校验逻辑和异常处理方式可能存在差异，导致响应的一致性和用户体验不佳。
• 全局性缺失：仅在业务逻辑层校验无法覆盖所有API入口，容易出现遗漏，而且对于一些基础的、通用的约束条件（如ID必须为正数、邮箱格式等），不能提供全局的强制性校验。
• 性能损耗：由于是在执行链路的较后阶段进行校验，当校验失败时，可能已经触发了不必要的数据库查询或其他资源消耗。

因此，提倡在请求到达控制器之前，利用Spring框架提供的机制（如JSR-303/JSR-380规范的注解验证，或自定义处理器等方式）对@PathVariable参数进行集中、标准和全面的校验，以确保API的安全性和健壮性。

四、实现@PathVariable参数校验的方法

介绍如何通过Spring Validation模块（如JSR-303/JSR-349或Hibernate Validator）对@PathVariable进行数据校验，包括自定义注解、编写Validator等方法。

1. 使用标准注解进行校验

在Spring框架中，可以利用标准Bean Validation注解实现对控制器方法的@PathVariable参数进行校验。

首先，为了启用验证功能，需要在类级别使用@Validated注解。然后，在@PathVariable绑定的 路径变量 上直接添加校验注解，并设置相应的校验规则和错误提示信息。

通过这种方式，在接收到不符合规则的 路径变量 时，系统会自动抛出异常并并附带详细的错误信息。

下面，以校验路径变量 用户ID 为19位正整数为例进行说明。

关键注解

三个关键注解如下：

• @Validated // 必须在类级别启用校验功能，放在控制器方法参数前不起作用
• @PathVariable
• @Pattern(regexp = "^\\d{19}$", message = "用户ID，应为19位数字") // 校验规则，19位正整数

图片示意

示例代码

package com.example.web.user.controller;

import com.example.web.model.vo.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.constraints.Pattern;

@Validated // 必须在类级别启用验证功能
@RestController
@RequestMapping("users")
@Tag(name = "用户管理")
public class UserController {

    @GetMapping("{id}")
    @Operation(summary = "查询用户")
    @Parameter(name = "id", description = "用户ID", example = "1234567890123456789")
    public UserVO getUser(@PathVariable @Pattern(regexp = "^\\d{19}$", message = "用户ID，应为19位数字") String id) {
        UserVO vo = new UserVO();
        vo.setId(id);
        vo.setName("张三");
        vo.setMobilePhone("18612345678");
        vo.setEmail("zhangsan@example.com");
        return vo;
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

校验成功示例

校验失败示例

2. 自定义注解与Validator

在处理复杂或特定的校验需求时，可以创建自定义注解并关联一个自定义Validator进行校验逻辑实现。

下面，以校验路径变量 用户ID 为19位正整数为例进行说明。

自定义注解

首先创建了一个名为@Id的自定义注解，并通过其description属性提供更具体的描述信息。

package com.example.core.validation.id;

import javax.validation.Constraint;
import javax.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * 字符串必须是格式正确的ID。正确格式为：19位数字。
 * <p>
 * null 是无效的，不能够通过校验。
 * <p>
 * 支持的类型：字符串
 *
 * @author songguanxun
 * @since 2024-1-20
 */
@Target({PARAMETER})
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = IdValidator.class)
public @interface Id {
    String message() default "ID，必须为19位数字";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    /**
     * ID的详细描述，比如：用户ID。
     * <p>
     * 用来替换 {@link #message} 中的“ID”，使描述信息更具体。
     */
    String description() default "";

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

Validator

接着，编写了对应的IdValidator类作为校验器，实现了ConstraintValidator<Id, String>接口以执行实际的校验逻辑。

package com.example.core.validation.id;

import com.example.core.validation.ResetMessageUtil;
import org.springframework.util.StringUtils;

import javax.validation.ConstraintValidator;
import javax.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;

/**
 * ID，格式校验器。
 * <p>
 * 当前ID的格式：必须为19位数字。
 */
public class IdValidator implements ConstraintValidator<Id, String> {

    private String description;

    @Override
    public void initialize(Id constraintAnnotation) {
        description = constraintAnnotation.description();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        if (!StringUtils.hasText(value)) {
            if (StringUtils.hasText(description)) {
                // 根据description，优化提示信息。
                String message = String.format("%s，不能为空", description);
                ResetMessageUtil.reset(context, message);
            } else {
                ResetMessageUtil.reset(context, "ID，不能为空");
            }
            return false;
        }

        if (!isValid(value)) {
            // 根据description，优化提示信息。
            if (StringUtils.hasText(description)) {
                String message = String.format("%s，必须为19位数字", description);
                ResetMessageUtil.reset(context, message);
            }
            return false;
        }

        return true;
    }

    private final Pattern PATTERN = Pattern.compile("^\\d{19}$");

    /**
     * 是有效的ID
     */
    private boolean isValid(String value) {
        return PATTERN.matcher(value).matches();
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

使用自定义注解

在Controller层，通过在 路径参数 上使用自定义的@Id注解，并确保控制器类已被@Validated注解启用验证功能，即可在接收到请求时自动调用自定义的验证逻辑。

package com.example.web.user.controller;

import com.example.core.validation.id.Id;
import com.example.web.model.vo.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Validated
@RestController
@RequestMapping("users")
@Tag(name = "用户管理")
public class UserController {

    @GetMapping("{id}")
    @Operation(summary = "查询用户")
    @Parameter(name = "id", description = "用户ID", example = "1234567890123456789")
    public UserVO getUser(@PathVariable @Id(description = "用户ID") String id) {
        UserVO vo = new UserVO();
        vo.setId(id);
        vo.setName("张三");
        vo.setMobilePhone("18612345678");
        vo.setEmail("zhangsan@example.com");
        return vo;
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

使用自定义注解的校验效果，和使用标准注解进行校验的效果，是完全相同的。

五、最佳实践与异常统一处理

在实际开发过程中，遇到路径变量校验失败时如何优雅地反馈给客户端的问题？推荐的做法是：

• 定义全局异常处理器（如@RestControllerAdvice配合@ExceptionHandler注解），捕获与参数校验相关的异常，如ConstraintViolationException、自定义的业务异常等。

• 在异常处理器中，根据不同的异常类型和场景，转换成具有统一格式的错误响应信息，通常包含错误码、错误描述和可能需要的附加信息。

• 返回HTTP状态码适当的响应，如400 Bad Request表示客户端请求的语法错误（如路径变量不合法）。

通过上述最佳实践，不仅可以确保对@PathVariable参数进行有效的校验，还可以提升系统的健壮性，降低耦合度，并提供友好的错误反馈信息。

路径变量校验失败，会抛出ConstraintViolationException异常，通过异常统一处理来对此异常进行处理。具体的实现细节，请参考如下文章：《全局异常统一处理之约束违反异常：ConstraintViolationException》

六、总结

在RESTful API设计中，路径变量是URL路径模板中的动态部分，对于精确定位和操作特定资源至关重要。Spring MVC框架通过@PathVariable注解实现了将请求URL中的路径变量映射到控制器方法参数的功能，极大地提高了API的灵活性与可读性。

对路径变量进行严格的校验是非常必要的，因为它直接关系到系统的安全性、稳定性和用户体验。未经校验的路径变量可能导致非法数据注入攻击、资源越权访问等问题。仅仅依赖业务逻辑层的分散式校验并不足够，因此提倡在请求处理链路的早期阶段就利用Spring Validation模块或自定义验证器对@PathVariable进行集中且全面的数据校验。

为了实现这一目标，开发者可以使用标准的Bean Validation注解（如JSR-303/JSR-349）对@PathVariable参数进行约束，或者创建自定义注解及对应的Validator来满足更复杂或特定的校验需求。同时，通过全局异常处理器如@RestControllerAdvice结合@ExceptionHandler注解，能够统一处理参数校验失败引发的异常，并优雅地反馈给客户端，确保系统健壮性的同时提升用户体验。