jackson-time-migration

name: jackson-time-migration description: Jackson + 자바 시간 API 통합 — Joda-Time(레거시)에서 java.time(JSR-310)으로의 마이그레이션, Spring Boot Jackson 시간 직렬화 설정, LocalDateTime/OffsetDateTime/ZonedDateTime/Instant 선택 기준, 타임존 처리, MyBatis 연동

Jackson + 자바 시간 API 마이그레이션

소스: https://github.com/FasterXML/jackson-modules-java8 | https://github.com/FasterXML/jackson-datatype-joda | https://github.com/JodaOrg/joda-time | https://blog.joda.org/2014/11/converting-from-joda-time-to-javatime.html | https://docs.spring.io/spring-boot/appendix/application-properties/index.html 검증일: 2026-04-22

주의: 이 문서는 Spring Boot 2.5 (Jackson 2.12.x 번들) + Joda-Time 2.10.10 레거시 환경 → Spring Boot 2.7/3.x (Jackson 2.13+ / 2.17+) + java.time 모던 환경으로의 전환을 전제로 합니다. 핵심 API는 Jackson 2.5 이후 안정적이므로 2.12 ~ 2.21 범위에서 동일하게 동작합니다.

1. 왜 Joda-Time에서 java.time으로 가야 하는가

Joda-Time은 Java 7 이전 표준 날짜/시간 API의 결함을 보완하기 위해 나온 사실상의 표준이었지만, Java SE 8부터 JSR-310 (java.time) 이 JDK에 정식 편입되면서 역할을 마쳤습니다.

Joda-Time 프로젝트 공식 입장 (joda-time/README):

• "Joda-time is no longer in active development except to keep timezone data up to date."
• "From Java SE 8 onwards, users are asked to migrate to java.time (JSR-310) — a core part of the JDK which replaces this project."

참고: JSR-310 사양 자체가 Joda-Time 저자인 Stephen Colebourne이 이끌었고, 설계 개선(불변성 강화, 엄격한 null 처리, 캘린더 시스템 명확화)이 반영되었습니다.

모던 Java에서 Joda-Time을 권장하지 않는 이유:

결론: 신규 코드는 무조건 java.time. 레거시 코드는 점진적 전환.

2. 레거시 환경: Spring Boot 2.5 + Joda-Time 2.10.10

2-1. 의존성

<!-- pom.xml -->
<dependencies>
    <!-- Joda-Time 본체 -->
    <dependency>
        <groupId>joda-time</groupId>
        <artifactId>joda-time</artifactId>
        <version>2.10.10</version>
    </dependency>

    <!-- Jackson ↔ Joda 연동 모듈 -->
    <dependency>
        <groupId>com.fasterxml.jackson.datatype</groupId>
        <artifactId>jackson-datatype-joda</artifactId>
        <!-- Spring Boot 2.5의 Jackson 버전(2.12.x)에 맞춤 -->
    </dependency>
</dependencies>

Spring Boot 2.5는 Jackson 2.12.x를 번들하므로 jackson-datatype-joda 버전을 직접 지정하지 않고 spring-boot-dependencies의 BOM을 따르는 편이 안전합니다.

2-2. JodaModule 등록

Spring Boot의 기본 ObjectMapper를 사용한다면 spring-boot-starter-json이 클래스패스의 Jackson 모듈을 자동 탐지하므로 jackson-datatype-joda를 의존성에 추가하는 것만으로 자동 등록됩니다.

커스텀 ObjectMapper를 쓸 때는 명시 등록:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.datatype.joda.JodaModule;

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new JodaModule())
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);   // ISO-8601 문자열로

또는 Jackson 3 권장 스타일:

ObjectMapper mapper = JsonMapper.builder()
    .addModule(new JodaModule())
    .build();

2-3. 직렬화 포맷 예시

public class Event {
    private org.joda.time.DateTime  startAt;     // 시간대 포함
    private org.joda.time.LocalDate eventDate;   // 날짜만
    private org.joda.time.LocalTime eventTime;   // 시간만
    // getters/setters
}

WRITE_DATES_AS_TIMESTAMPS를 disable한 상태 기준 JSON:

{
  "startAt":   "2026-04-22T10:30:00.000+09:00",
  "eventDate": "2026-04-22",
  "eventTime": "10:30:00.000"
}

2-4. 개별 필드 포맷 지정

import com.fasterxml.jackson.annotation.JsonFormat;

public class Event {
    @JsonFormat(shape = JsonFormat.Shape.STRING,
                pattern = "yyyy-MM-dd HH:mm:ss",
                timezone = "Asia/Seoul")
    private DateTime startAt;
}

주의: @JsonFormat(pattern=...)은 Joda 모듈에서도 동작하지만, 타임존 정보가 누락된 패턴을 쓰면 왕복 시 정보 손실이 발생합니다. 가능하면 ISO-8601 기본 포맷 유지.

3. 모던 환경: Spring Boot + java.time (JSR-310)

