Jackson ObjectMapper 사용법과 JSON 변환 예제 정리

Jackson ObjectMapper 사용법을 처음부터 실무 예제까지 쉽게 정리해 드립니다. JSON 문자열과 Java 객체를 서로 변환하는 방법, JSON 파일 처리, 컬렉션 변환, 예외 처리와 실무에서 자주 사용하는 기능까지 한 번에 이해하실 수 있습니다.

웹 서비스나 REST API를 개발하다 보면 JSON 데이터를 Java 객체로 변환하거나, Java 객체를 다시 JSON 문자열로 만들어야 하는 경우가 매우 자주 발생합니다. 이때 가장 널리 사용되는 라이브러리 가운데 하나가 바로 Jackson입니다.

특히 ObjectMapper는 Jackson의 핵심 클래스이며, JSON과 Java 객체 사이를 자유롭게 변환할 수 있도록 다양한 기능을 제공합니다. Spring Boot에서도 내부적으로 Jackson을 기본 JSON 처리 라이브러리로 사용하기 때문에 ObjectMapper의 사용법을 이해하면 API 개발이 훨씬 쉬워집니다.

이번 글에서는 Jackson ObjectMapper 사용법, JSON 변환 방법, 컬렉션 처리, 파일 읽기와 쓰기, 실무에서 자주 사용하는 기능까지 예제를 중심으로 자세히 알아보겠습니다.

01. ObjectMapper가 무엇인지 이해하기

이번 섹션에서는 ObjectMapper의 역할과 Jackson에서 왜 중요한지 살펴보겠습니다.

✓ ObjectMapper란 무엇일까요?

ObjectMapper는 Jackson 라이브러리에서 제공하는 핵심 클래스입니다.

가장 중요한 역할은 다음 두 가지입니다.

• JSON → Java 객체 변환
• Java 객체 → JSON 변환

즉, 개발자가 직접 JSON을 문자열로 분석하거나 객체를 하나씩 생성하지 않아도 ObjectMapper가 대부분의 작업을 자동으로 처리해 줍니다.

Spring Boot에서는 HTTP 요청의 JSON을 DTO로 변환하거나 Controller에서 반환한 객체를 JSON으로 응답할 때도 내부적으로 ObjectMapper가 사용됩니다.

02. Jackson 라이브러리 추가하기

이번 섹션에서는 프로젝트에서 Jackson을 사용하는 방법을 살펴보겠습니다.

✓ Gradle 프로젝트

Spring Boot를 사용하는 경우에는 대부분 Jackson이 기본 포함되어 있습니다.

순수 Java 프로젝트라면 Jackson Databind 라이브러리를 추가하면 됩니다.

필요한 대표 모듈은 다음과 같습니다.

라이브러리역할

jackson-databind	ObjectMapper 제공
jackson-core	JSON 파서
jackson-annotations	JSON 어노테이션 지원

대부분의 프로젝트에서는 jackson-databind만 추가해도 필요한 기능을 사용할 수 있습니다.

03. Java 객체를 JSON으로 변환하기

이번 섹션에서는 가장 많이 사용하는 JSON 직렬화를 살펴보겠습니다.

✓ writeValueAsString()

가장 많이 사용하는 메서드는 다음과 같습니다.

 

ObjectMapper mapper = new ObjectMapper();

User user = new User();
user.setName("Kim");
user.setAge(30);

String json = mapper.writeValueAsString(user);

System.out.println(json);

 

실행 결과는 다음과 비슷하게 생성됩니다.

 

{
  "name":"Kim",
  "age":30
}

 

이 과정을 직렬화(Serialization)라고 합니다.

직렬화란 Java 객체를 JSON으로 변환하는 과정을 의미합니다.

04. JSON을 Java 객체로 변환하기

이번 섹션에서는 JSON 문자열을 객체로 변환하는 방법을 알아보겠습니다.

✓ readValue()

JSON 문자열을 객체로 만드는 메서드는 readValue()입니다.

 

ObjectMapper mapper = new ObjectMapper();

String json =
"{\"name\":\"Kim\",\"age\":30}";

User user =
mapper.readValue(json, User.class);

System.out.println(user.getName());

 

실행 결과

Kim

 

이 과정은 역직렬화(Deserialization)라고 합니다.

즉,

