타임존·국제화 처리 베스트 프랙티스

// ❌ 위험: LocalDateTime은 타임존 정보가 없다
LocalDateTime now = LocalDateTime.now(); // 서버 타임존에 암묵적 의존
entity.setCreatedAt(now);

// ✅ 안전: Instant로 절대 시각을 저장
Instant now = Instant.now();
entity.setCreatedAt(now);

"이 값은 전 세계 어디서든 같은 순간을 가리키나?"
├─ Yes → Instant / OffsetDateTime
│         (이벤트 발생 시각, 결제 시각, 로그 타임스탬프)
└─ No  → "사용자의 '달력 위 날짜/시간'이 중요한가?"
         ├─ Yes → ZonedDateTime / LocalDateTime + ZoneId
         │         (생일, 예약 시각, "매일 9시 알림")
         └─ No  → LocalDate / LocalTime
                   (공휴일, 영업시간)

// Application.java — JVM 타임존 고정
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        TimeZone.setDefault(TimeZone.getTimeZone("UTC"));
        SpringApplication.run(Application.class, args);
    }
}

# application.yml — Jackson 직렬화 설정
spring:
  jackson:
    time-zone: UTC
    date-format: "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
    serialization:
      write-dates-as-timestamps: false

-- DB 세션 타임존 확인/고정
SHOW timezone;  -- 'UTC'여야 안전
SET timezone = 'UTC';

-- 테이블 설계: TIMESTAMPTZ 사용
CREATE TABLE orders (
    id          BIGSERIAL PRIMARY KEY,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),  -- UTC 저장
    user_tz     TEXT NOT NULL DEFAULT 'Asia/Seoul'    -- 표시용 타임존 별도 저장
);

-- 조회 시 사용자 타임존 변환
SELECT created_at AT TIME ZONE user_tz AS local_created_at
FROM orders WHERE id = 1;

@Entity
public class Order {
    @Column(columnDefinition = "TIMESTAMPTZ")
    private Instant createdAt;  // ✅ Instant 사용

    @Column
    private String userTimezone; // "Asia/Seoul"

    // 표시용 변환 메서드
    public ZonedDateTime getLocalCreatedAt() {
        return createdAt.atZone(ZoneId.of(userTimezone));
    }
}

// 미국 동부: 2025-03-09 02:00 → 03:00 (Spring Forward)
ZoneId eastern = ZoneId.of("America/New_York");

// 02:30은 존재하지 않는다
LocalDateTime gapTime = LocalDateTime.of(2025, 3, 9, 2, 30);
ZonedDateTime resolved = gapTime.atZone(eastern);
// → 2025-03-09T03:30-04:00 (자동으로 03:30으로 밀림)

System.out.println(resolved); // 의도와 다를 수 있음!

// 미국 동부: 2025-11-02 02:00 → 01:00 (Fall Back)
LocalDateTime overlapTime = LocalDateTime.of(2025, 11, 2, 1, 30);

// 어느 01:30인지 명시해야 한다
ZonedDateTime earlier = overlapTime.atZone(eastern)
    .withEarlierOffsetAtOverlap();  // EDT (-04:00)
ZonedDateTime later = overlapTime.atZone(eastern)
    .withLaterOffsetAtOverlap();    // EST (-05:00)

// 두 값의 Instant는 1시간 차이!
Duration gap = Duration.between(earlier.toInstant(), later.toInstant());
// → PT1H

// Spring @Scheduled에서 타임존 명시
@Scheduled(cron = "0 0 9 * * *", zone = "Asia/Seoul")
public void morningNotification() {
    // 서울 기준 매일 9시 — DST 없는 지역이라 안전
    // 미국 대상이면 zone="America/New_York"으로 DST 자동 처리
}

// ❌ 위험: 항상 24시간을 더한다
Instant tomorrow = Instant.now().plus(Duration.ofHours(24));

// ✅ 안전: 달력 기준 "내일 같은 시각"
ZonedDateTime now = ZonedDateTime.now(ZoneId.of("America/New_York"));
ZonedDateTime tomorrowLocal = now.plusDays(1); // DST 고려됨
// DST 전환일에는 23시간 또는 25시간 뒤가 될 수 있음

@GetMapping("/orders/today")
public List<Order> getTodayOrders(
        @RequestHeader("X-User-Timezone") String timezone) {

    ZoneId zone = ZoneId.of(timezone); // "Asia/Seoul"
    ZonedDateTime startOfDay = LocalDate.now(zone)
            .atStartOfDay(zone);
    ZonedDateTime endOfDay = startOfDay.plusDays(1);

    // UTC Instant로 변환하여 DB 조회
    return orderRepository.findByCreatedAtBetween(
            startOfDay.toInstant(),
            endOfDay.toInstant()
    );
}

// MessageConfig.java
@Configuration
public class MessageConfig {
    @Bean
    public MessageSource messageSource() {
        ReloadableResourceBundleMessageSource source =
            new ReloadableResourceBundleMessageSource();
        source.setBasename("classpath:messages");
        source.setDefaultEncoding("UTF-8");
        source.setCacheSeconds(3600);
        return source;
    }

    @Bean
    public LocaleResolver localeResolver() {
        AcceptHeaderLocaleResolver resolver =
            new AcceptHeaderLocaleResolver();
        resolver.setDefaultLocale(Locale.KOREAN);
        resolver.setSupportedLocales(
            List.of(Locale.KOREAN, Locale.ENGLISH, Locale.JAPANESE));
        return resolver;
    }
}

# messages_ko.properties
order.confirmation=주문이 완료되었습니다. 주문번호: {0}
order.amount=결제 금액: {0,number,currency}

# messages_en.properties
order.confirmation=Order confirmed. Order number: {0}
order.amount=Payment amount: {0,number,currency}

// API 응답: raw value + currency code
@JsonProperty("amount")
private BigDecimal amount;        // 15000.00

@JsonProperty("currency")
private String currency;          // "KRW"

// 서버 사이드 렌더링이 필요한 경우 (이메일/푸시)
public String formatAmount(Locale locale) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance(locale);
    formatter.setCurrency(Currency.getInstance(currency));
    return formatter.format(amount);
    // ko: ₩15,000  /  en-US: ₩15,000.00
}

// 서비스에서 Clock 주입
@Service
public class OrderService {
    private final Clock clock;

    public OrderService(Clock clock) {
        this.clock = clock;
    }

    public Order createOrder(OrderRequest request) {
        Order order = new Order();
        order.setCreatedAt(Instant.now(clock));  // 테스트에서 시간 고정 가능
        return orderRepository.save(order);
    }
}

// 프로덕션 설정
@Bean
public Clock clock() {
    return Clock.systemUTC();
}

// 테스트에서 시간 고정
@Test
void 주문_생성시_DST_전환일에도_UTC_저장() {
    // DST 전환 시점을 고정
    Clock fixed = Clock.fixed(
        ZonedDateTime.of(2025, 3, 9, 2, 30, 0, 0,
            ZoneId.of("America/New_York"))
            .toInstant(),
        ZoneId.of("UTC")
    );

    OrderService service = new OrderService(fixed);
    Order order = service.createOrder(new OrderRequest());

    // UTC로 정확히 저장되었는지 검증
    assertThat(order.getCreatedAt())
        .isEqualTo(Instant.parse("2025-03-09T07:30:00Z"));
}