Класс Java Instant | W3Docs Learn Java

Instant — это единственный момент на глобальной временной шкале, хранящийся как наносекунды с начала эпохи Unix (1970-01-01T00:00:00Z). У него нет временной зоны, нет календаря, нет понятия «какой сегодня день» — только счётчик. По своей природе этот счётчик измеряется в UTC, поэтому два значения Instant с разных машин в разных зонах можно сравнивать напрямую: то, у которого меньше число, является более ранним.

Это тип для машинных временных меток. Строки журнала. Временные метки сообщений. «Когда сервер получил запрос». Журналы аудита. Всё, что должно глобально сортироваться и никогда не должно быть неоднозначным с точки зрения того, какой день оно представляет — потому что здесь вообще нет «дня», только секунды.

Создание

Instant now    = Instant.now();                              // current moment, from System clock
Instant epoch  = Instant.EPOCH;                              // 1970-01-01T00:00:00Z
Instant max    = Instant.MAX;                                 // year +1000000000
Instant min    = Instant.MIN;                                 // year -1000000000

Instant fromS   = Instant.ofEpochSecond(1_700_000_000L);
Instant fromMs  = Instant.ofEpochMilli(1_700_000_000_000L);
Instant fromIso = Instant.parse("2025-11-04T19:30:00Z");     // ISO-8601, trailing Z is mandatory

Строковое представление заканчивается буквой Z (от «Zulu time» — военное обозначение UTC). Instant.parse("2025-11-04T19:30:00") (без Z) приводит к ошибке разбора — тип не будет угадывать, какую зону вы имели в виду.

Два фабричных метода, которые вы будете использовать чаще всего:

Instant.ofEpochSecond(epochSec);                              // long seconds, no nanos
Instant.ofEpochSecond(epochSec, nanos);                       // with sub-second resolution

Большинство внешних форматов временных меток (Unix time(2), syslog, JSON-поля created_at в виде целых чисел) представляют собой секунды или миллисекунды с начала эпохи. Фабричные методы ofEpochSecond / ofEpochMilli — стандартный мост к ним.

Разрешение

Instant обладает точностью до наносекунды (1 секунда = 1 000 000 000 нс). На большинстве систем нижележащие часы имеют меньшее разрешение — типично миллисекунду, на современном Linux — микросекунду. Instant.now() возвращает значение с доступным разрешением; неиспользуемые наносекунды равны нулю.

Методы доступа:

long seconds = inst.getEpochSecond();                         // long; can go past 2038
int nanos    = inst.getNano();                                // 0-999_999_999
long milli   = inst.toEpochMilli();                           // throws if out of long range

toEpochMilli — это потерянное преобразование: наносекунды обрезаются до миллисекунд. Для строк журнала и JSON-временных меток это обычно допустимо; для записей событий с высокой частотой используйте getEpochSecond + getNano раздельно.

Без календаря

Instant.getDayOfMonth() не существует. Так же как и getYear, getHour или любые другие методы доступа к календарю. Тип действительно не знает — календарная информация требует временной зоны, а у Instant её нет. Если вы хотите узнать «в какой час это произошло в Нью-Йорке», сначала нужно присвоить зону:

ZonedDateTime zdt = inst.atZone(ZoneId.of("America/New_York"));
int hour = zdt.getHour();
LocalDate date = zdt.toLocalDate();

atZone(zone) — это мост в обратном направлении от ZonedDateTime.toInstant(). Вместе они обеспечивают полный цикл преобразований: момент ↔ метка с зоной. Смотрите раздел Java ZonedDateTime для изучения календарной стороны этой пары.

Арифметика

Та же гибкая форма:

inst.plusSeconds(60);
inst.plusMillis(500);
inst.plusNanos(1_000_000);
inst.plus(Duration.ofMinutes(15));                            // any Duration

inst.minus(Duration.ofDays(1));                                // exactly 24h * 3600s

У Instant нет метода plusDays в календарном смысле. У него есть plus(amount, ChronoUnit), и ChronoUnit.DAYS работает, потому что JDK определяет сутки как ровно 24 часа * 3600 секунд для Instant. Это не то же самое, что календарные сутки при действии перехода на летнее время — именно поэтому Instant не претендует на роль одного из них.

inst.plus(1, ChronoUnit.DAYS);                                // exactly 86_400 seconds
inst.plus(7, ChronoUnit.DAYS);                                // exactly 604_800 seconds