3-1. 의존성 (Spring Boot 자동 포함)

<!-- spring-boot-starter-json 또는 spring-boot-starter-web을 쓰면 자동 포함 -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

Spring Boot 2.2+ 이후는 spring-boot-starter-json에 jackson-datatype-jsr310이 포함되어 있으며, 자동 설정이 JavaTimeModule을 기본 ObjectMapper에 등록합니다.

3-2. 기본 ObjectMapper 사용 시 (권장)

추가 설정 없이 LocalDateTime, OffsetDateTime, ZonedDateTime, Instant 등이 모두 직렬화/역직렬화됩니다.

public class EventDto {
    private java.time.OffsetDateTime startAt;
    private java.time.LocalDate      eventDate;
    private java.time.LocalTime      eventTime;
    private java.time.Instant        createdAt;
}

3-3. 커스텀 ObjectMapper 사용 시

커스텀 빈을 등록하면 자동 설정이 꺼지므로 직접 모듈을 등록해야 합니다.

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

@Bean
public ObjectMapper objectMapper() {
    return new ObjectMapper()
        .registerModule(new JavaTimeModule())
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
}

주의: 예전 JSR310Module 클래스는 deprecated 입니다. 반드시 JavaTimeModule을 사용하세요. 신규 Jackson 3.x에서는 jsr310 기능이 코어로 통합되었습니다.

3-4. application.yml 전역 설정

spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false     # ISO-8601 문자열로 직렬화
      write-dates-with-zone-id: false      # 존 ID 출력 억제
    time-zone: Asia/Seoul                  # Jackson 기본 타임존
    date-format: "yyyy-MM-dd'T'HH:mm:ssXXX"  # java.util.Date에만 적용. java.time에는 @JsonFormat 사용

핵심: spring.jackson.serialization.write-dates-as-timestamps: false가 없으면 숫자 epoch로 직렬화됩니다. 팀 표준으로 설정 파일에 박아두세요.

주의: spring.jackson.date-format 프로퍼티는 java.util.Date에만 적용되고, java.time.* 타입에는 영향을 주지 않습니다. java.time 타입의 포맷을 제어하려면 @JsonFormat 또는 커스텀 Serializer를 사용하세요.

3-5. 개별 필드 포맷 지정

import com.fasterxml.jackson.annotation.JsonFormat;

public class EventDto {
    @JsonFormat(shape = JsonFormat.Shape.STRING,
                pattern = "yyyy-MM-dd'T'HH:mm:ssXXX")
    private OffsetDateTime startAt;

    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
    private LocalDate eventDate;
}

패턴 기호:

• XXX — ISO-8601 오프셋 (+09:00)
• X — +09 (시간 단위)
• Z — RFC 822 (+0900)
• VV — 존 ID (Asia/Seoul)

4. LocalDateTime vs OffsetDateTime vs ZonedDateTime vs Instant

선택 결정 트리

서버가 "지금 이 순간"을 기록하고 싶다
  → Instant

UI 또는 리포트용 "연/월/일 시:분"이 필요하고 타임존이 무의미하다
  → LocalDateTime (주의: DB에 저장하거나 API로 내보낼 때는 타임존 의미가 사라짐)

DB에 타임존 확정된 시각을 저장하거나, API로 시각을 주고받는다
  → OffsetDateTime  (권장 — 왕복 시 동일 시점 보장)

미래 시각을 특정 지역 기준으로 예약 (DST 전환 반영 필요)
예: "서울 시간 2026-10-25 02:30에 실행"
  → ZonedDateTime

주요 주의사항

5. 타임존 처리 원칙 — "UTC 저장 + 렌더링 시점 변환"

표준 흐름

[사용자 입력 / 이벤트 발생]
       ↓
[서비스 레이어: OffsetDateTime 또는 Instant로 변환]
       ↓
[DB: UTC 기준 저장 (timestamptz)]
       ↓
[API 응답: OffsetDateTime ISO-8601 문자열로 직렬화]
       ↓
[클라이언트: 사용자 로케일 기준 렌더링]

원칙:

1. 서버 기본 타임존에 의존하지 말 것 — ZoneId.systemDefault()는 배포 환경마다 다르다
2. DB 컬럼은 UTC 기준 — PostgreSQL timestamptz, MySQL TIMESTAMP(내부 UTC)
3. API 전송은 ISO-8601 + 오프셋 포함 — 수신 측이 독립적으로 해석 가능
4. 변환은 렌더링 시점 — 비즈니스 로직은 Instant/OffsetDateTime으로 처리

JVM 기본 타임존 UTC 고정 (권장)

# 배포 환경
java -Duser.timezone=UTC -jar app.jar

또는 Spring Boot 초기화 시:

@PostConstruct
public void init() {
    TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
}

Jackson 타임존 설정

spring:
  jackson:
    time-zone: UTC    # 또는 Asia/Seoul — 팀 규칙으로 고정

