Jackson Timezone 직렬화가 되지 않던 문제 해결

[can019]

📝 작업 내용

• application.yml의 spring.jackson.time-zone 설정이 무시되는 문제 해결
• ObjectMapper를 Bean으로 등록해 UTC TimeZone 및 WRITE_DATES_AS_TIMESTAMPS 비활성화 적용
• Workflow 및 ExecutionLogDto에서 Instant 직렬화 시 Z(UTC) 표기가 누락되는 현상 수정
• 기존 application.yml 기반 설정 제거 후 Bean 설정으로 일원화

---

🔗 관련 이슈

• Closes [BUG] Spring에서 LocalDateTime을 사용하여 Timezone이 무시되는 버그 #204

---

💬 추가 요청사항

• 다른 모듈에서도 동일한 Instant 직렬화가 정상적으로 출력되는지 확인 부탁드립니다.

---

✅ 체크리스트

코드 품질

• 커밋 컨벤션 준수 (fix)
• 불필요한 코드/주석 제거

테스트

• 로컬 환경에서 Jackson 직렬화 결과에 Z(UTC) 포함 확인
• 기존 기능에 영향 없음 확인

배포 준비

• 환경변수 추가/변경사항 없음
• DB 마이그레이션 필요 없음
• 배포 시 주의사항 없음

[jihukimme]

시간 데이터를 String이 아닌 Instant로 처리해서 시간 관련 기능을 확장할 때 발생할 수 있는 버그를 사전에 방지한 것에 대해서 좋은 리팩토링 이었다고 생각합니다.

시간 데이터를 명확하고 표준화된 방식으로 처리

• String 타입의 문제점:

  • 모호함: "2025-09-26 15:30:00"과 같은 문자열은 타임존(Timezone) 정보가 없어, 어느 지역 기준의 시간인지 알 수 없습니다.
  • 계산의 어려움: 두 시간의 차이(duration)를 계산하려면 문자열을 날짜/시간 객체로 매번 파싱(Parsing)해야 해서 비효율적이고 오류가 발생하기 쉽습니다.
  • 형식 비일관성: "2025/09/26", "26-09-2025" 등 다양한 형식으로 데이터가 저장될 위험이 있습니다.

• Instant 타입의 장점:

  • 명확성: Instant는 UTC(협정 세계시)를 기준으로 하는, 시간대의 영향을 받지 않는 절대적인 '순간'을 표현합니다. 전 세계 어디서든 동일한 시점을 의미합니다.
  • 정확한 계산: 시간 차이를 나노초(nanosecond) 단위까지 정밀하게 계산할 수 있습니다.
  • 표준화: API 응답(JSON) 등에서 ISO 8601 형식(2025-09-26T06:30:00Z)으로 직렬화되어, 다른 시스템과 데이터를 주고받을 때 오해의 소지가 없습니다

[jihukimme]

Instant 타입과 같은 시간 데이터를 처리하는 타입에 대해서 인지하지 못하고 있었습니다. 해당 PR을 보고 시간 데이터를 처리하는 타입을 잘 처리해주어야 함을 알게 되었습니다.

[jihukimme]

Instant와 Timezone을 나누어 사용하는 이유는 데이터의 정확성과 시스템의 유연성을 모두 확보하기 위함이며, 이는 서버 개발의 표준적인 모범 사례입니다.

---

Instant vs. Timezone

구분 | Instant (언제) | Timezone (어디서) -- | -- | -- 핵심 개념 | 타임라인 위의 절대적인 한 순간 | 특정 지역의 시간을 정의하는 규칙 또는 오프셋 기준 | 항상 UTC (협정 세계시) | UTC로부터의 시간 차이 (예: +09:00) 표현 예시 | 2025-09-26T07:00:00Z | Asia/Seoul, KST 역할 | 기계가 이해하는 시간 (내부 처리용) | 사람이 이해하는 시간 (표시용)

왜 나누어서 사용해야 하는가?

서버는 전 세계 어디서든 동작할 수 있고, 사용자 또한 전 세계 어디서든 접속할 수 있습니다. 이때 시간 데이터를 모호하게 처리하면 심각한 문제가 발생할 수 있습니다.

1. 데이터 무결성 보장: 서버는 Instant를 사용