Для операций в форме календаря («на один месяц позже в зоне пользователя») используйте ZonedDateTime:

Instant later = inst.atZone(zone).plusMonths(1).toInstant();

Сравнение

inst1.isBefore(inst2);
inst1.isAfter(inst2);
inst1.equals(inst2);
inst1.compareTo(inst2);

Instant реализует Comparable<Instant> с естественным порядком по секундам эпохи, а затем по наносекундам. equals прост: одинаковые секунды и одинаковые наносекунды.

Расстояние

Duration d = Duration.between(start, end);                     // a Duration
long millis = ChronoUnit.MILLIS.between(start, end);
long days = ChronoUnit.DAYS.between(start, end);               // 24h-equivalent days

Для машинных временных меток всё это точно — нет никакой неоднозначности календаря. ChronoUnit.MONTHS.between(start, end) для значений Instant выбрасывает исключение, потому что месяцы не имеют постоянной длины в секундах: зоны нет, и вычислитель не может определить, какой именно месяц содержит эти секунды. Это правильное поведение при ошибке.

Мост к `java.util.Date`

Старый код использует java.util.Date. Преобразования прямые:

Date legacy = Date.from(inst);                                 // Instant -> Date
Instant back = legacy.toInstant();                              // Date -> Instant

Date внутри является обёрткой вокруг long в миллисекундах от эпохи, поэтому двустороннее преобразование является без потерь с точностью до наносекунд (Date имеет точность до миллисекунды, Instant — до наносекунды). Глава Legacy Date подробно описывает процесс миграции.

Почему всё внутреннее должно быть `Instant`

Рекомендация, выкристаллизовавшаяся за десять лет использования java.time в промышленных приложениях:

Внутри используйте Instant. Хранение, сравнение, журналирование, временные метки сообщений, везде, где значение передаётся между машинами.
На границе — при отображении пользователю, при приёме пользовательского ввода — конвертируйте в ZonedDateTime или LocalDateTime, используя правильную зону для контекста.

Это разделяет «что реально произошло» и «как это помечено». Ошибка на границе (неправильная зона) оставляет внутренние значения корректными; ошибка в системе типов, позволяющая LocalDateTime течь внутренне, как правило, приводит к тому, что временные метки молча оказываются в разных зонах.

Рабочий пример: маленький журнал событий

Приведённая ниже программа записывает последовательность событий в виде Instant-значений, вычисляет длительности между событиями, демонстрирует граничное взаимодействие с календарём путём присвоения зоны для отображения, показывает мост к устаревшему типу Date и, наконец, иллюстрирует правило «без календаря», показывая, что ChronoUnit.MONTHS.between на двух Instant-значениях выбрасывает исключение.

java— editable, runs on the server

import java.time.*;
import java.time.temporal.ChronoUnit;
import java.util.Date;

public class InstantDemo {
  public static void main(String[] args) {
    // --- 1. Take a baseline instant ---
    Instant t0 = Instant.parse("2025-11-04T19:30:00Z");          // fixed for reproducibility
    System.out.println("t0 = " + t0
        + "  (epochSecond = " + t0.getEpochSecond() + ", nano = " + t0.getNano() + ")");

// --- 2. Build a synthetic event sequence ---
    Instant request    = t0;
    Instant dbQuery    = request.plus(Duration.ofMillis(120));
    Instant dbResponse = dbQuery.plus(Duration.ofMillis(45));
    Instant rendered   = dbResponse.plus(Duration.ofMillis(80));
    Instant responded  = rendered.plus(Duration.ofMillis(10));

System.out.println("\nevent stream (UTC instants):");
    System.out.println("  request    = " + request);
    System.out.println("  dbQuery    = " + dbQuery);
    System.out.println("  dbResponse = " + dbResponse);
    System.out.println("  rendered   = " + rendered);
    System.out.println("  responded  = " + responded);

// --- 3. Inter-event durations ---
    System.out.println("\ndurations:");
    System.out.println("  request -> dbQuery    = " + Duration.between(request, dbQuery).toMillis() + " ms");
    System.out.println("  db round trip         = " + Duration.between(dbQuery, dbResponse).toMillis() + " ms");
    System.out.println("  total request handled = " + Duration.between(request, responded).toMillis() + " ms");

// --- 4. Display in two zones ---
    System.out.println("\nsame instant, two zone labels:");
    System.out.println("  in New York   = " + responded.atZone(ZoneId.of("America/New_York")));
    System.out.println("  in Tokyo      = " + responded.atZone(ZoneId.of("Asia/Tokyo")));

// --- 5. Legacy Date bridge ---
    Date legacy = Date.from(responded);
    Instant back = legacy.toInstant();
    System.out.println("\nlegacy bridge:");
    System.out.println("  Instant -> Date -> Instant equal? " + responded.equals(back)
        + "  (modulo nanos; Date is millis only)");

// --- 6. No calendar on Instant — months throw ---
    Instant a = Instant.parse("2025-01-01T00:00:00Z");
    Instant b = Instant.parse("2025-04-01T00:00:00Z");
    System.out.println("\nChronoUnit.MONTHS.between on Instants:");
    try {
      long months = ChronoUnit.MONTHS.between(a, b);
      System.out.println("  (unexpected) months = " + months);
    } catch (Exception e) {
      System.out.println("  threw: " + e.getClass().getSimpleName() + " -- " + e.getMessage());
      System.out.println("  reason: Instant has no zone; the JDK refuses to guess which calendar applies");
    }

// --- 7. The same thing through a ZonedDateTime: works ---
    ZonedDateTime ay = a.atZone(ZoneId.of("UTC"));
    ZonedDateTime by = b.atZone(ZoneId.of("UTC"));
    long months = ChronoUnit.MONTHS.between(ay, by);
    System.out.println("  through ZonedDateTime: months = " + months);
  }
}

