ZonedDateTime, Instant, praca ze strefami czasowymi

1. Pojęcie strefy czasowej

Na świecie istnieje wiele stref czasowych: gdy w Mińsku jest południe, w Nowym Jorku dopiero poranek, a w Tokio już wieczór. Jeśli przechowujesz datę i czas bez uwzględnienia strefy czasowej, łatwo o zamieszanie: na przykład, jeśli twój serwer jest w Niemczech, a użytkownik — we Władywostoku, zapis czasu "2025-06-01 12:00" będzie oznaczał coś zupełnie innego dla każdego z nich.

Strefa czasowa (timezone) — to zestaw reguł określających, ile czasu należy dodać lub odjąć od czasu Greenwich (UTC), aby uzyskać „lokalny” czas dla konkretnego regionu.

W Javie do pracy ze strefami czasowymi używa się klasy ZoneId. Oto kilka przykładów identyfikatorów stref:

• "Europe/Minsk"
• "UTC"
• "America/New_York"
• "Asia/Tokyo"

Dlaczego to ważne?

• Poprawne wyświetlanie czasu dla użytkowników z różnych krajów.
• Prawidłowy zapis czasu zdarzeń (np. logowanie, rezerwacja biletów, terminy).
• Uwzględnienie zmiany czasu na letni/zimowy (dzięki, Europo!).

2. ZonedDateTime — data i czas z uwzględnieniem strefy czasowej

ZonedDateTime — to klasa, która przechowuje datę, czas oraz informację o strefie czasowej. To jak LocalDateTime, tylko dodatkowo „wie”, w jakim regionie się znajduje.

Tworzenie ZonedDateTime

Bieżąca data i czas w systemowej strefie czasowej

import java.time.ZonedDateTime;

ZonedDateTime now = ZonedDateTime.now();
System.out.println(now); // Na przykład: 2025-06-01T15:30:00+03:00[Europe/Minsk]

Czas w konkretnej strefie czasowej

import java.time.ZoneId;

ZonedDateTime MinskTime = ZonedDateTime.now(ZoneId.of("Europe/Minsk"));
ZonedDateTime newYorkTime = ZonedDateTime.now(ZoneId.of("America/New_York"));

System.out.println("Mińsk: " + MinskTime);
System.out.println("Nowy Jork: " + newYorkTime);

Tworzenie z LocalDateTime

import java.time.LocalDateTime;

LocalDateTime meeting = LocalDateTime.of(2025, 6, 1, 18, 0);
ZonedDateTime meetingInMinsk = meeting.atZone(ZoneId.of("Europe/Minsk"));
System.out.println(meetingInMinsk); // 2025-06-01T18:00+03:00[Europe/Minsk]

Pobieranie i ustawianie strefy czasowej

ZoneId tokyoZone = ZoneId.of("Asia/Tokyo");
ZonedDateTime tokyoTime = ZonedDateTime.now(tokyoZone);
System.out.println("Tokio: " + tokyoTime);

Konwersja między strefami: withZoneSameInstant()

Czasem trzeba sprawdzić, jak to samo zdarzenie wygląda w innej strefie. Do tego używamy withZoneSameInstant():

ZonedDateTime MinskMeeting = ZonedDateTime.of(2025, 6, 1, 18, 0, 0, 0, ZoneId.of("Europe/Minsk"));
ZonedDateTime newYorkMeeting = MinskMeeting.withZoneSameInstant(ZoneId.of("America/New_York"));

System.out.println("Czas spotkania w Mińsku: " + MinskMeeting);
System.out.println("To samo zdarzenie w Nowym Jorku: " + newYorkMeeting);

Uwaga: withZoneSameInstant() przekłada czas tak, aby odpowiadał temu samemu momentowi w innej strefie. Jeśli użyjesz withZoneSameLocal(), to data i czas pozostaną takie same, a strefa się zmieni — to niemal zawsze błąd!

3. Instant — absolutny punkt w czasie

Instant — to klasa reprezentująca absolutny moment w czasie, niezależnie od strefy czasowej. Technicznie to liczba sekund i nanosekund, które upłynęły od 1 stycznia 1970 roku według Greenwich (UTC). Gdyby czas miał paszport — Instant byłby jego numerem.

Tworzenie Instant

import java.time.Instant;

Instant now = Instant.now();
System.out.println(now); // Na przykład: 2025-06-01T12:30:00.123Z

Zwróć uwagę na literę Z — oznacza „Zulu time”, czyli UTC.

Tworzenie z sekund od epoki Uniksa

Instant fromEpoch = Instant.ofEpochSecond(1685616000L);
System.out.println(fromEpoch); // 2023-06-01T00:00:00Z

Konwersja Instant ↔ ZonedDateTime/LocalDateTime

Z ZonedDateTime do Instant

ZonedDateTime zoned = ZonedDateTime.now();
Instant instant = zoned.toInstant();
System.out.println(instant);

Z Instant do ZonedDateTime

ZoneId zone = ZoneId.of("Europe/Minsk");
ZonedDateTime fromInstant = Instant.now().atZone(zone);
System.out.println(fromInstant);

Z Instant do LocalDateTime

import java.time.LocalDateTime;
import java.time.Instant;
import java.time.ZoneId;

LocalDateTime local = LocalDateTime.ofInstant(Instant.now(), ZoneId.of("Europe/Minsk"));
System.out.println(local);

4. Praktyka: bieżący czas w różnych strefach, konwersje między strefami

Pobieranie bieżącego czasu w różnych strefach czasowych

Zróbmy mini-aplikację, która pokazuje bieżący czas w Mińsku, Nowym Jorku i Tokio:

import java.time.ZonedDateTime;
import java.time.ZoneId;

public class TimeZonesDemo {
    public static void main(String[] args) {
        ZonedDateTime Minsk = ZonedDateTime.now(ZoneId.of("Europe/Minsk"));
        ZonedDateTime newYork = ZonedDateTime.now(ZoneId.of("America/New_York"));
        ZonedDateTime tokyo = ZonedDateTime.now(ZoneId.of("Asia/Tokyo"));

        System.out.println("Mińsk:    " + Minsk);
        System.out.println("Nowy Jork:  " + newYork);
        System.out.println("Tokio:     " + tokyo);
    }
}

Konwersja czasu między strefami

Załóżmy, że masz zdarzenie wyznaczone na 18:00 w Mińsku. Jak sprawdzić, która to będzie godzina w Nowym Jorku i Tokio?

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;

public class MeetingTime {
    public static void main(String[] args) {
        LocalDateTime eventTime = LocalDateTime.of(2025, 6, 1, 18, 0);
        ZonedDateTime minskEvent = eventTime.atZone(ZoneId.of("Europe/Minsk"));

        ZonedDateTime newYorkEvent = minskEvent.withZoneSameInstant(ZoneId.of("America/New_York"));
        ZonedDateTime tokyoEvent = minskEvent.withZoneSameInstant(ZoneId.of("Asia/Tokyo"));

        System.out.println("Spotkanie w Mińsku:   " + minskEvent);
        System.out.println("W Nowym Jorku:        " + newYorkEvent);
        System.out.println("W Tokio:              " + tokyoEvent);
    }
}

Konwersja LocalDateTime do ZonedDateTime i z powrotem

Local → Zoned:

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZonedDateTime;

LocalDateTime localTime = LocalDateTime.of(2025, 6, 1, 14, 0);
ZonedDateTime zonedTime = localTime.atZone(ZoneId.of("Europe/Minsk"));
System.out.println(zonedTime);

Zoned → Local:

LocalDateTime extracted = zonedTime.toLocalDateTime();
System.out.println(extracted);

5. Ważne uwagi i niuanse

Dlaczego nie należy przechowywać wyłącznie LocalDateTime

LocalDateTime — to po prostu data i czas bez strefy czasowej. Dla większości logik biznesowych to za mało! Na przykład, jeśli przechowujesz "2025-06-01 12:00" jako LocalDateTime, to dla użytkownika z Mińska i z Nowego Jorku będą to zupełnie różne momenty w rzeczywistym czasie.

Zawsze przechowuj czas absolutny (np. Instant) albo czas ze strefą (ZonedDateTime), jeśli zdarzenie faktycznie jest związane z konkretną strefą. LocalDateTime jest dobry tylko wtedy, gdy pracujesz z „pływającymi” datami (np. urodziny bez uwzględniania pory dnia i strefy).

Problemy ze zmianą czasu na letni/zimowy

Strefy czasowe — to nie tylko przesunięcie względem UTC, ale też reguły przechodzenia na czas letni/zimowy. Na przykład w niektórych krajach w określonym dniu czas przestawia się o godzinę do przodu lub wstecz — i jeśli przechowujesz tylko LocalDateTime, nie dowiesz się, czy taka chwila w ogóle istniała.

Przykład „dziury w czasie”:

• W USA w marcu o 2:00 w nocy zegary przestawia się na 3:00.
• Czas "2025-03-10 02:30" w Nowym Jorku nie istniał!

Pracując z ZonedDateTime, jesteś chroniony przed takimi niespodziankami: biblioteka sama sprawdzi poprawność czasu.

Schemat: jak są powiązane LocalDateTime, ZonedDateTime, Instant

graph TD
    A["LocalDateTime 
 (data + czas, bez strefy)"] -->|+ ZoneId| B["ZonedDateTime
(data + czas + strefa)"]
    B -->|"toInstant()"| C["Instant
(absolutny czas, UTC)"]
    C -->|"atZone(ZoneId)"| B
    B -->|"toLocalDateTime()"| A

6. Typowe błędy przy pracy z ZonedDateTime i Instant

Błąd nr 1: Używanie LocalDateTime dla globalnych zdarzeń.
Jeśli przechowujesz datę i czas spotkania użytkowników z różnych krajów jako LocalDateTime, to każdy zobaczy swoje „12:00”, chociaż mowa o różnych momentach w czasie. Dla globalnych zdarzeń używaj ZonedDateTime albo Instant.

Błąd nr 2: Ignorowanie strefy czasowej przy parsowaniu ciągu znaków.
Jeśli sparsujesz ciąg "2025-06-01T12:00:00" bez podania strefy, otrzymasz LocalDateTime, a nie ZonedDateTime. Aby uzyskać ZonedDateTime, używaj łańcuchów ze strefą lub jawnie ją dodawaj.

Błąd nr 3: Nieprawidłowa konwersja między strefami.
Użycie withZoneSameLocal() zamiast withZoneSameInstant() może prowadzić do nieprawidłowego czasu. Zawsze używaj withZoneSameInstant(), jeśli chcesz otrzymać ten sam moment w innej strefie.

Błąd nr 4: Nieuwzględnianie zmiany czasu na letni/zimowy.
Jeśli planujesz zdarzenia na granicy przejścia, koniecznie używaj ZonedDateTime i zaufaj bibliotece — zna wszystkie przejścia i „dziury” w czasie.

Błąd nr 5: Porównywanie ZonedDateTime bez uwzględnienia strefy.
Dwa ZonedDateTime z różnymi strefami, ale takim samym lokalnym czasem, mogą reprezentować różne momenty w czasie. Do porównań używaj toInstant().