• JSON → 객체
• 객체 → JSON

두 가지 모두 ObjectMapper 하나로 처리할 수 있습니다.

05. JSON 파일 읽기와 저장하기

이번 섹션에서는 문자열이 아닌 파일을 처리하는 방법을 알아보겠습니다.

✓ JSON 파일 읽기

 

ObjectMapper mapper = new ObjectMapper();

User user =
mapper.readValue(
new File("user.json"),
User.class
);

 

JSON 파일의 내용을 바로 객체로 읽을 수 있습니다.

✓ JSON 파일 저장

 

mapper.writeValue(
new File("user.json"),
user
);

 

객체 내용을 JSON 파일로 저장합니다.

별도의 문자열 처리 과정 없이 파일 입출력이 가능합니다.

06. List와 Map 변환하기

이번 섹션에서는 컬렉션 처리 방법을 살펴보겠습니다.

✓ List 변환

JSON 배열은 일반 객체와 조금 다르게 처리해야 합니다.

 

List<User> users =
mapper.readValue(
json,
new TypeReference<List<User>>() {}
);

 

여기서 TypeReference를 사용하는 이유는 제네릭 타입 정보를 유지하기 위해서입니다.

✓ Map 변환

 

Map<String, Object> map =
mapper.readValue(
json,
new TypeReference<Map<String,Object>>() {}
);

 

정해진 DTO가 없는 경우에는 Map으로 받아 처리하는 방법도 자주 사용됩니다.

07. JSON을 보기 좋게 출력하기

이번 섹션에서는 사람이 읽기 쉬운 JSON을 만드는 방법을 알아보겠습니다.

✓ Pretty Print

기본 JSON은 한 줄로 출력됩니다.

읽기 쉽게 출력하려면 다음과 같이 작성합니다.

 

String json =
mapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(user);

 

출력 예시는 다음과 같습니다.

 

{
  "name" : "Kim",
  "age" : 30
}

 

디버깅이나 로그를 확인할 때 매우 유용합니다.

08. ObjectMapper에서 자주 사용하는 기능

이번 섹션에서는 실무에서 많이 사용하는 기능을 정리해 보겠습니다.

✓ null 제외하기

 

mapper.setSerializationInclusion(
JsonInclude.Include.NON_NULL
);

 

null인 필드는 JSON에 포함되지 않습니다.

✓ 알 수 없는 필드 무시하기

 

mapper.configure(
DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,
false
);

 

JSON에 DTO에 없는 필드가 포함되어 있어도 예외가 발생하지 않습니다.

외부 API를 연동할 때 자주 사용하는 설정입니다.

✓ 날짜 처리하기

Java Time API를 사용하는 경우에는 날짜 모듈을 등록하는 방법을 많이 사용합니다.

실무에서는 날짜 형식과 타임존을 함께 고려하는 경우가 많으므로 프로젝트 요구 사항에 맞는 설정을 적용하는 것이 좋습니다.

09. Spring Boot에서 ObjectMapper는 어떻게 사용될까요?

이번 섹션에서는 Spring Boot와 ObjectMapper의 관계를 살펴보겠습니다.

✓ @RequestBody

 

@PostMapping
public User save(
@RequestBody User user
)

 

클라이언트가 JSON을 보내면

ObjectMapper가 자동으로 User 객체를 생성합니다.

✓ Response

 

@GetMapping
public User find()

 

객체를 반환하면

ObjectMapper가 JSON으로 자동 변환하여 응답합니다.

즉, 대부분의 경우 개발자가 ObjectMapper를 직접 호출하지 않아도 Spring Boot 내부에서 자동으로 동작합니다.

다만 JSON 파일 처리나 커스텀 변환이 필요한 경우에는 직접 ObjectMapper를 사용하는 경우가 많습니다.

10. 실무에서 많이 사용하는 활용 사례

이번 섹션에서는 실제 프로젝트에서 자주 사용하는 사례를 정리해 보겠습니다.

✓ API 응답 저장

외부 API에서 받은 JSON을 객체로 변환하여 데이터베이스에 저장할 수 있습니다.

✓ 로그 기록

객체를 JSON 문자열로 변환하여 로그에 기록하면 데이터 확인이 쉬워집니다.

✓ 테스트 데이터 생성

