Spring Boot中如何校验@PathVariable的null值？

核心原因 #

你遇到的问题本质和路径变量的特性、Spring的参数处理顺序有关：

1. 路径变量的必填性：RESTful设计中，/categories/{id}这类URL的{id}是标识单一资源的必填参数。当你尝试传递null（比如直接访问/categories/或未替换路径变量的/categories/:id），Spring要么找不到匹配的控制器方法（返回404），要么会先尝试将路径中的字符串（比如:id）转换为long类型，触发NumberFormatException——这一步发生在校验注解（@NotNull、@Valid）生效之前，所以你的校验逻辑根本没机会执行。
2. 基本类型的限制：用基本类型long时，它无法存储null值，一旦路径中的值无法转换为合法数字，直接抛出类型转换异常，不会进入方法体。

无效方法的原因 #

• @Valid + @NotNull：@Valid主要用于对象级别的嵌套校验，对单个@PathVariable参数的校验支持有限；且参数转换失败会提前阻断校验流程。
• 基本类型long：本身不能为null，不存在"校验null"的场景，非法输入直接触发异常。
• @Validated + @Valid + @NotNull：@Validated能开启方法级校验，但同样会被参数转换异常打断，无法触发@NotNull的校验逻辑。

可行解决方案 #

方案1：遵循REST规范，拆分接口 #

将"查询单个分类"和"查询所有分类"拆分为两个独立接口，从根源避免null路径变量的场景：

@RestController
@RequestMapping("/categories")
public class CategoryController {

    // 查询单个分类（必填id）
    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<CategoryDto>> findById(@PathVariable Long id) {
        // 业务逻辑：直接处理合法的id值
        return ResponseEntity.ok(new ApiResponse<>(true, "查询成功", categoryService.findById(id)));
    }

    // 查询所有分类（无id参数）
    @GetMapping
    public ResponseEntity<ApiResponse<List<CategoryDto>>> findAll() {
        return ResponseEntity.ok(new ApiResponse<>(true, "查询成功", categoryService.findAll()));
    }
}

此时：

• 访问/categories/123：正常匹配单个查询接口
• 访问/categories：正常匹配批量查询接口
• 访问/categories/abc：触发NumberFormatException，可通过全局异常处理器统一处理

方案2：用可选路径变量+全局异常处理 #

如果一定要在同一个接口处理有无id的场景，可设置@PathVariable(required = false)，同时处理类型转换异常：

@RestController
@RequestMapping("/categories")
public class CategoryController {

    @GetMapping({"/{id}", ""})
    public ResponseEntity<ApiResponse<?>> findCategory(@PathVariable(required = false) Long id) {
        if (id == null) {
            return ResponseEntity.ok(new ApiResponse<>(true, "查询所有分类成功", categoryService.findAll()));
        } else {
            return ResponseEntity.ok(new ApiResponse<>(true, "查询分类成功", categoryService.findById(id)));
        }
    }
}

然后添加全局异常处理器，捕获非法输入的异常：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(NumberFormatException.class)
    public ResponseEntity<ApiResponse<Void>> handleInvalidIdFormat(NumberFormatException e) {
        return ResponseEntity.badRequest()
                .body(new ApiResponse<>(false, "分类ID必须是有效的数字"));
    }
}

方案3：开启方法级校验处理合法null场景 #

若需要严格校验路径变量不能为null（比如某些特殊场景下路径变量可能被解析为null），可结合@Validated和包装类型：

@RestController
@Validated
@RequestMapping("/categories")
public class CategoryController {

    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<CategoryDto>> findById(
            @PathVariable @NotNull(message = "分类ID不能为空") Long id) {
        return ResponseEntity.ok(new ApiResponse<>(true, "查询成功", categoryService.findById(id)));
    }
}

再添加校验异常的处理器：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ApiResponse<Void>> handleValidationException(ConstraintViolationException e) {
        String message = e.getConstraintViolations().stream()
                .map(ConstraintViolation::getMessage)
                .findFirst()
                .orElse("参数校验失败");
        return ResponseEntity.badRequest().body(new ApiResponse<>(false, message));
    }
}

注意：这种场景下，只有当路径变量被Spring成功解析为null时才会触发@NotNull校验，常规的非法输入还是会触发类型转换异常。

关于Swagger和Postman的差异 #

• Swagger遵循REST规范，默认认为路径变量是必填项，因此强制要求填写合法值，不允许传递null或空值。
• Postman允许你发送未正确替换的路径变量（比如/categories/:id），此时Spring会把:id当作普通字符串处理，尝试转换为long时触发NumberFormatException，这并不是真正的"传递null路径变量"。

内容的提问来源于stack exchange，提问作者Jack