Spring Boot：重命名必填请求参数时的二选一校验实现

要实现旧参数group弃用、新参数pageGroup上线，且二者必须二选一传入的需求，你可以按以下几种方式实现：

1. 基础逻辑兼容（快速落地） #

直接在Controller方法里同时接收两个非必填参数，然后在方法内部做判断处理：

@GetMapping("/your-api-path")
public ResponseEntity<?> handleRequest(
        @RequestParam(value = "group", required = false) String oldGroupParam,
        @RequestParam(value = "pageGroup", required = false) String newPageGroupParam) {
    
    // 禁止同时传入两个参数
    if (oldGroupParam != null && newPageGroupParam != null) {
        return ResponseEntity.badRequest().body("请勿同时传入group和pageGroup参数");
    }
    
    // 确定最终使用的参数
    String targetGroup;
    if (newPageGroupParam != null) {
        targetGroup = newPageGroupParam;
    } else if (oldGroupParam != null) {
        targetGroup = oldGroupParam;
    } else {
        // 两个都没传，返回参数错误
        return ResponseEntity.badRequest().body("必须传入group或pageGroup参数");
    }

    // 业务逻辑处理
    return ResponseEntity.ok("处理成功，分组值：" + targetGroup);
}

2. 自定义校验注解（优雅复用） #

如果多个接口都有类似的二选一参数需求，可以自定义校验注解统一处理，避免重复代码：

第一步：定义校验注解 #

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = OneOfTwoParamsValidator.class)
public @interface OneOfTwoParams {
    String firstParam();
    String secondParam();
    String message() default "必须传入{firstParam}或{secondParam}参数";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

第二步：实现校验器逻辑 #

public class OneOfTwoParamsValidator implements ConstraintValidator<OneOfTwoParams, Object> {
    private String firstParam;
    private String secondParam;

    @Override
    public void initialize(OneOfTwoParams annotation) {
        this.firstParam = annotation.firstParam();
        this.secondParam = annotation.secondParam();
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        ServletRequestAttributes requestAttrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (requestAttrs == null) return false;
        
        HttpServletRequest request = requestAttrs.getRequest();
        String firstValue = request.getParameter(firstParam);
        String secondValue = request.getParameter(secondParam);

        // 校验规则：至少传一个，且不能同时传
        boolean hasAtLeastOne = (firstValue != null && !firstValue.isBlank()) || (secondValue != null && !secondValue.isBlank());
        boolean notBothPresent = !(firstValue != null && !firstValue.isBlank() && secondValue != null && !secondValue.isBlank());
        
        return hasAtLeastOne && notBothPresent;
    }
}

第三步：在Controller中使用 #

记得给Controller类加上@Validated注解开启校验：

@RestController
@Validated
public class YourController {

    @GetMapping("/your-api-path")
    @OneOfTwoParams(firstParam = "group", secondParam = "pageGroup", message = "必须传入group或pageGroup参数，且不能同时传入")
    public ResponseEntity<?> handleRequest(
            @RequestParam(value = "group", required = false) @Deprecated(message = "该参数已弃用，请使用pageGroup") String oldGroupParam,
            @RequestParam(value = "pageGroup", required = false) String newPageGroupParam) {
        
        String targetGroup = newPageGroupParam != null ? newPageGroupParam : oldGroupParam;
        // 业务逻辑处理
        return ResponseEntity.ok("处理成功，分组值：" + targetGroup);
    }
}

3. 标记旧参数弃用 #

用@Deprecated注解标记旧参数，配合接口文档工具（比如Swagger）可以明确提示客户端开发者迁移到新参数，减少后续兼容性问题。

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