서버 내부, 특히 데이터베이스에 시간을 기록할 때는 전 세계적으로 동일한 절대적인 시점을 나타내는 Instant (UTC 기준)를 사용해야 합니다.

• 장점: 서울에 있는 서버가 기록한 Instant 값과, 나중에 미국에 있는 서버가 그 값을 읽었을 때, 두 서버는 완벽하게 동일한 물리적 순간을 이해하게 됩니다. 만약 "2025년 9월 26일 오후 4시"와 같이 지역 시간으로 저장했다면, 이것이 한국 시간인지 미국 시간인지 알 수 없어 데이터의 정합성이 깨집니다.

2. 유연한 표현: 사용자는 Timezone이 적용된 시간을 봄

사용자에게 시간을 보여줄 때는, 서버에 저장된 절대적인 Instant 값에 사용자의 지역 Timezone을 적용하여 변환한 후 보여줍니다.

• 장점: 한국에 있는 사용자는 "오후 4시"로 보고, 동시에 접속한 미국 사용자는 "오전 3시"로 보게 됩니다. 이처럼 단 하나의 Instant 데이터만으로 전 세계 모든 사용자에게 각자의 지역 시간에 맞는 올바른 정보를 제공할 수 있습니다.

코드 리뷰 관점에서의 결론

현재 프로젝트에서 TaskRun과 같은 도메인 모델에는 Instant를 사용하여 서버 내부의 데이터 정확성을 확보하고, TaskRunDto와 같은 DTO에서는 이를 String으로 변환하여 외부(클라이언트)에 명확한 정보를 제공하는 방식은, 이러한 역할과 책임을 완벽하게 분리한 매우 훌륭하고 표준적인 설계입니다.

[jihukimme]

전역 ObjectMapper를 Bean으로 등록하여 애플리케이션 전체의 JSON 직렬화/역직렬화 방식을 표준화한 것은 매우 훌륭한 설계입니다. 특히 시간(Time) 데이터를 UTC로 통일한 것은 분산 시스템에서 발생할 수 있는 수많은 버그를 사전에 방지하는 핵심적인 모범 사례입니다.

잘된 점 (Pros)

1. 중앙화된 시간 관리 (setTimeZone):

   • .setTimeZone(TimeZone.getTimeZone("UTC")) 설정을 통해, 애플리케이션의 모든 JSON 변환에서 시간을 UTC(협정 세계시) 기준으로 통일했습니다. 이는 서버의 위치나 설정에 관계없이 항상 일관된 시간 데이터를 보장하여, 타임존 관련 버그를 원천적으로 차단하는 가장 좋은 방법입니다.

2. Java 8 시간 API 지원 (JavaTimeModule):

   • .registerModule(new JavaTimeModule())을 통해 Instant, LocalDateTime 등 Java 8의 시간 타입을 Jackson이 올바르게 처리할 수 있도록 했습니다. 이는 최신 Java 개발 환경의 필수 설정입니다.

3. 가독성 높은 시간 포맷 (WRITE_DATES_AS_TIMESTAMPS):

   • .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS) 설정을 통해, 1727339859000과 같은 숫자 타임스탬프 대신, 사람이 읽기 쉬운 ISO 8601 형식(2025-09-26T09:17:39.000+00:00)의 문자열로 시간을 표현하도록 했습니다. 이는 API 응답을 디버깅하고 이해하는 데 큰 도움이 됩니다.

4. 전역 적용 (@Primary):

   • @Primary 어노테이션을 사용하여, 여기서 설정한 ObjectMapper가 Spring 컨테이너 내에서 기본값으로 사용되도록 했습니다. 이제 @RestController가 JSON 응답을 생성할 때 등 별도의 설정 없이도 이 Bean이 자동으로 사용되어 애플리케이션 전체의 동작 일관성을 보장합니다.

추가 제안 (고려 사항)

• API의 안정성을 더욱 높이고 싶다면, 역직렬화(JSON -> Java Object) 시 알 수 없는 필드가 있어도 에러를 발생시키지 않도록 아래 설정을 추가하는 것을 고려해볼 수 있습니다.

  .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)

결론적으로, 이 코드는 안정적이고 예측 가능한 데이터 처리를 위한 훌륭한 기반을 마련한 매우 잘 작성된 설정입니다.