【工作篇】再次熟悉 SpringMVC 参数绑定

前言

主要现在项目中使用的参数绑定五花八门的，搞得很头大，例如有些用字符串接收日期，用字符串接受数组等等，完全没有利用好 SpringMVC 的优势，这里自己也总结一下，免得到时又要百度谷歌查找。

以下实践的 Spring 版本是：5.2.7.RELEASE

一、SpringMVC 中不同类型的数据绑定

1.1、基础数据类型

• 默认参数名

  // http://localhost:8080/baseType3?a=123
  @GetMapping("/baseType")
  @ResponseBody
  public String baseType(int a) {
      return "baseType " + a;
  }

• 使用@RequestParam 自定义请求参数名称

  //  http://localhost:8080/baseType3?b=123
  @GetMapping("/baseType3")
  @ResponseBody
  public String baseType3(@RequestParam(value = "b", required = true) Integer a) {
      return "baseType3 " + a;
  }

• 多个参数

  //  http://localhost:8080/baseType4?age=10&name=Java
  @GetMapping("/baseType4")
  public String baseType3(@RequestParam Integer age, String name) {
      return "baseType4  age:" + age + "  name="+name;
  }

1.2、 对象类型

超过三个参数及以上，则推荐使用对象来接收传递的参数

• 定义简单对象接收参数

  @Data //这里使用了 lombok 插件
  public class User {
      Integer id;
      String name;
  }

  // http://localhost:8080/objectType?id=1&name=Java
  @GetMapping("/objectType")
  public String objectType(User user) {
      return "objectType " + user;
  }

• 内嵌对象接收参数

  @Data
  public class Order {
      Integer id;
      User user;
  }

  // http://localhost:8080/objectType2?id=1&user.name=Java&user.id=2
  @GetMapping("/objectType2")
  public String objectType2(Order order) {
      return "objectType2 " + order;
  }

• 使用 DataBinder 解决不同对象，参数名相同覆盖问题

  • 定义对象

  @Data
  public class Friend {
      Integer id;
      String name;  //与User 对象name 名称冲突
  }
  
  @Data
  public class User {
      Integer id;
      String name;
  }

• InitBinder 配置

  在 Controller 中定义，只对当前 Controller 有效，也可以在 @ControllerAdvice 类中全局定义

/**
     * 初始化绑定参数user 标识前缀
     *
     * @param binder
     */
@InitBinder("user")
public void initBinderUser(WebDataBinder binder) {
    binder.setFieldDefaultPrefix("user.");
}

/**
     * 初始化绑定参数friend 标识前缀
     *
     * @param binder
     */
@InitBinder("friend")
public void initBinderFriend(WebDataBinder binder) {
    binder.setFieldDefaultPrefix("friend.");
}

• 编写请求

//http://localhost:8080/objectType3?name=Java  name会同时填充到User 和Friend对象上
//http://localhost:8080/objectType3?user.name=Java&friend.name=Python 分别填充数据到各自的对象中去
@GetMapping("/objectType3")
public String objectType3(User user, Friend friend) {
    return "objectType3  user" + user + "  friend " + friend;
}

1.3、 日期类型

日期类型的参数传递方式比较多，正式项目中建议统一规定日期类型的参数绑定的格式

1.3.1、使用时间戳传递(不是参数绑定方式)

// http://localhost:8080/dateType6?date=1628752881
@GetMapping("/dateType6")
public String dateType5(Long date) {
	return "dateType6  date" + new Date(date);
}

1.3.2、使用字符串接收(不是参数绑定方式)

// http://localhost:8080/dateType7?date=2021-08-12
@GetMapping("/dateType7")
public String dateType7(String date) throws ParseException {
    return "dateType7  date" + new SimpleDateFormat("yyyy-MM-dd").parse(date);
}

1.3.3、使用 SpringMVC 默认提供的 @DateTimeFormat （对于 json 参数无效）

// http://localhost:8080/dateType2?date1=2020-01-01
@GetMapping("/dateType2")
public String dateType2(@DateTimeFormat(pattern = "yyyy-MM-dd") Date date1) {
    return "dateType2  date " + date1;
}

1.3.4、使用 @InitBinder 注册转换器

• 添加转换器

    /**
     * 注册日期转换 date
     *
     * @param binder
     */
    @InitBinder
    public void initBinderDate(WebDataBinder binder) {
        binder.addCustomFormatter(new Formatter<Date>() {
            @Override
            public Date parse(String text, Locale locale) throws ParseException {
                System.out.println("InitBinder addCustomFormatter String to Date  ");
                return new SimpleDateFormat("yyyy-MM-dd").parse(text);
            }

            @Override
            public String print(Date date, Locale locale) {
                System.out.println("InitBinder addCustomFormatter  Date to String  ");
                return new SimpleDateFormat("yyyy-MM-dd").format(date);
            }
        });
    }

