源码剖析ApiImplicitParam对RequestParam的required属性的侵入性

问题起源

应用 SpringCloud 构建我的项目时，应用 Swagger 生成相应的接口文档是举荐的选项，Swagger 可能提供页面拜访，间接在网页上调试后端系统的接口，十分不便。最近却遇到了一个有点困惑的问题，演示接口示例如下（原有性能接口带有业务实现逻辑，这里简化了接口）：

/**
 * @description: 演示类
 * @author: Huang Ying
 **/
@Api(tags = "演示类")
@RestController
@Slf4j
public class DemoController {@ApiOperation(value = "测试接口")
    @ApiImplicitParams({@ApiImplicitParam(name = "uid", value = "用户 ID", paramType = "query", dataType = "Long")
    })
    @RequestMapping(value = "/api/json/demo", method = RequestMethod.GET)
    public String auth(@RequestParam(value = "uid") Long uid) {System.out.println(uid);
        return "the uid:" + uid;
    }
}

问题出在接口参数 uid 的必填性上，@RequestParam注解里 require 默认为 true，要求必填，但 @ApiImplicitParam 注解里 require 默认为 false，要求非必填，该业务接口在进行性能联调时，uid 竟然能失去一个 null 值，依照个别认知习惯 @ApiImplicitParam 注解的次要作用是生成接口文档，不应该对 @RequestParam 的属性有侵入性才对，目前反馈的 bug，让我狐疑 @ApiImplicitParam 是不是会侵入 @RequestParam 的 require 属性？

框架选型、版本及次要性能

我的项目搭建

SpringBoot 版本：2.1.6.RELEASE
SpringCloud 版本：Greenwich.SR3

业务模块

SpringCloud 业务模块应用的 swagger:

swagger bootstrap ui 1.9.6 加强 swagger ui 款式
spring4all-swagger 1.9.0.RELEASE 配置化 swagger 参数，免去代码开发

业务网关

SpringCloud 业务网关应用的 swagger:

knife4j 2.0.1 加强 swagger ui 款式（网关用 gateway 搭建，swagger 应用 knife4j-spring-boot-starter 依赖，能够聚合业务模块的 swagger 文档）

此次的范畴只针对 SpringCloud 业务模块，临时不波及业务网关的 Swagger 文档。

测试工具

测试工具目前有两个：
swagger doc：应用浏览器进行拜访，如下图：

postman：手动配置接口参数，示例：

案例实战

接口测试 1

接口示例如开篇所示，咱们先应用如下接口，全副应用默认值，即 @ApiImplicitParam 的 required 为 false，@RequestParam 的 required 为 true：

@ApiOperation(value = "测试接口")
@ApiImplicitParams({@ApiImplicitParam(name = "uid", value = "用户 ID", paramType = "query", dataType = "Long")
})
@RequestMapping(value = "/api/json/demo", method = RequestMethod.GET)
public String auth(@RequestParam(value = "uid") Long uid) {System.out.println(uid);
    return "the uid:" + uid;
}

看 swagger 的后果：

看 postman 的后果：

接口测试 2

咱们批改 @ApiImplicitParam 的 required 值为 true，@RequestParam 不变，重启模块
@ApiImplicitParam(name = "uid", value = "用户 ID", paramType = "query", required = true, dataType = "Long")

看 swagger 的后果：

通过调试浏览器能够发现，为空校验是 js 实现的，js 判断为空后，并未发动申请到后端，这样咱们能够认为 swagger 内 @ApiImplicitParam 的 required 参数失效了。

接口测试 3

在后面咱们应用 postman 测试接口时，发现参数项是空的，咱们加上参数，但不写值测试后，后果让人惊讶：

并且无论 @ApiImplicitParam 的 required 值如何批改，后果都是一样的，必定有一个中央是搞错了，导致咱们误判。

起初认真查阅材料，发现是咱们对 @RequestParam 的 required 参数了解错了，这个 required 为 true 的含意是：接口参数名肯定要存在，但参数前面有没有值它管不着。拿刚刚的例子来说：

这两个申请是通过的：localhost:8080/api/json//demo?uid
localhost:8080/api/json//demo?uid=