주의: spring.jackson.time-zone은 Jackson이 Date, Calendar 같은 레거시 타입을 직렬화할 때의 표시 타임존입니다. OffsetDateTime/ZonedDateTime은 자체 오프셋/존을 그대로 직렬화하므로 이 설정의 영향을 덜 받습니다.

6. Joda-Time → java.time 타입 매핑 표

자주 쓰이는 변환 코드

// Joda DateTime → java.time ZonedDateTime
org.joda.time.DateTime joda = ...;
java.time.ZonedDateTime modern = java.time.ZonedDateTime.ofInstant(
    java.time.Instant.ofEpochMilli(joda.getMillis()),
    java.time.ZoneId.of(joda.getZone().getID())
);

// Joda DateTime → java.time OffsetDateTime (DB/API 전송용)
java.time.OffsetDateTime modern2 = java.time.OffsetDateTime.ofInstant(
    java.time.Instant.ofEpochMilli(joda.getMillis()),
    java.time.ZoneId.of(joda.getZone().getID())
);

// java.time Instant → Joda DateTime (역방향, 과도기용)
java.time.Instant instant = ...;
org.joda.time.DateTime joda2 = new org.joda.time.DateTime(instant.toEpochMilli());

주의: joda.getZone().getID() 결과는 대부분 java.time.ZoneId에 호환되지만, 오래된 타임존 별칭(deprecated alias)은 다를 수 있습니다. ZoneId.of(..., ZoneId.SHORT_IDS) 또는 별도 매핑 테이블을 고려하세요.

Period 의미 차이 (함정)

Joda의 시간 단위 Period를 그대로 java.time.Period로 바꾸면 시/분/초 정보가 유실됩니다. 시간 단위는 java.time.Duration으로 분리해야 합니다.

7. 마이그레이션 절차 (점진적)

대규모 코드베이스를 한 번에 교체하면 리스크가 크므로 단계별 병존 전략을 권장합니다.

단계 0: 준비

• 현재 코드 Joda 사용처 전수 조사 (grep -r "org.joda.time")
• Jackson 설정 스냅샷 (spring.jackson.*) 기록
• 기존 JSON 응답 포맷 샘플 저장 (회귀 테스트 기준)

단계 1: 의존성 병존

<dependencies>
    <!-- 기존 Joda 유지 -->
    <dependency>
        <groupId>joda-time</groupId>
        <artifactId>joda-time</artifactId>
        <version>2.10.10</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.datatype</groupId>
        <artifactId>jackson-datatype-joda</artifactId>
    </dependency>

    <!-- java.time 모듈 추가 -->
    <dependency>
        <groupId>com.fasterxml.jackson.datatype</groupId>
        <artifactId>jackson-datatype-jsr310</artifactId>
    </dependency>
</dependencies>

두 모듈을 같은 ObjectMapper에 등록:

@Configuration
public class JacksonConfig {
    @Bean
    public Jackson2ObjectMapperBuilderCustomizer customizer() {
        return builder -> builder
            .modulesToInstall(new JodaModule(), new JavaTimeModule())
            .featuresToDisable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
    }
}

이 시점에 신규 코드는 java.time, 기존 코드는 Joda로 작성 가능한 상태가 됩니다.

단계 2: 도메인별 점진 전환

• 경계 계층(Controller DTO, DB Entity)부터 전환
• 전환 단위: 도메인 모듈 또는 테이블 단위 (하루 안에 완료 가능한 크기)
• 전환 시 기존 JSON 포맷과 새 포맷을 통합 테스트로 비교

단계 3: 경계 어댑터

전환 완료 전까지 Joda ↔ java.time 변환 어댑터를 유틸리티로 유지:

public final class TimeAdapters {
    public static java.time.OffsetDateTime toOffsetDateTime(org.joda.time.DateTime joda) {
        if (joda == null) return null;
        return java.time.OffsetDateTime.ofInstant(
            java.time.Instant.ofEpochMilli(joda.getMillis()),
            java.time.ZoneId.of(joda.getZone().getID())
        );
    }
    public static org.joda.time.DateTime toJoda(java.time.OffsetDateTime modern) {
        if (modern == null) return null;
        return new org.joda.time.DateTime(
            modern.toInstant().toEpochMilli(),
            org.joda.time.DateTimeZone.forID(modern.getOffset().getId())
        );
    }
}

단계 4: Joda 제거

• grep -r "org.joda.time" 0건 확인
• joda-time, jackson-datatype-joda 의존성 제거
• JodaModule 등록 제거
• 회귀 테스트 전체 실행 (API 응답 포맷, DB 왕복, 타임존 테스트)

검증 포인트 (단계마다)

• JSON 응답의 시간 필드 포맷이 기존과 동일한가
• DB에 저장된 시각이 기존과 동일한 시점을 가리키는가
• DST 전환 시점을 포함한 테스트 케이스 통과
• 클라이언트 코드가 새 포맷을 파싱할 수 있는가

상세 레퍼런스 (예제·고급 패턴·흔한 실수) → references/REFERENCE.md