• 请求

// http://localhost:8080/dateType?date=2020-01-01
@GetMapping("/dateType")
public String dateType(Date date) {
    return "dateType  date" + date;
}

1.3.5、全局配置 Formatter

对于 json 参数（@RequestBody 修饰的参数）无效

@Configuration
public class WebConfig implements WebMvcConfigurer {

    /**
     * 注册 Converters 和 Formatters
     *
     * @param registry
     */
        @Override
    public void addFormatters(FormatterRegistry registry) {
        //参数传出格式化
        registry.addFormatter(new DateFormatter("yyyy-MM-dd"));
    }
}

1.3.6、@JsonFormat 单独配置字段格式化

只对 @RequestBody 修饰的参数有效

• 定义实体

@Data
public class UserDate {

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM")
    private Date birthday;
}

• 请求

/**
  * http://localhost:8080/dateType4
  * {
  *     "birthday": "2020-08"
  * }
*/
@PostMapping("/dateType4")
@ResponseBody
public UserDate dateType4(@RequestBody UserDate userDate) {
    return userDate;
}

1.3.7、全局配置 JSON 参数日期格式化

注意： 全局配置后，依然可以使用 @JsonFormat 注解，用来接收特殊的日期参数格式。

• 配置

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder()
                //指定时区
                .timeZone(TimeZone.getTimeZone("GMT+8:00"))
                //日期格式化
                .dateFormat(new SimpleDateFormat("yyyy-MM-dd"));
        converters.add(0, new MappingJackson2HttpMessageConverter(builder.build()));
    }
}

• 实体

@Data
public class UserDate {

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM")
    private Date birthday;

    private Date date;
}

• 请求

/**
  * http://localhost:8080/dateType4
  * {
  *     "birthday": "2020-08",
  *     "date": "2021-08-13"
  * }
*/
@PostMapping("/dateType4")
@ResponseBody
public UserDate dateType4(@RequestBody UserDate userDate) {
    return userDate;
}

1.4、 复杂类型

复杂类型包括数组和集合类型，像 List、Set、Map。以下以 List 为例

• 使用逗号分割形式

    /**
     * 请求形式
     * http://localhost:8080/complexType2_1?list=1,2,3
     */
    @GetMapping("/complexType2_1")
    public String complexType2_1(@RequestParam("list") List<String> list) {
        return "complexType2_1 " + list;
    }

• 相同参数明传递多次

    /**
     * 请求形式
     * http://localhost:8080/complexType2?list=1&list=2
     */
    @GetMapping("/complexType2")
    public String complexType2(@RequestParam("list") List<String> list) {
        return "complexType2 " + list;
    }

• 使用 JSON 字符串传递

/**
     * 请求形式
     * http://localhost:8080/complexType4
     * <p>
     * 请求体
     * [1,2,3]
     */
@PostMapping("/complexType4")
public String complexType4(@RequestBody List<String> list) {
    return "complexType4 " + list;
}

1.5、 特殊类型

• xml

@Data
@XmlRootElement(name ="user")
public class User {
    Integer id;
    String name;
}

/**
     * http://localhost:8080/xmlType

 <?xml version="1.0" encoding="utf-8"?>
 <user>
 <id>1</id>
 <name>Java</name>
 </user>
     */
@PostMapping(path = "/xmlType", consumes = "application/xml;charset=UTF-8")
public String xmlType(@RequestBody User user) {
    return "xmlType " + user;
}

• json

/**
     * 请求
     * http://localhost:8080/jsonType
     * 请求体
{
    "id": 1,
    "name": "Java"
}
     *
     * @RequestBody 不支持GET请求
     */
@PostMapping(value = "/jsonType", consumes = "application/json")
public String jsonType(@RequestBody User user) {
    return "jsonType " + user;
}

二、了解底层实现

2.1、SpringMVC 方法参数绑定

2.1.1、认识 HandlerMethodArgumentResolver 接口

public interface HandlerMethodArgumentResolver {

	//该解析器是否支持parameter参数的解析
	boolean supportsParameter(MethodParameter parameter);

	//从给定请求(webRequest)解析为参数值并填充到指定对象中
	@Nullable
	Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
			NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception;
}

2.1.2、内置的 HandlerMethodArgumentResolver

