详细分析@InitBinder注解的使用和原理

曾经终败给现在 2023-09-25 16:50 42阅读 0赞

## 前言 ##

由@**InitBinder**注解修饰的方法用于初始化**WebDataBinder**对象，能够实现：从**request**获取到**handler**方法中由@**RequestParam**注解或@**PathVariable**注解修饰的参数后，假如获取到的参数类型与**handler**方法上的参数类型不匹配，此时可以使用初始化好的**WebDataBinder**对获取到的参数进行类型处理。

一个经典的例子就是**handler**方法上的参数类型为**Date**，而从**request**中获取到的参数类型是字符串，**SpringMVC**在默认情况下无法实现字符串转**Date**，此时可以在由@**InitBinder**注解修饰的方法中为**WebDataBinder**对象注册**CustomDateEditor**，从而使得**WebDataBinder**能将从**request**中获取到的字符串再转换为**Date**对象。

通常，如果在@**ControllerAdvice**注解修饰的类中使用@**InitBinder**注解，此时@**InitBinder**注解修饰的方法所做的事情全局生效（前提是@**ControllerAdvice**注解没有设置**basePackages**字段）；如果在@**Controller**注解修饰的类中使用@**InitBinder**注解，此时@**InitBinder**注解修饰的方法所做的事情仅对当前**Controller**生效。本篇文章将结合简单例子，对@**InitBinder**注解的使用，原理进行学习。

**SpringBoot**版本：**2.4.1**

## 正文 ##

### 一. @InitBinder注解使用说明 ###

以前言中提到的字符串转**Date**为例，对@**InitBinder**的使用进行说明。

@RestController
    public class DateController {
    
        private static final String SUCCESS = "success";
        private static final String FAILED = "failed";
    
        private final List<Date> dates = new ArrayList<>();
    
        @RequestMapping(value = "/api/v1/date/add", method = RequestMethod.GET)
        public ResponseEntity<String> addDate(@RequestParam("date") Date date) {
            ResponseEntity<String> response;
            try {
                dates.add(date);
                response = new ResponseEntity<>(SUCCESS, HttpStatus.OK);
            } catch (Exception e) {
                e.printStackTrace();
                response = new ResponseEntity<>(FAILED, HttpStatus.INTERNAL_SERVER_ERROR);
            }
            return response;
        }
    
    }
    复制代码

上面写好了一个简单的**Controller**，用于获取**Date**并存储。然后在单元测试中使用**TestRestTemplate**模拟客户端向服务端发起请求，程序如下。

@ExtendWith(SpringExtension.class)
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
    class DateControllerTest {
    
        @Autowired
        private TestRestTemplate restTemplate;
    
        @Test
        void 测试Date字符串转换为Date对象() {
            ResponseEntity<String> response = restTemplate
                    .getForEntity("/api/v1/date/add?date=20200620", String.class);
    
            assertThat(response.getStatusCodeValue(), is(HttpStatus.OK.value()));
        }
    
    }
    复制代码

由于此时并没有使用@**InitBinder**注解修饰的方法向**WebDataBinder**注册**CustomDateEditor**对象，运行测试程序时断言会无法通过，报错会包含如下信息。

> **Failed to convert value of type 'java.lang.String' to required type 'java.util.Date'**

由于无法将字符串转换为**Date**，导致了参数类型不匹配的异常。

下面使用@**ControllerAdvice**注解和@**InitBinder**注解为**WebDataBinder**添加**CustomDateEditor**对象，使**SpringMVC**框架为我们实现字符串转**Date**。

@ControllerAdvice
    public class GlobalControllerAdvice {
    
        @InitBinder
        public void setDateEditor(WebDataBinder binder) {
            binder.registerCustomEditor(Date.class,
                    new CustomDateEditor(new SimpleDateFormat("yyyyMMdd"), false));
        }
    
    }
    复制代码

此时再执行测试程序，断言通过。

**小节：由`@InitBinder`注解修饰的方法返回值类型必须为`void`，入参必须为`WebDataBinder`对象实例。如果在`@Controller`注解修饰的类中使用`@InitBinder`注解则配置仅对当前类生效，如果在`@ControllerAdvice`注解修饰的类中使用`@InitBinder`注解则配置全局生效**。

### 二. 实现自定义Editor ###

现在假如需要将日期字符串转换为**LocalDate**，但是**SpringMVC**框架并没有提供类似于**CustomDateEditor**这样的**Editor**时，可以通过继承**PropertyEditorSupport**类来实现自定义**Editor**。首先看如下的一个**Controller**。

