OpenAPI定义可选请求对象但含必填字段的验证问题

问题根源 #

Spring Boot会自动实例化@RequestParam/@ModelAttribute绑定的查询对象，哪怕没有传入任何字段，此时对象内的必填字段为null，直接触发JSR-380验证失败。下面是几种可行的解决思路：

方案一：OpenAPI配置+自定义类级验证注解（推荐） #

1. 调整OpenAPI YAML配置 #

将整个请求对象设为可选，同时保留对象内部字段的必填规则：

parameters:
  - name: pagination
    in: query
    schema:
      $ref: '#/components/schemas/Pagination'
    required: false # 整个对象允许省略
  - name: sorting
    in: query
    schema:
      $ref: '#/components/schemas/Sorting'
    required: false

components:
  schemas:
    Pagination:
      type: object
      required: [page, size] # 对象内部字段必填
      properties:
        page:
          type: integer
          minimum: 1
        size:
          type: integer
          minimum: 1
    Sorting:
      type: object
      required: [field, direction]
      properties:
        field:
          type: string
        direction:
          type: string
          enum: [ASC, DESC]

2. 自定义@ValidIfPresent验证注解 #

实现"对象不为null时才触发内部验证"的逻辑：

@Target({ElementType.TYPE, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = ValidIfPresentValidator.class)
public @interface ValidIfPresent {
    String message() default "传入对象时，所有必填字段必须填写完整";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class ValidIfPresentValidator implements ConstraintValidator<ValidIfPresent, Object> {
    private final Validator validator;

    public ValidIfPresentValidator(Validator validator) {
        this.validator = validator;
    }

    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {
        if (value == null) return true; // 对象为null时跳过验证

        Set<ConstraintViolation<Object>> violations = validator.validate(value);
        if (!violations.isEmpty()) {
            context.disableDefaultConstraintViolation();
            violations.forEach(violation -> 
                context.buildConstraintViolationWithTemplate(violation.getMessage())
                        .addPropertyNode(violation.getPropertyPath().toString())
                        .addConstraintViolation()
            );
            return false;
        }
        return true;
    }
}

3. 让生成器自动添加注解 #

在YAML参数中添加扩展配置，让生成的控制器参数带上@ValidIfPresent：

parameters:
  - name: pagination
    in: query
    schema:
      $ref: '#/components/schemas/Pagination'
    required: false
    x-java-annotations:
      - "@com.yourpackage.ValidIfPresent"

方案二：修改Spring参数绑定行为 #

通过自定义参数解析器，让未传入任何字段的查询对象绑定为null：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new OptionalQueryObjectResolver());
    }

    private static class OptionalQueryObjectResolver implements HandlerMethodArgumentResolver {
        @Override
        public boolean supportsParameter(MethodParameter parameter) {
            // 匹配需要处理的对象类型
            return Pagination.class.isAssignableFrom(parameter.getParameterType())
                    || Sorting.class.isAssignableFrom(parameter.getParameterType());
        }

        @Override
        public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                      NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
            String paramPrefix = parameter.getParameterName();
            // 检查是否有该对象的任何字段被传入
            boolean hasAnyField = Arrays.stream(webRequest.getParameterNames())
                    .anyMatch(name -> name.startsWith(paramPrefix + "."));

            if (!hasAnyField) return null; // 无字段传入时返回null

            // 正常绑定并验证对象
            WebDataBinder binder = binderFactory.createBinder(webRequest, null, paramPrefix);
            binder.bind(webRequest);
            binder.validate();
            return binder.getTarget();
        }
    }
}

此方案下，只要没传入对象的任何字段，对象就是null，不会触发验证；一旦传入任意字段，就会绑定对象并验证内部必填规则。

方案三：编程式验证（简单直接） #

如果不想折腾配置和注解，可直接在控制器手动处理：

1. 先移除OpenAPI YAML中对象内部的required声明，避免生成@NotNull等注解；
2. 在控制器方法内判断并验证：

@GetMapping("/list")
public ResponseEntity<List<Data>> getList(
        @RequestParam(required = false) Pagination pagination,
        @RequestParam(required = false) Sorting sorting) {
    // 验证Pagination
    if (pagination != null) {
        List<String> errors = new ArrayList<>();
        if (pagination.getPage() == null || pagination.getPage() < 1) {
            errors.add("page必须是大于等于1的整数");
        }
        if (pagination.getSize() == null || pagination.getSize() < 1) {
            errors.add("size必须是大于等于1的整数");
        }
        if (!errors.isEmpty()) {
            return ResponseEntity.badRequest().body(errors);
        }
    }
    // 同理验证Sorting...
    // 执行业务逻辑
    return ResponseEntity.ok(dataService.query(pagination, sorting));
}

缺点是验证逻辑和业务代码耦合，YAML变更时需要同步修改验证代码。

额外建议 #

如果可以升级到OpenAPI 3.1.x，它支持更灵活的nullable和验证规则定义，配合最新版OpenAPI生成器能减少部分配置工作，但核心的Spring对象实例化问题仍需结合上述方案解决。

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