//在初始化RequestMappingHandlerAdapter 时会默认加载参数解析器
// org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#afterPropertiesSet
private List<HandlerMethodArgumentResolver> getDefaultArgumentResolvers() {
   List<HandlerMethodArgumentResolver> resolvers = new ArrayList<>();

   // Annotation-based argument resolution

   //处理 @RequestParam 注解标识的参数
   resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), false));
   //处理@RequestParam 注解标识的Map参数且不能指定参数名称
   resolvers.add(new RequestParamMapMethodArgumentResolver());
   //处理@PathVariable 注解标识路径参数 如/pathVariable/{a}
   resolvers.add(new PathVariableMethodArgumentResolver());
   //处理@PathVariable 注解标识的Map参数且不能指定参数名称
   resolvers.add(new PathVariableMapMethodArgumentResolver());

   //处理@MatrixVariable注解标识的参数
   resolvers.add(new MatrixVariableMethodArgumentResolver());
   resolvers.add(new MatrixVariableMapMethodArgumentResolver());


   resolvers.add(new ServletModelAttributeMethodProcessor(false));

   //处理@RequestBody 注解
   resolvers.add(new RequestResponseBodyMethodProcessor(getMessageConverters(), this.requestResponseBodyAdvice));
   resolvers.add(new RequestPartMethodArgumentResolver(getMessageConverters(), this.requestResponseBodyAdvice));
   //处理请求头
   resolvers.add(new RequestHeaderMethodArgumentResolver(getBeanFactory()));
   resolvers.add(new RequestHeaderMapMethodArgumentResolver());
   //处理Cookie 值
   resolvers.add(new ServletCookieValueMethodArgumentResolver(getBeanFactory()));

   resolvers.add(new ExpressionValueMethodArgumentResolver(getBeanFactory()));
   resolvers.add(new SessionAttributeMethodArgumentResolver());
   resolvers.add(new RequestAttributeMethodArgumentResolver());

   // Type-based argument resolution
   resolvers.add(new ServletRequestMethodArgumentResolver());
   resolvers.add(new ServletResponseMethodArgumentResolver());
   resolvers.add(new HttpEntityMethodProcessor(getMessageConverters(), this.requestResponseBodyAdvice));
   resolvers.add(new RedirectAttributesMethodArgumentResolver());
   resolvers.add(new ModelMethodProcessor());
   resolvers.add(new MapMethodProcessor());
   resolvers.add(new ErrorsMethodArgumentResolver());
   resolvers.add(new SessionStatusMethodArgumentResolver());
   resolvers.add(new UriComponentsBuilderMethodArgumentResolver());

   // 添加自定义的解析器
   if (getCustomArgumentResolvers() != null) {
      resolvers.addAll(getCustomArgumentResolvers());
   }

   // Catch-all
   resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), true));
   resolvers.add(new ServletModelAttributeMethodProcessor(true));

   return resolvers;
}

2.1.2、执行过程

• 初始化解析器到 RequestMappingHandlerAdapter 中

// org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport#requestMappingHandlerAdapter
@Bean
public RequestMappingHandlerAdapter requestMappingHandlerAdapter(
    @Qualifier("mvcContentNegotiationManager") ContentNegotiationManager contentNegotiationManager,
    @Qualifier("mvcConversionService") FormattingConversionService conversionService,
    @Qualifier("mvcValidator") Validator validator) {

    RequestMappingHandlerAdapter adapter = createRequestMappingHandlerAdapter();
    adapter.setContentNegotiationManager(contentNegotiationManager);
    adapter.setMessageConverters(getMessageConverters());
    adapter.setWebBindingInitializer(getConfigurableWebBindingInitializer(conversionService, validator));


    //可以实现org.springframework.web.servlet.config.annotation.WebMvcConfigurer接口
    //设置自定义的参数解析器
    adapter.setCustomArgumentResolvers(getArgumentResolvers());

    adapter.setCustomReturnValueHandlers(getReturnValueHandlers());
    if (jackson2Present) {
        adapter.setRequestBodyAdvice(Collections.singletonList(new JsonViewRequestBodyAdvice()));
        adapter.setResponseBodyAdvice(Collections.singletonList(new JsonViewResponseBodyAdvice()));
    }
    AsyncSupportConfigurer configurer = new AsyncSupportConfigurer();
    configureAsyncSupport(configurer);
    if (configurer.getTaskExecutor() != null) {
        adapter.setTaskExecutor(configurer.getTaskExecutor());
    }
    if (configurer.getTimeout() != null) {
        adapter.setAsyncRequestTimeout(configurer.getTimeout());
    }
    adapter.setCallableInterceptors(configurer.getCallableInterceptors());
    adapter.setDeferredResultInterceptors(configurer.getDeferredResultInterceptors());
    return adapter;
}