只有这种申请是不通过的：localhost:8080/api/json//demo?

小论断

通过上述三个接口的测试场景，咱们至多能够明确 3 点：

1. @ApiImplicitParam 的 required 参数不会对 @RequestParam 的 required 值造成侵入，它们俩不相干。
2. @ApiImplicitParam 的 required 参数会影响 swagger doc 的 js 逻辑判断，为空校验是在 js 层面上实现的。
3. @RequestParam 的 required 参数默认状况下只会校验是否有该参数名，不校验它是否有值。

源码分析

swagger 局部

上一节当中提及 swagger 读取 @ApiImplicitParam 注解的 required 参数，最终会体现在 js 上，通过浏览器 F12 的追踪，定位到 swaggerbootstrapui.js 文件上，这里摘抄局部源码：

# 点击发送按钮时，逐行读取参数信息，并提取 required 参数
 paramBody.find("tr").each(function () {var paramtr=$(this);
    var cked=paramtr.find("td:first").find(":checked").prop("checked");
    var _urlAppendflag=true;
    //that.log(cked)
    if (cked){// 如果选中，注意此行的 required:paramtr.data("required")信息提取
        var trdata={name:paramtr.find("td:eq(2)").find("input").val(),in:paramtr.data("in"),required:paramtr.data("required"),type:paramtr.data("type"),emflag:paramtr.data("emflag"),schemavalue:paramtr.data("schemavalue")};
        //that.log("trdata....")
        //that.log(trdata);
        // 获取 key
        //var key=paramtr.find("td:eq(1)").find("input").val();
        var key=trdata["name"];
        // 获取 value
        var value="";
        var reqflag=false;
        // 前面代码省略
    }
})
 

js 上判断该属性 required 是否为 true 的解决，js 源码如下：

// 判断是否 required
if (trdata.hasOwnProperty("required")){var required=trdata["required"];
    if (required){if(!reqflag){
            // 必须, 验证 value 是否为空
            if(value==null||value==""){
                validateflag=true;
                var des=trdata["name"]
                //validateobj={message:des+"不能为空"};
                validateobj={message:des+i18n.message.debug.fieldNotEmpty};
                return false;
            }
        }
    }

}

SpringCloud 业务模块局部

swagger 前端 js 验证通过能够向后盾发送申请，或者应用 postman 向后盾零碎发送申请时，开始进入后盾的一系列过滤器、Servlet 解决，货色还不少：

// 理论的业务办法局部
auth:28, DemoController (com.hy.demo.controller)
invoke0:-1, NativeMethodAccessorImpl (sun.reflect)
invoke:62, NativeMethodAccessorImpl (sun.reflect)
invoke:43, DelegatingMethodAccessorImpl (sun.reflect)
invoke:498, Method (java.lang.reflect)

// 申请参数的提取、管制局部
doInvoke:190, InvocableHandlerMethod (org.springframework.web.method.support)
invokeForRequest:138, InvocableHandlerMethod (org.springframework.web.method.support)
invokeAndHandle:104, ServletInvocableHandlerMethod (org.springframework.web.servlet.mvc.method.annotation)
invokeHandlerMethod:892, RequestMappingHandlerAdapter (org.springframework.web.servlet.mvc.method.annotation)
handleInternal:797, RequestMappingHandlerAdapter (org.springframework.web.servlet.mvc.method.annotation)
handle:87, AbstractHandlerMethodAdapter (org.springframework.web.servlet.mvc.method)