@RestController
    public class LocalDateController {
    
        private static final String SUCCESS = "success";
        private static final String FAILED = "failed";
    
        private final List<LocalDate> localDates = new ArrayList<>();
    
        @RequestMapping(value = "/api/v1/localdate/add", method = RequestMethod.GET)
        public ResponseEntity<String> addLocalDate(@RequestParam("localdate") LocalDate localDate) {
            ResponseEntity<String> response;
            try {
                localDates.add(localDate);
                response = new ResponseEntity<>(SUCCESS, HttpStatus.OK);
            } catch (Exception e) {
                e.printStackTrace();
                response = new ResponseEntity<>(FAILED, HttpStatus.INTERNAL_SERVER_ERROR);
            }
            return response;
        }
    
    }
    复制代码

同样的在单元测试中使用**TestRestTemplate**模拟客户端向服务端发起请求。

@ExtendWith(SpringExtension.class)
    @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
    class LocalDateControllerTest {
    
        @Autowired
        private TestRestTemplate restTemplate;
    
        @Test
        void 测试LocalDate字符串转换为LocalDate对象() {
            ResponseEntity<String> response = restTemplate
                    .getForEntity("/api/v1/localdate/add?localdate=20200620", String.class);
    
            assertThat(response.getStatusCodeValue(), is(HttpStatus.OK.value()));
        }
    
    }
    复制代码

此时直接执行测试程序断言会不通过，会报错类型转换异常。现在实现一个自定义的**Editor**。

public class CustomLocalDateEditor extends PropertyEditorSupport {
    
        private static final DateTimeFormatter dateTimeFormatter
                = DateTimeFormatter.ofPattern("yyyyMMdd");
    
        @Override
        public void setAsText(String text) throws IllegalArgumentException {
            if (StringUtils.isEmpty(text)) {
                throw new IllegalArgumentException("Can not convert null.");
            }
            LocalDate result;
            try {
                result = LocalDate.from(dateTimeFormatter.parse(text));
                setValue(result);
            } catch (Exception e) {
                throw new IllegalArgumentException("CustomDtoEditor convert failed.", e);
            }
        }
    
    }
    复制代码

**CustomLocalDateEditor**是自定义的**Editor**，最简单的情况下，通过继承**PropertyEditorSupport**并重写**setAsText()** 方法可以实现一个自定义**Editor**。通常，自定义的转换逻辑在**setAsText()** 方法中实现，并将转换后的值通过调用父类**PropertyEditorSupport**的**setValue()** 方法完成设置。

同样的，使用@**ControllerAdvice**注解和@**InitBinder**注解为**WebDataBinder**添加**CustomLocalDateEditor**对象。

@ControllerAdvice
    public class GlobalControllerAdvice {
    
        @InitBinder
        public void setLocalDateEditor(WebDataBinder binder) {
            binder.registerCustomEditor(LocalDate.class,
                    new CustomLocalDateEditor());
        }
    
    }
    复制代码

此时再执行测试程序，断言全部通过。

**小节：通过继承`PropertyEditorSupport`类并重写`setAsText()`方法可以实现一个自定义`Editor`**。

### 三. WebDataBinder初始化原理解析 ###

已经知道，由@**InitBinder**注解修饰的方法用于初始化**WebDataBinder**，并且在[详解SpringMVC-RequestMappingHandlerAdapter][SpringMVC-RequestMappingHandlerAdapter]这篇文章中提到：从**request**获取到**handler**方法中由@**RequestParam**注解或@**PathVariable**注解修饰的参数后，便会使用**WebDataBinderFactory**工厂完成对**WebDataBinder**的初始化。下面看一下具体的实现。

**AbstractNamedValueMethodArgumentResolver\#resolveArgument**部分源码如下所示。

public final Object resolveArgument(MethodParameter parameter, @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest, @Nullable WebDataBinderFactory binderFactory) throws Exception {
    
        // ...
    
        // 获取到参数
        Object arg = resolveName(resolvedName.toString(), nestedParameter, webRequest);
    
        // ...
    
        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());
            }
            if (arg == null && namedValueInfo.defaultValue == null &&
                    namedValueInfo.required && !nestedParameter.isOptional()) {
                handleMissingValue(namedValueInfo.name, nestedParameter, webRequest);
            }
        }
    
        handleResolvedValue(arg, namedValueInfo.name, parameter, mavContainer, webRequest);
    
        return arg;
    }
    复制代码