// org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#afterPropertiesSet
@Override
public void afterPropertiesSet() {
    // Do this first, it may add ResponseBody advice beans
    initControllerAdviceCache();

    if (this.argumentResolvers == null) {
        //获取默认解析器 和 自定义解析器
        List<HandlerMethodArgumentResolver> resolvers = getDefaultArgumentResolvers();
        this.argumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.initBinderArgumentResolvers == null) {
        List<HandlerMethodArgumentResolver> resolvers = getDefaultInitBinderArgumentResolvers();
        this.initBinderArgumentResolvers = new HandlerMethodArgumentResolverComposite().addResolvers(resolvers);
    }
    if (this.returnValueHandlers == null) {
        List<HandlerMethodReturnValueHandler> handlers = getDefaultReturnValueHandlers();
        this.returnValueHandlers = new HandlerMethodReturnValueHandlerComposite().addHandlers(handlers);
    }
}

• 寻找合适的解析器

//1. org.springframework.web.servlet.DispatcherServlet#doDispatch
//2. org.springframework.web.servlet.HandlerAdapter#handle
//3. org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod#invokeAndHandle
//4. org.springframework.web.method.support.InvocableHandlerMethod#getMethodArgumentValues
protected Object[] getMethodArgumentValues(NativeWebRequest request, @Nullable ModelAndViewContainer mavContainer,
                                           Object... providedArgs) throws Exception {
	//获取方法参数
    MethodParameter[] parameters = getMethodParameters();
    if (ObjectUtils.isEmpty(parameters)) {
        return EMPTY_ARGS;
    }

    Object[] args = new Object[parameters.length];
    for (int i = 0; i < parameters.length; i++) {
        MethodParameter parameter = parameters[i];
        parameter.initParameterNameDiscovery(this.parameterNameDiscoverer);
        args[i] = findProvidedArgument(parameter, providedArgs);
        if (args[i] != null) {
            continue;
        }
        //判断是否支持解析该参数
        if (!this.resolvers.supportsParameter(parameter)) {
            throw new IllegalStateException(formatArgumentError(parameter, "No suitable resolver"));
        }
        try {
            //HandlerMethodArgumentResolverComposite 组合模式
            //使用具体HandlerMethodArgumentResolver 解析参数
            args[i] = this.resolvers.resolveArgument(parameter, mavContainer, request, this.dataBinderFactory);
        }
        catch (Exception ex) {
            // Leave stack trace for later, exception may actually be resolved and handled...
            if (logger.isDebugEnabled()) {
                String exMsg = ex.getMessage();
                if (exMsg != null && !exMsg.contains(parameter.getExecutable().toGenericString())) {
                    logger.debug(formatArgumentError(parameter, exMsg));
                }
            }
            throw ex;
        }
    }
    return args;
}

• 解析参数

// @RequestParam 注解的参数
// 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 namedValueInfo = getNamedValueInfo(parameter);
    //如果参数是使用Optional包裹，则获取内嵌的参数对象
    MethodParameter nestedParameter = parameter.nestedIfOptional();
	// 处理参数名称
    Object resolvedName = resolveStringValue(namedValueInfo.name);
    if (resolvedName == null) {
        throw new IllegalArgumentException(
            "Specified name must not resolve to null: [" + namedValueInfo.name + "]");
    }
	//解析请求参数值
    Object arg = resolveName(resolvedName.toString(), nestedParameter, webRequest);
    if (arg == null) {
        if (namedValueInfo.defaultValue != null) {
            arg = resolveStringValue(namedValueInfo.defaultValue);
        }
        else if (namedValueInfo.required && !nestedParameter.isOptional()) {
            handleMissingValue(namedValueInfo.name, nestedParameter, webRequest);
        }
        arg = handleNullValue(namedValueInfo.name, arg, nestedParameter.getNestedParameterType());
    }
    else if ("".equals(arg) && namedValueInfo.defaultValue != null) {
        arg = resolveStringValue(namedValueInfo.defaultValue);
    }

    if (binderFactory != null) {
        //创建WebDataBinder
        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;
}

2.2、WebDataBinder 原理

2.2.1、初始化 WebDataBinder 方式

• @Controller 在每个控制器中定义(或者提取到 BaseController )

public class BaseController {
    // @InitBinder 注解的方法，返回值需要声明为void
    @InitBinder
    public void initBinderUser(WebDataBinder binder) {
        System.out.println("BaseController  WebDataBinder 执行" );
    }
}

