java | spring boot | WebDataBinder 정리 (Spring MVC 데이터 바인딩 핵심)

by

Create by.ChatGPT

Spring MVC에서 WebDataBinder는
HTTP 요청 파라미터를 자바 객체로 변환(binding)하고 검증(validation)을 연결해주는 핵심 컴포넌트입니다.

한 문장 요약

WebDataBinder는 요청 데이터(String)를 컨트롤러가 사용하는 자바 객체 타입으로 안전하게 변환하고 검증하는 역할을 한다.

WebDataBinder란?

웹 요청에서 전달되는 값은 모두 문자열(String) 입니다.

예:

?age=20&price=1000&date=2025-12-16

하지만 컨트롤러에서는 다음과 같이 자바 타입으로 받고 싶습니다.

int age;
int price;
LocalDate date;

👉 이때 문자열 → 자바 객체 변환을 담당하는 것이 WebDataBinder입니다.

WebDataBinder의 역할

WebDataBinder는 다음 역할을 수행합니다.

  1. 데이터 바인딩 (Binding)
    • 요청 파라미터 → 자바 객체 필드에 자동 매핑
  2. 타입 변환 (Type Conversion)
    • String → int, long, boolean, enum, LocalDate 등
  3. 검증 연동 (Validation)
    • @Valid, @Validated와 함께 동작
    • BindingResult에 오류 저장
  4. 보안 필터링
    • 바인딩 가능한 필드 제한 (setAllowedFields)

언제 WebDataBinder가 동작하는가?

아래와 같은 경우 자동으로 동작합니다.

@PostMapping("/users")
public String createUser(User user) {
    return "result";
}
  • 요청 파라미터 → User 객체
  • 이 과정에서 WebDataBinder가 내부적으로 사용됨
  • 개발자가 직접 생성하지 않음

동작 흐름 요약

  1. HTTP 요청 도착
  2. DispatcherServlet 수신
  3. Controller 호출
  4. WebDataBinder 생성
  5. 요청 파라미터를 객체에 바인딩
  6. 타입 변환 + 검증 수행
  7. Controller 메서드 실행

예제: 자동 데이터 바인딩

요청

POST /users
name=kim&age=20

Controller

@PostMapping("/users")
public String create(User user) {
    System.out.println(user.getName()); // kim
    System.out.println(user.getAge());  // 20
    return "ok";
}

👉 이 자동 변환의 핵심이 WebDataBinder입니다.

@InitBinder와 WebDataBinder

@InitBinder를 사용하면 WebDataBinder를 직접 커스터마이징할 수 있습니다.

@InitBinder
public void initBinder(WebDataBinder binder) {
    binder.setAllowedFields("name", "age");
}

의미

  • name, age 필드만 바인딩 허용
  • 나머지 필드는 무시됨
  • 보안 강화 목적

커스텀 타입 변환 (PropertyEditor)

예: String → LocalDate 변환

@InitBinder
public void initBinder(WebDataBinder binder) {
    binder.registerCustomEditor(
        LocalDate.class,
        new PropertyEditorSupport() {
            @Override
            public void setAsText(String text) {
                setValue(LocalDate.parse(text));
            }
        }
    );
}

👉 특정 타입 변환 규칙을 직접 정의 가능

(실무에서는 Converter / Formatter 사용을 더 권장)

Validation과 WebDataBinder

WebDataBinder는 검증기(Validator) 와 함께 동작합니다.

@PostMapping("/users")
public String create(
    @Valid User user,
    BindingResult bindingResult
) {
    if (bindingResult.hasErrors()) {
        return "error";
    }
    return "ok";
}
  • 바인딩 중 오류 발생 시
  • 오류 정보가 BindingResult에 저장됨
  • WebDataBinder가 이 연결을 담당

WebDataBinder vs @RequestParam vs @ModelAttribute

구분역할
WebDataBinder내부 동작 엔진
@RequestParam단일 파라미터 추출
@ModelAttribute객체 단위 바인딩
@RequestBodyJSON → 객체 (HttpMessageConverter 사용)

👉 @ModelAttribute 내부에서 WebDataBinder가 사용됨

WebDataBinder와 @RequestBody의 차이

  • WebDataBinder
    • Form 데이터
    • Query Parameter
    • application/x-www-form-urlencoded
  • @RequestBody
    • JSON
    • HttpMessageConverter 사용
    • WebDataBinder 사용 ❌

실무 핵심 포인트

  • WebDataBinder는 직접 사용하지 않지만 항상 동작
  • 데이터 바인딩의 중심 역할
  • 보안(필드 제한)과 검증에 매우 중요
  • Spring MVC의 자동화 핵심 기술 중 하나

DispatcherServlet과의 관계

DispatcherServlet이 요청 흐름을 제어한다면
WebDataBinder는 요청 데이터를 객체로 만드는 역할을 담당한다.

마무리

Spring MVC의 “자동 바인딩”이 마법처럼 보인다면,
그 중심에는 항상 WebDataBinder가 있다.