实际上，上面方法中的**binderFactory**是**ServletRequestDataBinderFactory**工厂类，该类的类图如下所示。

![format_png][]

**createBinder()** 是由接口**WebDataBinderFactory**声明的方法，**ServletRequestDataBinderFactory**的父类**DefaultDataBinderFactory**对其进行了实现，实现如下。

public final WebDataBinder createBinder(
            NativeWebRequest webRequest, @Nullable Object target, String objectName) throws Exception {
    
        // 创建WebDataBinder实例
        WebDataBinder dataBinder = createBinderInstance(target, objectName, webRequest);
        if (this.initializer != null) {
            // 调用WebBindingInitializer对WebDataBinder进行初始化
            this.initializer.initBinder(dataBinder, webRequest);
        }
        // 调用由@InitBinder注解修饰的方法对WebDataBinder进行初始化
        initBinder(dataBinder, webRequest);
        return dataBinder;
    }
    复制代码

**initBinder()** 是**DefaultDataBinderFactory**的一个模板方法，**InitBinderDataBinderFactory**对其进行了重写，如下所示。

public void initBinder(WebDataBinder dataBinder, NativeWebRequest request) throws Exception {
        for (InvocableHandlerMethod binderMethod : this.binderMethods) {
            if (isBinderMethodApplicable(binderMethod, dataBinder)) {
                // 执行由@InitBinder注解修饰的方法，完成对WebDataBinder的初始化
                Object returnValue = binderMethod.invokeForRequest(request, null, dataBinder);
                if (returnValue != null) {
                    throw new IllegalStateException(
                            "@InitBinder methods must not return a value (should be void): " + binderMethod);
                }
            }
        }
    }
    复制代码

如上，**initBinder()** 方法中会遍历加载的所有由@**InitBinder**注解修饰的方法并执行，从而完成对**WebDataBinder**的初始化。

**小节：`WebDataBinder`的初始化是由`WebDataBinderFactory`先创建`WebDataBinder`实例，然后遍历`WebDataBinderFactory`加载好的由`@InitBinder`注解修饰的方法并执行，以完成`WebDataBinder`的初始化**。

### 四. @InitBinder注解修饰的方法的加载 ###

由第三小节可知，**WebDataBinder**的初始化是由**WebDataBinderFactory**先创建**WebDataBinder**实例，然后遍历**WebDataBinderFactory**加载好的由@**InitBinder**注解修饰的方法并执行，以完成**WebDataBinder**的初始化。本小节将学习**WebDataBinderFactory**如何加载由@**InitBinder**注解修饰的方法。

**WebDataBinderFactory**的获取是发生在**RequestMappingHandlerAdapter**的**invokeHandlerMethod()** 方法中，在该方法中是通过调用**getDataBinderFactory()** 方法获取**WebDataBinderFactory**。下面看一下其实现。

**RequestMappingHandlerAdapter\#getDataBinderFactory**源码如下所示。

private WebDataBinderFactory getDataBinderFactory(HandlerMethod handlerMethod) throws Exception {
        // 获取handler的Class对象
        Class<?> handlerType = handlerMethod.getBeanType();
        // 从initBinderCache中根据handler的Class对象获取缓存的initBinder方法集合
        Set<Method> methods = this.initBinderCache.get(handlerType);
        // 从initBinderCache没有获取到initBinder方法集合，则执行MethodIntrospector.selectMethods()方法获取handler的initBinder方法集合，并缓存到initBinderCache中
        if (methods == null) {
            methods = MethodIntrospector.selectMethods(handlerType, INIT_BINDER_METHODS);
            this.initBinderCache.put(handlerType, methods);
        }
        // initBinderMethods是WebDataBinderFactory需要加载的initBinder方法集合
        List<InvocableHandlerMethod> initBinderMethods = new ArrayList<>();
        // initBinderAdviceCache中存储的是全局生效的initBinder方法
        this.initBinderAdviceCache.forEach((controllerAdviceBean, methodSet) -> {
            // 如果ControllerAdviceBean有限制生效范围，则判断其是否对当前handler生效
            if (controllerAdviceBean.isApplicableToBeanType(handlerType)) {
                Object bean = controllerAdviceBean.resolveBean();
                // 如果对当前handler生效，则ControllerAdviceBean的所有initBinder方法均需要添加到initBinderMethods中
                for (Method method : methodSet) {
                    initBinderMethods.add(createInitBinderMethod(bean, method));
                }
            }
        });
        // 将handler的所有initBinder方法添加到initBinderMethods中
        for (Method method : methods) {
            Object bean = handlerMethod.getBean();
            initBinderMethods.add(createInitBinderMethod(bean, method));
        }
        // 创建WebDataBinderFactory，并同时加载initBinderMethods中的所有initBinder方法
        return createDataBinderFactory(initBinderMethods);
    }
    复制代码

