💡 Java Spring에서 자주 사용하는 ObjectMapper

Java로 웹 개발을 하다 보면 객체(Object)와 JSON 사이를 변환해야 하는 일이 굉장히 많습니다. 이때 유용하게 쓰이는 라이브러리가 바로 ObjectMapper입니다. 특히 Spring에서는 이 ObjectMapper를 이용해서 직렬화(Serialize)와 역직렬화(Deserialize)를 아주 손쉽게 처리할 수 있죠.

이번 포스팅에서는 ObjectMapper의 기본 사용법부터 실무에서 자주 쓰는 옵션들, 그리고 실전 예제까지 깔끔하게 정리해드릴게요!

---

📦 ObjectMapper란?

ObjectMapper는 Jackson 라이브러리에서 제공하는 클래스입니다. JSON 데이터를 Java 객체로 변환하거나, Java 객체를 JSON 문자열로 변환할 때 사용합니다.

Spring Boot에서는 기본적으로 Jackson이 내장되어 있어 별다른 설정 없이도 바로 사용할 수 있어요.

---

🔧 기본 사용법

import com.fasterxml.jackson.databind.ObjectMapper;

public class ObjectMapperExample {
    public static void main(String[] args) throws Exception {
        ObjectMapper objectMapper = new ObjectMapper();

        // Java 객체 -> JSON 문자열
        User user = new User("홍길동", 30);
        String json = objectMapper.writeValueAsString(user);
        System.out.println(json);

        // JSON 문자열 -> Java 객체
        String jsonStr = "{\"name\":\"홍길동\",\"age\":30}";
        User result = objectMapper.readValue(jsonStr, User.class);
        System.out.println(result.getName() + ", " + result.getAge());
    }
}

class User {
    private String name;
    private int age;

    public User() {} // 기본 생성자 필수

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

    // Getter/Setter 생략 가능 (Lombok 쓰면 더 간편)
}

---

🧪 실무에서 자주 쓰는 옵션들

1. @JsonProperty

JSON 필드명과 객체 필드명이 다를 때 매핑을 도와주는 어노테이션입니다.

public class User {
    @JsonProperty("user_name")
    private String name;

    private int age;
}

2. @JsonIgnore

해당 필드는 JSON 직렬화/역직렬화에서 제외됩니다.

public class User {
    private String name;

    @JsonIgnore
    private String password;
}

3. 날짜 포맷 설정

// ObjectMapper에 포맷 설정
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

혹은 어노테이션으로도 처리할 수 있어요:

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss")
private Date createdAt;

4. FAIL_ON_UNKNOWN_PROPERTIES 무시 설정

objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

5. Pretty Print (JSON 보기 좋게 출력)

String prettyJson = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(obj);

---

🧑‍💻 실무 적용 예제: Controller에서 사용

Spring에서는 대부분 자동으로 ObjectMapper가 작동하지만, 직접 사용해야 할 상황도 있습니다. 예를 들어 Redis 캐싱, 로그 출력, Kafka 메시지 처리 등.

@RestController
@RequiredArgsConstructor
public class SampleController {

    private final ObjectMapper objectMapper;

    @GetMapping("/user/json")
    public String getUserJson() throws JsonProcessingException {
        User user = new User("이순신", 45);
        return objectMapper.writeValueAsString(user);
    }
}

---

✅ 마무리 정리

기능	설명
writeValueAsString	객체 → JSON 문자열
readValue	JSON 문자열 → 객체
@JsonProperty	JSON 필드명 지정
@JsonIgnore	필드 무시
@JsonFormat	날짜 포맷 지정
FAIL_ON_UNKNOWN_PROPERTIES	존재하지 않는 필드 무시 설정
writerWithDefaultPrettyPrinter()	JSON 보기 좋게 출력

---

🚀 고급 사용법: ObjectMapper 커스터마이징 및 모듈 등록

기본 기능 외에도 ObjectMapper는 다양한 방식으로 커스터마이징이 가능합니다. 특히 LocalDate, LocalDateTime 같은 java.time 패키지 타입을 제대로 처리하려면 JavaTimeModule을 등록해야 합니다.

1. JavaTimeModule 등록

기본적으로 Jackson은 Java 8 날짜/시간 API를 인식하지 못하기 때문에 아래와 같이 모듈을 등록해야 합니다.

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.databind.SerializationFeature;

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());

        // timestamp가 아닌 문자열로 날짜 출력
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);

        return mapper;
    }
}

이렇게 설정하면 LocalDate나 LocalDateTime도 JSON 변환 시 문제가 발생하지 않으며, 날짜 포맷도 보기 좋게 출력됩니다.

---

2. 날짜 포맷 전역 적용

날짜 포맷을 통일되게 적용하고 싶을 때도 ObjectMapper 커스터마이징이 유용합니다.

SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
mapper.setDateFormat(dateFormat);

---

3. 빈 값 무시 (null 제거)

mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

위 설정을 하면 JSON 직렬화 시 null 필드는 아예 출력되지 않습니다. API 응답을 더 깔끔하게 만들 수 있어요.

---

4. 커스터마이징된 ObjectMapper를 사용하는 방법

Spring에서는 기본적으로 MappingJackson2HttpMessageConverter에 ObjectMapper가 들어갑니다. 따라서 아래처럼 전체 컨버터에 적용할 수도 있습니다.

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final ObjectMapper objectMapper;

    public WebConfig(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }

    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        for (HttpMessageConverter<?> converter : converters) {
            if (converter instanceof MappingJackson2HttpMessageConverter) {
                ((MappingJackson2HttpMessageConverter) converter).setObjectMapper(objectMapper);
            }
        }
    }
}

---

---

📌 결론

ObjectMapper는 Spring 개발자라면 필수로 익혀야 할 도구입니다. 단순한 JSON 변환뿐 아니라 다양한 옵션을 활용하면 더 안정적이고 유연한 데이터 처리를 할 수 있습니다.