[Spring Boot] JSON 데이터 자동 변환 원리: Jackson과 HttpMessageConverter

안녕하세요. IT 기술 블로거입니다.

Spring Boot로 REST API를 개발할 때, 우리는 컨트롤러에서 단순히 자바 객체를 반환하기만 합니다. 그러면 클라이언트는 신기하게도 예쁘게 정렬된 JSON 데이터를 받게 되죠. 반대로 클라이언트가 보낸 JSON 데이터도 자바 객체로 쏙 들어옵니다.

개발자는 별다른 설정을 하지 않았는데, 이 “자동 변환”은 누가 해주는 걸까요? 오늘은 Spring Boot 내부에서 일어나는 마법 같은 일, HttpMessageConverter와 Jackson 라이브러리의 동작 원리를 깊이 있게 파헤쳐 보겠습니다.

1. 마법의 주인공: HttpMessageConverter

Spring MVC는 HTTP 요청 본문을 읽거나 응답 본문을 쓸 때 HttpMessageConverter 인터페이스를 사용합니다.

동작 시점

• 요청 시: @RequestBody가 붙은 파라미터를 읽을 때
• 응답 시: @ResponseBody (또는 @RestController)가 붙은 메서드의 반환값을 처리할 때

결정 방식

Spring은 등록된 여러 컨버터 중 현재 요청의 Content-Type(요청 시)이나 Accept(응답 시) 헤더를 확인하여 적절한 컨버터를 선택합니다.
– 문자열이면? StringHttpMessageConverter
– 객체(JSON)면? MappingJackson2HttpMessageConverter

2. JSON 변환의 실세: Jackson 라이브러리

Spring Boot는 JSON 변환을 위해 기본적으로 Jackson이라는 라이브러리를 사용합니다. MappingJackson2HttpMessageConverter가 내부적으로 Jackson의 ObjectMapper를 호출하여 변환을 수행합니다.

직렬화 (Serialization): Java Object -> JSON

서버에서 데이터를 내보낼 때 발생합니다. Jackson은 객체의 Getter 메서드를 사용하여 필드 값을 읽어 JSON 키-값 쌍을 만듭니다.

역직렬화 (Deserialization): JSON -> Java Object

클라이언트 요청을 받을 때 발생합니다. Jackson은 클래스의 기본 생성자로 객체를 생성한 뒤, JSON 키와 매칭되는 필드나 Setter를 통해 값을 주입합니다.

3. 실무 코드 예제: Jackson 제어하기

단순 변환을 넘어, 특정 필드의 이름을 바꾸거나 날짜 형식을 지정하고 싶을 때 어노테이션을 사용합니다.

예제 1: 필드명 매핑 및 무시 (@JsonProperty, @JsonIgnore)

@Getter
@NoArgsConstructor
public class UserDto {

    @JsonProperty("user_name") // JSON의 "user_name" 키를 "name" 필드에 매핑
    private String name;

    private int age;

    @JsonIgnore // 응답 JSON에서 이 필드는 제외됨
    private String password;

    public UserDto(String name, int age, String password) {
        this.name = name;
        this.age = age;
        this.password = password;
    }
}

예제 2: 날짜 형식 지정 (@JsonFormat)

@Getter
public class PostResponseDto {
    private String title;

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Seoul")
    private LocalDateTime createdDate;
}

4. 주의사항: 기본 생성자와 Getter

Jackson을 사용할 때 개발자들이 가장 많이 겪는 오류는 다음 두 가지입니다.

1. 기본 생성자 부재: 역직렬화(JSON -> Object) 시 Jackson은 객체를 먼저 생성해야 합니다. 기본 생성자가 없으면 InvalidDefinitionException이 발생할 수 있습니다. (Lombok의 @NoArgsConstructor 사용 권장)
2. Getter 부재: 직렬화(Object -> JSON) 시 Jackson은 Getter를 통해 값을 읽습니다. Getter가 없으면 해당 필드가 JSON에서 빠지거나 오류가 날 수 있습니다.

결론

Spring Boot에서 JSON 데이터가 자동으로 변환되는 원리는 “HttpMessageConverter가 요청 헤더를 보고 Jackson의 ObjectMapper를 호출하여 자바의 표준 자산(Getter, 생성자)을 활용하는 과정”입니다.

이 원리를 이해하면 단순히 어노테이션을 붙이는 것을 넘어, 복잡한 데이터 구조를 어떻게 JSON으로 설계하고 제어할지 알 수 있게 됩니다. 특히 실무에서는 날짜 포맷이나 보안상 민감한 필드 처리를 위해 Jackson 어노테이션을 적극 활용해 보세요.

다음 시간에는 단순히 객체만 반환하는 것을 넘어, HTTP 상태 코드와 헤더를 정교하게 제어할 수 있는 “ResponseEntity를 사용하는 이유”에 대해 알아보겠습니다.