A Custom Data Binder in Spring MVC – Spring MVC中的自定义数据绑定器

最后修改: 2017年 1月 11日


1. Overview


This article will show how we can use Spring’s Data Binding mechanism in order to make our code more clear and readable by applying automatic primitives to objects conversions.


By default, Spring only knows how to convert simple types. In other words, once we submit data to controller Int, String or Boolean type of data, it will be bound to appropriate Java types automatically.


But in real-world projects, that won’t be enough, as we might need to bind more complex types of objects.


2. Binding Individual Objects to Request Parameters


Let’s start simple and first bind a simple type; we’ll have to provide a custom implementation of the Converter<S, T> interface where S is the type we are converting from, and T is the type we are converting to:

让我们从简单的开始,首先绑定一个简单的类型;我们必须提供一个Converter<S, T>接口的自定义实现,其中S是我们要转换的类型,而T是我们要转换的类型。

public class StringToLocalDateTimeConverter
  implements Converter<String, LocalDateTime> {

    public LocalDateTime convert(String source) {
        return LocalDateTime.parse(
          source, DateTimeFormatter.ISO_LOCAL_DATE_TIME);

Now we can use the following syntax in our controller:


public GenericEntity findByDate(@PathVariable("date") LocalDateTime date) {
    return ...;

2.1. Using Enums as Request Parameters


Next, we’ll see how to use enum as a RequestParameter.


Here, we have a simple enum Modes:

这里,我们有一个简单的enum Modes

public enum Modes {

We’ll build a String to enum Converter as follows:


public class StringToEnumConverter implements Converter<String, Modes> {

    public Modes convert(String from) {
        return Modes.valueOf(from);

Then, we need to register our Converter:


public class WebConfig implements WebMvcConfigurer {

    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToEnumConverter());

Now we can use our Enum as a RequestParameter:


public ResponseEntity<Object> getStringToMode(@RequestParam("mode") Modes mode) {
    // ...

Or as a PathVariable:


public GenericEntity findByEnum(@PathVariable("mode") Modes mode) {
    // ...

3. Binding a Hierarchy of Objects


Sometimes we need to convert the entire tree of the object hierarchy and it makes sense to have a more centralized binding rather than a set of individual converters.


In this example, we have AbstractEntity our base class:


public abstract class AbstractEntity {
    long id;
    public AbstractEntity(long id){
        this.id = id;

And the sub-classes Foo and Bar:


public class Foo extends AbstractEntity {
    private String name;
    // standard constructors, getters, setters
public class Bar extends AbstractEntity {
    private int value;
    // standard constructors, getters, setters

In this case, we can implement ConverterFactory<S, R> where S will be the type we are converting from and R to be the base type defining the range of classes we can convert to:

在这种情况下,我们可以实现ConverterFactory<S, R>,其中S将是我们要转换的类型,R是基础类型,定义我们可以转换的类的范围。

public class StringToAbstractEntityConverterFactory 
  implements ConverterFactory<String, AbstractEntity>{

    public <T extends AbstractEntity> Converter<String, T> getConverter(Class<T> targetClass) {
        return new StringToAbstractEntityConverter<>(targetClass);

    private static class StringToAbstractEntityConverter<T extends AbstractEntity>
      implements Converter<String, T> {

        private Class<T> targetClass;

        public StringToAbstractEntityConverter(Class<T> targetClass) {
            this.targetClass = targetClass;

        public T convert(String source) {
            long id = Long.parseLong(source);
            if(this.targetClass == Foo.class) {
                return (T) new Foo(id);
            else if(this.targetClass == Bar.class) {
                return (T) new Bar(id);
            } else {
                return null;

As we can see, the only method that must implement is getConverter() which returns converter for needed type. The conversion process then is delegated to this converter.


Then, we need to register our ConverterFactory:


public class WebConfig implements WebMvcConfigurer {

    public void addFormatters(FormatterRegistry registry) {
        registry.addConverterFactory(new StringToAbstractEntityConverterFactory());

Finally, we can use it as we like in our controller:


public class AbstractEntityController {

    public ResponseEntity<Object> getStringToFoo(@PathVariable Foo foo) {
        return ResponseEntity.ok(foo);
    public ResponseEntity<Object> getStringToBar(@PathVariable Bar bar) {
        return ResponseEntity.ok(bar);

4. Binding Domain Objects


There are cases when we want to bind data to objects, but it comes either in a non-direct way (for example, from Session, Header or Cookie variables) or even stored in a data source. In those cases, we need to use a different solution.


4.1. Custom Argument Resolver


First of all, we will define an annotation for such parameters:


public @interface Version {

Then, we will implement a custom HandlerMethodArgumentResolver:


public class HeaderVersionArgumentResolver
  implements HandlerMethodArgumentResolver {

    public boolean supportsParameter(MethodParameter methodParameter) {
        return methodParameter.getParameterAnnotation(Version.class) != null;

    public Object resolveArgument(
      MethodParameter methodParameter, 
      ModelAndViewContainer modelAndViewContainer, 
      NativeWebRequest nativeWebRequest, 
      WebDataBinderFactory webDataBinderFactory) throws Exception {
        HttpServletRequest request 
          = (HttpServletRequest) nativeWebRequest.getNativeRequest();

        return request.getHeader("Version");

The last thing is letting Spring know where to search for them:


public class WebConfig implements WebMvcConfigurer {


    public void addArgumentResolvers(
      List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new HeaderVersionArgumentResolver());

That’s it. Now we can use it in a controller:


public ResponseEntity findByVersion(
  @PathVariable Long id, @Version String version) {
    return ...;

As we can see, HandlerMethodArgumentResolver‘s resolveArgument() method returns an Object. In other words, we could return any object, not only String.


5. Conclusion


As a result, we got rid of many routine conversions and let Spring do most stuff for us. At the end, let’s conclude:


  • For an individual simple type to object conversions we should use Converter implementation
  • For encapsulating conversion logic for a range of objects, we can try ConverterFactory implementation
  • For any data comes indirectly or it is required to apply additional logic to retrieve the associated data it’s better to use HandlerMethodArgumentResolver

As usual, all the examples can be always found at our GitHub repository.