Что следует вынести из запуска:

Instant.parse("2025-11-04T19:30:00Z") разобрался только благодаря завершающей Z. Уберите Z — и разбор завершится ошибкой: тип настаивает на том, чтобы знать, что строка является UTC. Другие зоны должны передаваться через ZonedDateTime.parse (или задаваться через atZone).
Последовательность событий использовала Duration.between(...). Каждый результат являлся чистым целочисленным количеством миллисекунд — без путаницы с зонами, без перехода на летнее время, без календарной арифметики. Именно поэтому серверное время должно быть в Instant: арифметика — это просто вычитание long-значений под капотом.
Блок «тот же момент, две метки зон» вывел ZonedDateTime-значения, которые выглядели по-разному, но являлись одним и тем же Instant. atZone(...) — это сугубо операция отображения для Instant. Если вы хотите выполнить календарные вычисления (следующий месяц, конец недели), делайте это с ZonedDateTime, а затем вызовите .toInstant(), чтобы вернуться обратно.
Date.from(inst) и legacy.toInstant() были преобразованиями без потерь с точностью до наносекунд. Date хранит только миллисекунды, поэтому при преобразовании через Date точность ниже миллисекунды теряется. Для большинства журналов это допустимо; для захвата событий с высокой точностью оставайтесь в Instant от начала до конца и никогда не делайте цикл через Date.
ChronoUnit.MONTHS.between(a, b) выбросил UnsupportedTemporalTypeException. Это правильное поведение при ошибке: месяцы не имеют постоянной длины в секундах, и JDK отказывается изобретать ответ. Переход через ZonedDateTime предоставил недостающую зону, и тот же вызов сработал. Паттерн универсален: операции в форме календаря требуют зоны, и система типов заставляет вас указывать её явно.

Что дальше

Instant — это момент. Следующие две главы рассматривают длительности времени между моментами: Java Duration для измерений «X секунд, Y наносекунд» и Java Period для календарных длительностей «X лет, Y месяцев, Z дней». Вместе они позволяют выражать «через час» и «через месяц» без потерь.

Практика

В строке журнала есть поле `created_at: 1700000000` (секунды в формате Unix). Вам нужно значение `java.time`, которое можно сравнить с `Instant.now()` и передать в вычисление `Duration.between(...)`. Какое преобразование верно?

`Instant.ofEpochSecond(1_700_000_000L)` — значение представляет собой секунды с начала эпохи в UTC, что является именно тем, чем является `Instant`. Зона не нужна, поскольку значение не содержит никакой календарной информации`LocalDateTime.ofEpochSecond(1_700_000_000L)` — это современный API для секунд эпохи`ZonedDateTime.ofEpochSecond(1_700_000_000L, 0, ZoneId.systemDefault())` — нужно всегда указывать зону`new Date(1_700_000_000L)`, затем вызвать `.toInstant()` — метода `Instant.ofEpochSecond` не существует