上面的方法中使用到了两个缓存，**initBinderCache**和**initBinderAdviceCache**，表示如下。

private final Map<Class<?>, Set<Method>> initBinderCache = new ConcurrentHashMap<>(64);
    
    private final Map<ControllerAdviceBean, Set<Method>> initBinderAdviceCache = new LinkedHashMap<>();
    复制代码

其中**initBinderCache**的**key**是**handler**的**Class**对象，**value**是**handler**的**initBinder**方法集合，**initBinderCache**一开始是没有值的，当需要获取**handler**对应的**initBinder**方法集合时，会先从**initBinderCache**中获取，如果获取不到才会调用**MethodIntrospector\#selectMethods**方法获取，然后再将获取到的**handler**对应的**initBinder**方法集合缓存到**initBinderCache**中。

**initBinderAdviceCache**的**key**是**ControllerAdviceBean**，**value**是**ControllerAdviceBean**的**initBinder**方法集合，**initBinderAdviceCache**的值是在**RequestMappingHandlerAdapter**初始化时调用的**afterPropertiesSet()** 方法中完成加载的，具体的逻辑在[详解SpringMVC-RequestMappingHandlerAdapter][SpringMVC-RequestMappingHandlerAdapter]有详细说明。

因此**WebDataBinderFactory**中的**initBinder**方法由两部分组成，一部分是写在当前**handler**中的**initBinder**方法（这解释了为什么写在**handler**中的**initBinder**方法仅对当前**handler**生效），另外一部分是写在由@**ControllerAdvice**注解修饰的类中的**initBinder**方法，所有的这些**initBinder**方法均会对**WebDataBinderFactory**创建的**WebDataBinder**对象进行初始化。

最后，看一下**createDataBinderFactory()** 的实现。

**`RequestMappingHandlerAdapter#createDataBinderFactory`**

protected InitBinderDataBinderFactory createDataBinderFactory(List<InvocableHandlerMethod> binderMethods)
            throws Exception {
    
        return new ServletRequestDataBinderFactory(binderMethods, getWebBindingInitializer());
    }
    复制代码

**`ServletRequestDataBinderFactory#ServletRequestDataBinderFactory`**

public ServletRequestDataBinderFactory(@Nullable List<InvocableHandlerMethod> binderMethods,
            @Nullable WebBindingInitializer initializer) {
    
        super(binderMethods, initializer);
    }
    复制代码

**`InitBinderDataBinderFactory#InitBinderDataBinderFactory`**

public InitBinderDataBinderFactory(@Nullable List<InvocableHandlerMethod> binderMethods,
            @Nullable WebBindingInitializer initializer) {
    
        super(initializer);
        this.binderMethods = (binderMethods != null ? binderMethods : Collections.emptyList());
    }
    复制代码

可以发现，最终创建的**WebDataBinderFactory**实际上是**ServletRequestDataBinderFactory**，并且在执行**ServletRequestDataBinderFactory**的构造函数时，会调用其父类**InitBinderDataBinderFactory**的构造函数，在这个构造函数中，会将之前获取到的生效范围内的**initBinder**方法赋值给**InitBinderDataBinderFactory**的**binderMethods**变量，最终完成了**initBinder**方法的加载。

**小节：由`@InitBinder`注解修饰的方法的加载发生在创建`WebDataBinderFactory`时，在创建`WebDataBinderFactory`之前，会先获取对当前handler生效的initBinder方法集合，然后在创建`WebDataBinderFactory`的构造函数中将获取到的initBinder方法集合加载到`WebDataBinderFactory`中**。

## 总结 ##

由@**InitBinder**注解修饰的方法用于初始化**WebDataBinder**，从而实现请求参数的类型转换适配，例如日期字符串转换为日期**Date**类型，同时可以通过继承**PropertyEditorSupport**类来实现自定义**Editor**，从而增加可以转换适配的类型种类。

[SpringMVC-RequestMappingHandlerAdapter]: https://juejin.cn/post/7203717563237924919
[format_png]: https://img-blog.csdnimg.cn/img_convert/b4c22f8f4c6afdac338b6c06bb206213.webp?x-oss-process=image/format,png