Unix timestamp: seconds vs milliseconds

실무에서 가장 흔한 버그는 초/밀리초 단위 혼동입니다. 숫자 자체는 비슷해 보이지만 결과 시간은 수십 년 차이가 날 수 있습니다. 로그, JWT 만료, 캐시 TTL, 예약 실행 같은 기능이 전부 시간 단위에 기대고 있기 때문에 이 실수 하나로 인증과 스케줄이 모두 꼬일 수 있습니다.

1) 단위 구분 방법

초(seconds): 보통 10자리
밀리초(milliseconds): 보통 13자리

간단한 체크:

숫자가 1e12보다 작으면 보통 초
13자리면 대부분 밀리초

2) 자주 발생하는 오류

서버는 초를 기대하는데 클라이언트가 밀리초를 보낸 경우
로그는 UTC 기준인데 화면은 로컬 시간으로 해석한 경우
캐시 만료를 계산할 때 단위를 섞어 사용한 경우
자바스크립트 Date.now() 값을 그대로 다른 언어 API에 넘긴 경우

3) 실무 팁

API 스펙에 단위를 명시하세요.
DB 스키마나 이벤트 로그에 단위 표기를 붙여 혼동을 방지하세요.
시스템 간 시간대(UTC/Local)를 반드시 확인하세요.
테스트 데이터에 초와 밀리초 예시를 모두 포함하세요.

4) 바로 써보기

Unix Timestamp Converter에 숫자를 넣으면 ISO, 로컬, 초/밀리초가 동시에 출력됩니다. 단위를 빠르게 확인하는 데 좋습니다.

5) 변환 예시

1700000000 → 2023-11-14T22:13:20.000Z
1700000000000 → 2023-11-14T22:13:20.000Z (밀리초)

6) 테스트 팁

동일한 값이 UTC/로컬에서 어떻게 보이는지 비교
서버/클라이언트 시간대가 일치하는지 확인

여기서 중요한 점은 "같은 순간"이라도 표현 방식이 다를 수 있다는 것입니다. 사용자가 보는 화면 시간은 로컬 시간대일 수 있지만, 내부 저장은 UTC 문자열이나 epoch 값으로 통일하는 편이 일반적입니다.

7) 자주 보는 장애 사례

만료 시간이 이미 지났는데도 로그인 토큰이 계속 유효하거나, 반대로 발급 직후 바로 만료되는 문제가 있습니다. 대부분 exp를 초 단위로 저장했는데 클라이언트가 밀리초로 비교하거나 그 반대로 계산한 경우입니다. 예약 발송이나 배치 실행에서도 같은 일이 일어납니다.

8) 체크리스트

단위를 명시했는가?
시간대 차이를 고려했는가?
로그의 기준 시간이 무엇인지 확인했는가?
언어/플랫폼 기본값을 그대로 믿지 않았는가?

9) 추가 예시

만료 계산: 현재 시각 + 3600초
로컬 표시: UTC를 브라우저에서 변환
JavaScript Date.now()는 밀리초, 일부 백엔드 라이브러리 epoch는 초입니다.

Unix timestamp: seconds vs milliseconds (practical guide)

목차