Spring Boot REST API类型不匹配时将查询参数设为默认值

问题背景 #

我们基于Spring Boot和OpenAPI代码生成器构建REST API，其中/user路径的GET接口定义了非必填的id查询参数（类型为int64）：

...
"paths": {
    "/user": {
        "get": {
            "parameters": [{
                "name": "id",
                "in": "query",
                "required": false,
                "type": "integer",
                "format": "int64"
            }],
            "responses": { ... }
        }
    }
    // 更多路径定义
}
...

代码生成器自动生成接口MyControllerApi，控制器实现后，当请求/user?id=abcd这类参数类型不匹配的请求时，Spring Boot会直接返回400 Bad Request：

{
    "timestamp": "2022-10-19T17:20:48.393+0000",
    "status": 400,
    "error": "Bad Request",
    "path": "/user"
}

我们需要实现：所有类型为Long或Boolean的非必填查询参数，在类型不匹配时自动设为null，而非返回400错误，且该规则要覆盖API中大量路径和参数。

已尝试的无效方案 #

1. 启用OpenAPI生成器的useOptional选项 #

在pom.xml中配置该选项后，生成的控制器方法参数会变为Optional<?>类型，但参数类型不匹配时仍会返回400错误，无法满足需求。

2. 使用请求拦截器 #

尝试通过HandlerInterceptor预处理请求，但遇到瓶颈：无法通过RequestParam注解获取参数类型，且编译后的类无法通过MethodParameter获取参数名称，无法完成参数类型与请求值的匹配处理。

可行解决方案：自定义全局参数解析器 #

通过实现HandlerMethodArgumentResolver，针对指定类型的非必填查询参数，在解析失败时返回null，优先级高于Spring默认的参数解析器。

1. 实现参数解析器 #

@Component
public class TolerantRequestParamResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        // 匹配条件：带有@RequestParam注解、非必填、类型为Long或Boolean
        RequestParam requestParam = parameter.getParameterAnnotation(RequestParam.class);
        if (requestParam == null || requestParam.required()) {
            return false;
        }
        Class<?> paramType = parameter.getParameterType();
        return paramType.equals(Long.class) || paramType.equals(Boolean.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer,
                                  NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
        RequestParam requestParam = parameter.getParameterAnnotation(RequestParam.class);
        // 获取参数名（优先取@RequestParam的value，否则用方法参数名）
        String paramName = StringUtils.hasText(requestParam.value()) 
            ? requestParam.value() 
            : parameter.getParameterName();
        String paramValue = webRequest.getParameter(paramName);

        if (paramValue == null) {
            return null;
        }

        Class<?> paramType = parameter.getParameterType();
        try {
            // 尝试转换参数类型
            if (paramType.equals(Long.class)) {
                return Long.parseLong(paramValue);
            } else if (paramType.equals(Boolean.class)) {
                return Boolean.parseBoolean(paramValue);
            }
        } catch (NumberFormatException e) {
            // 转换失败时返回null
            return null;
        }
        return null;
    }
}

2. 注册解析器 #

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private TolerantRequestParamResolver tolerantRequestParamResolver;

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        // 将自定义解析器放在最前面，确保优先级高于默认解析器
        resolvers.add(0, tolerantRequestParamResolver);
    }
}

方案说明 #

• 该解析器仅处理非必填的Long/Boolean类型查询参数，不会影响其他参数的正常校验逻辑；
• 转换失败时直接返回null，控制器方法可根据null值返回默认数据；
• 无需修改生成的控制器代码，适配大量路径和参数的场景。

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