如何限制API路径变量/请求参数长度并返回自定义错误提示？

这个问题我之前也碰到过，核心原因是Spring MVC在处理@PathVariable Long id时，会先尝试把路径中的字符串转成Long类型——当输入的字符串长度超过Long的最大位数（19位）时，直接抛出NumberFormatException，根本轮不到@Max注解生效，因为参数绑定都失败了。

下面给你几个可行的解决方案，按推荐程度排序：

方案1：用String接收参数，手动校验+转换（最直接） #

把参数类型改成String，先检查长度，再尝试转成Long，这样能在第一时间拦截过长的输入，返回自定义提示：

@GetMapping("/user/{id}")
public ResponseEntity<MyClass> getById(@PathVariable String id) {
    // Long最大值是9223372036854775807，共19位
    if (id.length() > 19) {
        // 直接返回自定义错误提示，或者抛出自定义异常让全局处理器处理
        return new ResponseEntity<>(ID_LENGTH_EXCEED_MESSAGE, HttpStatus.BAD_REQUEST);
    }
    
    Long userId;
    try {
        userId = Long.parseLong(id);
    } catch (NumberFormatException e) {
        return new ResponseEntity<>("Invalid user ID format", HttpStatus.BAD_REQUEST);
    }
    
    // 额外校验：防止输入19位但超过Long.MAX_VALUE的情况
    if (userId > Long.MAX_VALUE) {
        return new ResponseEntity<>(ID_LENGTH_EXCEED_MESSAGE, HttpStatus.BAD_REQUEST);
    }
    
    // 执行业务逻辑
    // some code here
    return new ResponseEntity<>(HttpStatus.OK);
}

方案2：自定义校验注解（更优雅，复用性高） #

如果多个接口都需要类似的校验，可以自定义一个注解，专门校验字符串是否为有效的Long类型且不超过长度限制：

步骤1：创建自定义校验注解

@Target({ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ValidLongIdValidator.class)
public @interface ValidLongId {
    // 自定义错误消息，默认值可替换为你的ID_LENGTH_EXCEED_MESSAGE
    String message() default "User ID is too long or invalid";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

步骤2：实现校验器逻辑

public class ValidLongIdValidator implements ConstraintValidator<ValidLongId, String> {
    private static final int MAX_LONG_DIGITS = 19;
    private static final Long MAX_LONG_VALUE = Long.MAX_VALUE;

    @Override
    public boolean isValid(String id, ConstraintValidatorContext context) {
        if (id == null || id.isBlank()) {
            return false;
        }
        
        // 先检查长度
        if (id.length() > MAX_LONG_DIGITS) {
            // 覆盖默认消息，返回自定义提示
            context.disableDefaultConstraintViolation();
            context.buildConstraintViolationWithTemplate(ID_LENGTH_EXCEED_MESSAGE)
                   .addConstraintViolation();
            return false;
        }
        
        // 再检查是否能转成Long，且不超过最大值
        try {
            Long userId = Long.parseLong(id);
            return userId <= MAX_LONG_VALUE;
        } catch (NumberFormatException e) {
            return false;
        }
    }
}

步骤3：在接口中使用

记得给Controller类加上@Validated注解，让Spring的方法校验生效：

@Validated
@RestController
public class UserController {
    @GetMapping("/user/{id}")
    public ResponseEntity<MyClass> getById(@PathVariable @ValidLongId String id) {
        // 校验通过后转成Long
        Long userId = Long.parseLong(id);
        // 执行业务逻辑
        // some code here
        return new ResponseEntity<>(HttpStatus.OK);
    }
}

步骤4：全局异常处理（可选）

如果想统一处理校验失败的情况，可以加一个全局异常处理器，捕获ConstraintViolationException：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<String> handleConstraintViolation(ConstraintViolationException e) {
        // 提取自定义错误消息
        String errorMessage = e.getConstraintViolations().stream()
               .map(ConstraintViolation::getMessage)
               .findFirst()
               .orElse("Invalid request parameter");
        return new ResponseEntity<>(errorMessage, HttpStatus.BAD_REQUEST);
    }
}

方案3：自定义参数转换器（底层处理） #

如果不想修改参数类型，可以自定义一个Spring的Converter<String, Long>，在转换时检查长度，抛出自定义异常：

步骤1：实现转换器

@Component
public class StringToLongConverter implements Converter<String, Long> {
    private static final int MAX_LONG_DIGITS = 19;

    @Override
    public Long convert(String source) {
        if (source.length() > MAX_LONG_DIGITS) {
            throw new IllegalArgumentException(ID_LENGTH_EXCEED_MESSAGE);
        }
        try {
            return Long.parseLong(source);
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException("Invalid user ID format");
        }
    }
}

步骤2：全局异常处理

捕获IllegalArgumentException，返回自定义响应：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<String> handleIllegalArgument(IllegalArgumentException e) {
        return new ResponseEntity<>(e.getMessage(), HttpStatus.BAD_REQUEST);
    }
}

这种方法的好处是不用修改接口方法的参数类型，但需要注意全局转换器会影响所有String转Long的场景，要确保符合业务需求。

最后提醒一下：@Max注解是用来校验数值大小的，不是长度，所以当输入的字符串无法转成Long时，它根本不会触发。解决这类问题的核心是在参数绑定/转换前先做长度校验，或者拦截转换失败的异常并返回自定义提示。

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