Unix timestamp: секунды или миллисекунды

В интерфейсе внезапно 1970 год. Или наоборот - дата улетела в далёкое будущее. До timezone ещё рано: сначала проверьте, не перепутаны ли секунды и миллисекунды. Код при этом может быть "правильным" с обеих сторон, просто контракт между системами оказался неявным.

Для быстрой проверки откройте конвертер timestamp и сравните обе интерпретации. Это не доказывает причину бага, но быстро проверяет главную гипотезу.

Быстрая проверка по длине

Для дат вокруг текущих лет timestamp в секундах обычно выглядит как 10 цифр. Это формат из мира Unix: сколько секунд прошло с 1 января 1970 года UTC. Такое часто встречается в логах, backend API и командах вроде date +%s.

Миллисекунды чаще выглядят как 13 цифр. Их любит JavaScript: Date.now() возвращает именно миллисекунды. Клиентская аналитика и браузерные события тоже часто живут в этом формате.

Правило не абсолютное. Старые даты короче, будущие длиннее. Но если у вас "сегодняшняя" дата и число из 13 цифр, почти наверняка это миллисекунды.

Как выглядит перепутанный формат

Если секунды скормить коду, который ждёт миллисекунды, дата падает к январю 1970 года. Передали 1719326400, а new Date() решил, что это миллисекунды. Получилось не лето 2024, а первые недели после Unix epoch.

Обратная ошибка заметнее: миллисекунды прочитали как секунды, и дата улетела куда-то в далёкое будущее. Если в интерфейсе внезапно появился фантастический год, первым делом проверьте единицу timestamp.

Где ошибка появляется чаще всего

Частое место ошибки - граница frontend и backend. Сервер отдаёт секунды, фронтенд передаёт число в new Date(value), JavaScript ждёт миллисекунды. Или браузер отправляет Date.now(), а backend кладёт значение в поле, где команда думала хранить секунды.

Вторая зона риска - аналитика. События из разных систем легко смешиваются: одна пишет seconds, другая milliseconds, третья ISO-строку. До сортировки и сравнения такие значения надо привести к одному виду.

Самая дешёвая профилактика - писать единицу прямо в названии поля: created_at_ms, created_at_seconds, expiresAtMs. createdAt выглядит красиво, но через полгода заставляет угадывать.

Если API уже публичный, лучше зафиксировать единицу в документации и тестах. Менять seconds на milliseconds без версии контракта - верный способ получить часть клиентов в 1970 году.