// 上面是各种根底 Web 服务组件的过滤器等，临时不关怀
doDispatch:1039, DispatcherServlet (org.springframework.web.servlet)
doService:942, DispatcherServlet (org.springframework.web.servlet)
processRequest:1005, FrameworkServlet (org.springframework.web.servlet)
doGet:897, FrameworkServlet (org.springframework.web.servlet)
service:634, HttpServlet (javax.servlet.http)
service:882, FrameworkServlet (org.springframework.web.servlet)
service:741, HttpServlet (javax.servlet.http)
internalDoFilter:231, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilter:53, WsFilter (org.apache.tomcat.websocket.server)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilter:84, SecurityBasicAuthFilter (com.github.xiaoymin.swaggerbootstrapui.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilter:53, ProductionSecurityFilter (com.github.xiaoymin.swaggerbootstrapui.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilter:124, WebStatFilter (com.alibaba.druid.support.http)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilterInternal:88, HttpTraceFilter (org.springframework.boot.actuate.web.trace.servlet)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilterInternal:99, RequestContextFilter (org.springframework.web.filter)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilterInternal:92, FormContentFilter (org.springframework.web.filter)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilterInternal:93, HiddenHttpMethodFilter (org.springframework.web.filter)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
filterAndRecordMetrics:114, WebMvcMetricsFilter (org.springframework.boot.actuate.metrics.web.servlet)
doFilterInternal:104, WebMvcMetricsFilter (org.springframework.boot.actuate.metrics.web.servlet)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilterInternal:200, CharacterEncodingFilter (org.springframework.web.filter)
doFilter:109, OncePerRequestFilter (org.springframework.web.filter)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
invoke:202, StandardWrapperValve (org.apache.catalina.core)
invoke:96, StandardContextValve (org.apache.catalina.core)
invoke:490, AuthenticatorBase (org.apache.catalina.authenticator)
invoke:139, StandardHostValve (org.apache.catalina.core)
invoke:92, ErrorReportValve (org.apache.catalina.valves)
invoke:74, StandardEngineValve (org.apache.catalina.core)
service:343, CoyoteAdapter (org.apache.catalina.connector)
service:408, Http11Processor (org.apache.coyote.http11)
process:66, AbstractProcessorLight (org.apache.coyote)
process:853, AbstractProtocol$ConnectionHandler (org.apache.coyote)
doRun:1587, NioEndpoint$SocketProcessor (org.apache.tomcat.util.net)
run:49, SocketProcessorBase (org.apache.tomcat.util.net)
runWorker:1149, ThreadPoolExecutor (java.util.concurrent)
run:624, ThreadPoolExecutor$Worker (java.util.concurrent)
run:61, TaskThread$WrappingRunnable (org.apache.tomcat.util.threads)
run:748, Thread (java.lang)

汇集重点在申请参数的读取校验方面，首先看 org.springframework.web.method.annotation.AbstractNamedValueMethodArgumentResolver 类的 resolveArgument 办法：

@Override
@Nullable
public final Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception {

    // 注意此办法调用
    NamedValueInfo namedValueInfo = getNamedValueInfo(parameter);
    MethodParameter nestedParameter = parameter.nestedIfOptional();

    Object resolvedName = resolveStringValue(namedValueInfo.name);
    if (resolvedName == null) {
        throw new IllegalArgumentException("Specified name must not resolve to null: [" + namedValueInfo.name + "]");
    }
    // 前面临时省略
}

getNamedValueInfo办法的实现如下：

/**
 * Obtain the named value for the given method parameter.
 */
private NamedValueInfo getNamedValueInfo(MethodParameter parameter) {NamedValueInfo namedValueInfo = this.namedValueInfoCache.get(parameter);
    if (namedValueInfo == null) {namedValueInfo = createNamedValueInfo(parameter);
        namedValueInfo = updateNamedValueInfo(parameter, namedValueInfo);
        this.namedValueInfoCache.put(parameter, namedValueInfo);
    }
    return namedValueInfo;
}

进入 createNamedValueInfo(parameter) 办法时，这部分代码如下：

@Override
protected NamedValueInfo createNamedValueInfo(MethodParameter parameter) {RequestParam ann = parameter.getParameterAnnotation(RequestParam.class);
    return (ann != null ? new RequestParamNamedValueInfo(ann) : new RequestParamNamedValueInfo());
}

/**
 * NamedValueInfo 的定义
 * Represents the information about a named value, including name, whether it's required and a default value.
 */
protected static class NamedValueInfo {

    private final String name;

    private final boolean required;

    @Nullable
    private final String defaultValue;

    public NamedValueInfo(String name, boolean required, @Nullable String defaultValue) {
        this.name = name;
        this.required = required;
        this.defaultValue = defaultValue;
    }
}

这段代码很要害，这里只读取 @RequestParam 注解，不会读 @ApiImplicitParam 注解，所以 @ApiImplicitParam 注解不会影响 @RequestParam 的属性，并且无论是从 swagger doc 过去的申请，还是 postman 过去的申请，都执行这一段代码，最终读取注解的后果用 CurrenctHashMap 存储，key 的格局是method 'xxx' parameter y，xxx 为办法名，y 为参数的顺序号，如method 'auth' parameter 0，基本上能够保障唯一性。

阶段性总结

源码浏览到这里，基本上能够验证后面提及的小论断的前 2 条，援用一下：

1. @ApiImplicitParam 的 required 参数不会对 @RequestParam 的 required 值造成侵入，它们俩不相干。
2. @ApiImplicitParam 的 required 参数会影响 swagger doc 的 js 逻辑判断，为空校验是在 js 层面上实现的。
3. @RequestParam 的 required 参数默认状况下只会校验是否有该参数名，不校验它是否有值。

后面 2 个问题曾经从源码中找到解释，来看第 3 个问题：如果参数设置 required=true，但只是要求参数名存在，如果此字段是 Long 类型或 Integer 类型，写成 uid= 或 ’uid’，也能通过校验，最终进入办法后，还是得手动写代码进行为空校验，这显然不是咱们想要的后果？该如何解决呢？

申请参数 data bind 的问题

接上一节，如果这样通用的参数，得挨个判断是否为空，这样的做法就有点好受了，有没有更好的解决办法呢？预期的实现成果是字段加上 require=true 后，Long 类型或其余数值类型能够把 ””，null 过滤掉，要不然 require 还有什么意义呢？

解决办法有两个思路：

1. POST 申请办法中将多个参数封装到一个 POJO 类里，用 @RequestBody 申明，POJO 类中能够应用 @Validator 框架的 @NotNull 等注解，并在参数前申明 @Valid。
2. 自定义参数绑定规定扩大。

计划 2 更通用一些，实用 GET、POST 申请，并且原有的单个参数申明无需封装到 POJO 类里。

官网自身提供自定义参数绑定的扩大，见https://docs.spring.io/spring/docs/5.1.8.RELEASE/spring-framework-reference/web.html#mvc-ann-initbinder

官网的例子是在指定的 Controller 类中应用 @InitBinder 注解，影响范畴仅限该 Controller 类，示例如下：

@InitBinder
public void initBinder(WebDataBinder binder) {
    /*
     * 注册对于 String 类型参数对象的属性进行 trim 操作的编辑器,
     * 结构参数代表空串是否转为 null，false，则将 null 转为空串。*/
    binder.registerCustomEditor(String.class, new StringTrimmerEditor(false));
    // 这里我还增加了其余类型的属性编辑器，true 示意容许应用 ""，并且将"" 解决为空，false 示意不容许应用 ""
    binder.registerCustomEditor(Short.class, new CustomNumberEditor(Short.class, false));
    binder.registerCustomEditor(Integer.class, new CustomNumberEditor(Integer.class, false));
    binder.registerCustomEditor(Long.class, new CustomNumberEditor(Long.class, false));
    binder.registerCustomEditor(Float.class, new CustomNumberEditor(Float.class, false));
    binder.registerCustomEditor(Double.class, new CustomNumberEditor(Double.class, false));
    binder.registerCustomEditor(BigDecimal.class, new CustomNumberEditor(BigDecimal.class, false));
    binder.registerCustomEditor(BigInteger.class, new CustomNumberEditor(BigInteger.class, false));
}

因为此次面临的问题是全模块 @RequestParam 的值的问题，须要做一个全局的配置，此时须要新增一个类，并应用 @ControllerAdvice 注解，代码如下：

@ControllerAdvice
public class CustomWebBindingInitializer implements WebBindingInitializer {

    @InitBinder
    @Override
    public void initBinder(WebDataBinder binder) {
        /*
         * 注册对于 String 类型参数对象的属性进行 trim 操作的编辑器,
         * 结构参数代表空串是否转为 null，false，则将 null 转为空串。*/
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(false));
        // 这里我还增加了其余类型的属性编辑器，true 示意容许应用 ""，并且将"" 解决为空，false 示意不容许应用 ""
        binder.registerCustomEditor(Short.class, new CustomNumberEditor(Short.class, false));
        binder.registerCustomEditor(Integer.class, new CustomNumberEditor(Integer.class, false));
        binder.registerCustomEditor(Long.class, new CustomNumberEditor(Long.class, false));
        binder.registerCustomEditor(Float.class, new CustomNumberEditor(Float.class, false));
        binder.registerCustomEditor(Double.class, new CustomNumberEditor(Double.class, false));
        binder.registerCustomEditor(BigDecimal.class, new CustomNumberEditor(BigDecimal.class, false));
        binder.registerCustomEditor(BigInteger.class, new CustomNumberEditor(BigInteger.class, false));
    }

}

留神一下 CustomNumberEditor 实例初始化的传的 false 参数。

重启利用，看一下成果：

扩大 DataBinder 后相干源码浏览

都曾经到这儿了，再加把劲把相干的源码看一下，还是在 org.springframework.web.method.annotation.AbstractNamedValueMethodArgumentResolver 类的 resolveArgument 办法的后半段：

@Override
@Nullable
public final Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
        NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception {
    // 后面省略
    if (binderFactory != null) {WebDataBinder binder = binderFactory.createBinder(webRequest, null, namedValueInfo.name);
        try {
            // 在这里对参数进行转换
            arg = binder.convertIfNecessary(arg, parameter.getParameterType(), parameter);
        }
        catch (ConversionNotSupportedException ex) {throw new MethodArgumentConversionNotSupportedException(arg, ex.getRequiredType(),
                    namedValueInfo.name, parameter, ex.getCause());
        }
        catch (TypeMismatchException ex) {throw new MethodArgumentTypeMismatchException(arg, ex.getRequiredType(),
                    namedValueInfo.name, parameter, ex.getCause());

        }
    }

    handleResolvedValue(arg, namedValueInfo.name, parameter, mavContainer, webRequest);

    return arg;
}

从 binder.convertIfNecessary 办法一路跟上来，两头省略一些调用，最终达到 org.springframework.beans.propertyeditors.CustomNumberEditor 类的 setAsText 办法：

/**
 * Parse the Number from the given text, using the specified NumberFormat.
 */
@Override
public void setAsText(String text) throws IllegalArgumentException {if (this.allowEmpty && !StringUtils.hasText(text)) {
        // Treat empty String as null value.
        setValue(null);
    }
    else if (this.numberFormat != null) {
        // Use given NumberFormat for parsing text.
        setValue(NumberUtils.parseNumber(text, this.numberClass, this.numberFormat));
    }
    else {
        // Use default valueOf methods for parsing text.
        setValue(NumberUtils.parseNumber(text, this.numberClass));
    }
}

认真看 allowEmpty 变量，针对 Long 类型的参数，咱们扩大数据绑定时，该变量设置的是 false，示意不承受空值，试验中咱们传的值是空串，那么这里的条件分支判断就必须对空串转换成数值，执行 Long.valueOf("") 后果报出运行时异样 java.lang.NumberFormatException，告知客户端参数不对，这是冀望的后果。

总结

本篇以理论的研发排错过程为出发点，刚开始本人也认为 @ApiImplicitParam 对 @RequestParam 的 required 属性的有侵入性，感觉惊讶便深刻源码论证本人的想法，经浏览源码后发现事实并不是这样，是刚开始咱们对 required 的了解有误。既然 required 的作用十分无限，那么必定能找到通用的解决方案防止手动写代码对所有参数进行为空判断，这些解决一个问题后，发现新的问题，再持续解决，最终失去的后果，剖析若有不详尽之处，请斧正，谢谢。

专一 Java 高并发、分布式架构，更多技术干货分享与心得，请关注公众号：Java 架构社区
能够扫右边二维码增加好友，邀请你退出 Java 架构社区微信群独特探讨技术