Mastering @InitBinder in Spring Boot 3: Custom Data Binding Techniques

1. Introduction

In @Controller or @ControllerAdvice classes you can annotate methods with @InitBinder to initialize a WebDataBinder instance. These methods can bind request parameters to model objects, convert string values to object property types, and format model attributes as strings when rendering HTML forms.

When @InitBinder is used inside a @Controller, it applies only to that controller (or to specific model attributes referenced by name). When placed in a @ControllerAdvice, the method applies to all controllers.

You can register PropertyEditor, Converter, and Formatter components in the DataBinder for type conversion, or register them globally via the FormattingConversionService in MVC configuration.

2. Practical Cases

Case 1

Parameter format: xxx-\d (e.g., order-1). The number after the hyphen is automatically converted to an integer.

@RestController
@RequestMapping("/binders")
public class BinderController {
  @InitBinder
  public void init(WebDataBinder dataBinder) {
    // Register custom editor to convert String to Integer
    dataBinder.registerCustomEditor(Integer.class, new PropertyEditorSupport() {
      public void setAsText(String text) throws IllegalArgumentException {
        // Parse input parameter
        setValue(Integer.valueOf(text.split("-")[1]));
      }
    });
  }
  // Request endpoint
  @GetMapping("/user")
  public Object binder(Integer id) {
    return id;
  }
}

Test result:

Case 2

Parameter format: xxx,yyy (e.g., 张三,22). The comma separates values which are converted into a User object.

@RestController
@RequestMapping("/binders")
public class BinderController {
  @InitBinder
  public void init(WebDataBinder dataBinder) {
    // Convert String to User
    WebConversionService cs = (WebConversionService) dataBinder.getConversionService();
    cs.addConverter(new Converter<String, User>() {
      @Override
      public User convert(String source) {
        String[] ars = source.split(",");
        return new User(ars[0], Integer.valueOf(ars[1]));
      }
    });
  }
  // Request endpoint
  @GetMapping("/user")
  public Object binder(User user) {
    return user;
  }
}

Test result:

Case 3

Binding property values with conversion.

@RestController
@RequestMapping("/binders")
public class BinderController {
  @InitBinder
  public void init(WebDataBinder dataBinder) {
    dataBinder.registerCustomEditor(User.class, new PropertyEditorSupport() {
      @Override
      public void setAsText(String text) throws IllegalArgumentException {
        String[] ars = text.split(",");
        setValue(new User(ars[0], Integer.valueOf(ars[1])));
      }
    });
  }
  // Request endpoint
  @GetMapping("/user")
  public Object binder(DTO dto) {
    return dto;
  }
}

public class DTO {
  private User user;
}

Test result:

Case 4

Define a global data binder using @ControllerAdvice.

@ControllerAdvice
public class InitBinderGlobalAdvice {
  @InitBinder
  public void init(WebDataBinder dataBinder) {
    dataBinder.registerCustomEditor(User.class, new PropertyEditorSupport() {
      @Override
      public void setAsText(String text) throws IllegalArgumentException {
        String[] ars = text.split(",");
        setValue(new User(ars[0], Integer.valueOf(ars[1])));
      }
    });
  }
}

Through @ControllerAdvice you can declare a globally scoped configuration, and you can also fine‑tune it via annotation attributes.

Case 5

Fine‑tune data binding configuration, e.g., bind directly to fields (no setter) and restrict binding to specific fields.

@RestController
@RequestMapping("/binders")
public class BinderController {
  @InitBinder
  public void init(WebDataBinder dataBinder) {
    // Allow only the "age" field to be bound
    dataBinder.setAllowedFields("age");
    // Enable direct field access (bind without setter)
    dataBinder.initDirectFieldAccess();
    // ...
  }
}

Test result:

All the above content aims to help you master custom data binding in Spring Boot.

End of article.