@RestController
public class DemoDataBindingController extends BaseController {
}

• @ControllerAdvice 类 中定义，每个请求都会执行，适合全局配置

@ControllerAdvice
public class ControllerAdviceConfig {

    @InitBinder
    public void initBinderUser(WebDataBinder binder) {
        System.out.println("ControllerAdvice  WebDataBinder 执行" );
    }
}

• 自定义 WebBindingInitializer

//默认实现 ConfigurableWebBindingInitializer
public interface WebBindingInitializer {
	// org.springframework.web.bind.support.DefaultDataBinderFactory#createBinder 创建时调用
    // 比@InitBinder 注解的方法先执行
	void initBinder(WebDataBinder binder);

	@Deprecated
	default void initBinder(WebDataBinder binder, WebRequest request) {
		initBinder(binder);
	}
}

@Configuration
public class CustomConfigurableWebBindingInitializer extends ConfigurableWebBindingInitializer {

    @Override
    public void initBinder(WebDataBinder binder) {
        super.initBinder(binder);

        System.out.println("CustomConfigurableWebBindingInitializer  initBinder");
    }
}

//发起请求时，控制台输出
//CustomConfigurableWebBindingInitializer  initBinder
//ControllerAdvice  WebDataBinder 执行

2.2.2、WebDataBinder 有什么作用？

• 用于绑定请求参数(Form 表单参数，query 参数)到模型对象中
• 用于转换 字符串参数(请求参数、路径参数、header 属性、Cookie) 为 Controller 方法形参的对应类型
• 格式化对象为指定字符串格式

2.2.3、WebDataBinder 执行过程

• 定义初始化 WebDataBinder 方式(#2.2.1)
• 创建 DataBinderFactory

//1. org.springframework.web.servlet.DispatcherServlet#doDispatch
//2. org.springframework.web.servlet.HandlerAdapter#handle
//3. org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#invokeHandlerMethod
private WebDataBinderFactory getDataBinderFactory(HandlerMethod handlerMethod) throws Exception {
    Class<?> handlerType = handlerMethod.getBeanType();
    Set<Method> methods = this.initBinderCache.get(handlerType);
    if (methods == null) {
        // 查找@Controller中 @InitBinder 注解的方法
        methods = MethodIntrospector.selectMethods(handlerType, INIT_BINDER_METHODS);
        this.initBinderCache.put(handlerType, methods);
    }
    List<InvocableHandlerMethod> initBinderMethods = new ArrayList<InvocableHandlerMethod>();
    // Global methods first
    // initBinderAdviceCache 在 RequestMappingHandlerAdapter#afterPropertiesSet 里初始化
    // 1. 先加载 在@ControllerAdvice类定义的 @InitBinder 注解的方法
    for (Entry<ControllerAdviceBean, Set<Method>> entry : this.initBinderAdviceCache.entrySet()) {
        if (entry.getKey().isApplicableToBeanType(handlerType)) {
            Object bean = entry.getKey().resolveBean();
            for (Method method : entry.getValue()) {
                initBinderMethods.add(createInitBinderMethod(bean, method));
            }
        }
    }
    //2. 再加载@Controller中 @InitBinder 注解的方法
    for (Method method : methods) {
        Object bean = handlerMethod.getBean();
        initBinderMethods.add(createInitBinderMethod(bean, method));
    }
    return createDataBinderFactory(initBinderMethods);
}

• 执行 initBinder 方法

// org.springframework.web.method.annotation.AbstractNamedValueMethodArgumentResolver#resolveArgument
// org.springframework.web.bind.support.DefaultDataBinderFactory#createBinder
@Override
@SuppressWarnings("deprecation")
public final WebDataBinder createBinder(
    NativeWebRequest webRequest, @Nullable Object target, String objectName) throws Exception {

    WebDataBinder dataBinder = createBinderInstance(target, objectName, webRequest);
    if (this.initializer != null) {
        //执行 WebBindingInitializer 定义的initBinder方法
        this.initializer.initBinder(dataBinder, webRequest);
    }
    //执行 @InitBinder 注解的方法
    initBinder(dataBinder, webRequest);
    return dataBinder;
}

到此，对 SpringMVC 的参数绑定讲解完成了。

项目地址

• https://github.com/h-dj/Spring-Learning/tree/master/mvc-argument-resolver

参考

• https://juejin.im/post/5ba6384cf265da0aa06ef3b7
• https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#format-configuring-formatting-globaldatetimeformat
• https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#mvc-ann-initbinder