테스트 코드에서 객체를 JSON으로 변환하여 Mock 요청 데이터를 생성하는 경우가 많습니다.

✓ 설정 파일 처리

JSON 형식의 설정 파일을 읽어 객체로 변환하여 사용하는 프로젝트도 많이 있습니다.

11. Jackson ObjectMapper 사용 시 주의할 점

이번 섹션에서는 자주 발생하는 실수를 미리 살펴보겠습니다.

✓ 기본 생성자가 필요할 수 있습니다.

역직렬화를 위해서는 기본 생성자가 필요한 경우가 있습니다.

최근에는 Lombok이나 Jackson 어노테이션을 함께 사용하는 프로젝트도 많으므로 프로젝트 구조에 맞게 설정하는 것이 좋습니다.

✓ 예외 처리를 고려해야 합니다.

JSON 형식이 잘못되었거나 타입이 맞지 않으면 예외가 발생할 수 있습니다.

따라서 try-catch 또는 적절한 예외 처리를 함께 구현하는 것이 좋습니다.

✓ ObjectMapper를 반복 생성하지 않는 것이 좋습니다.

ObjectMapper는 재사용하도록 설계된 클래스입니다.

동일한 설정을 사용하는 경우에는 매번 새로 생성하기보다 재사용하는 방식이 일반적으로 권장됩니다.

12. 핵심 내용 정리

이번 섹션에서는 지금까지 살펴본 내용을 간단히 정리해 보겠습니다.

✓ 한눈에 정리

ObjectMapper의 대표 기능은 다음과 같습니다.

기능메서드

객체 → JSON	writeValueAsString()
JSON → 객체	readValue()
JSON 파일 읽기	readValue(File)
JSON 파일 저장	writeValue(File)
보기 좋은 JSON	writerWithDefaultPrettyPrinter()
List 변환	TypeReference 사용
Map 변환	TypeReference 사용

ObjectMapper는 단순히 JSON 문자열을 처리하는 도구를 넘어 Spring Boot 기반 API 개발에서 매우 중요한 역할을 담당합니다. 기본적인 직렬화와 역직렬화 방법을 익혀 두시면 REST API 개발, 외부 시스템 연동, 테스트 코드 작성 등 다양한 상황에서 효율적으로 활용하실 수 있습니다.

FAQ

Q1. Jackson ObjectMapper는 Spring Boot에서 기본으로 제공되나요?

Spring Boot에서는 일반적으로 Jackson이 기본 JSON 처리 라이브러리로 포함되어 있으며, HTTP 요청과 응답 처리에도 기본적으로 사용됩니다. 다만 프로젝트 구성에 따라 포함 여부가 달라질 수 있으므로 의존성을 확인하는 것이 좋습니다.

Q2. writeValueAsString()과 readValue()의 차이는 무엇인가요?

writeValueAsString()은 Java 객체를 JSON 문자열로 변환하는 메서드이며, readValue()는 JSON 문자열을 Java 객체로 변환하는 메서드입니다.

Q3. JSON 배열은 어떻게 변환하나요?

JSON 배열은 List와 같은 제네릭 타입으로 변환할 때 TypeReference를 함께 사용하는 방법이 일반적입니다.

Q4. ObjectMapper를 매번 생성해도 되나요?

기술적으로는 가능하지만, 동일한 설정을 사용하는 경우에는 ObjectMapper를 재사용하는 방식이 일반적으로 권장됩니다.

Q5. Gson과 Jackson의 차이는 무엇인가요?

두 라이브러리 모두 JSON 처리를 지원하지만, Spring Boot에서는 Jackson이 기본으로 사용되는 경우가 많습니다. 프로젝트 환경과 요구 사항에 따라 적합한 라이브러리를 선택하시면 됩니다.

관련글

• Spring Boot JSON 데이터 처리 과정 완벽 이해하기
• 시퀀스 다이어그램 그리는 법, diagrams.net 실전 예제
• JAVA Jackson 역직렬화 오류가 발생하는 원인과 해결 방법
• 워드프레스 Rank Math SEO 총정리｜설치부터 검색 노출 설정까지
• Spring Boot Lombok 실무 사용법: 설치부터 Annotation 적용과 오류 해결까지
• 전자서명 로그인 원리 완벽 정리: tokenId는 어디에 저장되고 공개키는 어떻게 사용될까?