秒 vs ミリ秒のTimestamp

timestampバグの最も一般的な原因の一つが、秒ベースとミリ秒ベースのtimestampの混同です。1700000000という秒timestampは2023年11月14日を表しますが、末尾にゼロが3つ追加された1700000000000はミリ秒timestampとして同じ瞬間を、より細かい精度で表します。

見分け方：

最もシンプルな判断方法は桁数です。2020年代時点で、秒ベースのUnix timestampは10桁、ミリ秒timestampは13桁です。このルールは2001年から2286年まで確実に有効です。

10桁 → 秒        (例: 1700000000)
13桁 → ミリ秒     (例: 1700000000000)
16桁 → マイクロ秒  (例: 1700000000000000)
19桁 → ナノ秒     (例: 1700000000000000000)

言語ごとの使用単位：

単位	言語/システム
秒	Python, PHP, Ruby, Bash, Go, C, MySQL
ミリ秒	JavaScript, Java, Dart, C# (DateTimeOffset)

相互変換：

// ミリ秒から秒へ
const seconds = Math.floor(milliseconds / 1000);

// 秒からミリ秒へ
const ms = seconds * 1000;

よくあるバグのシナリオ： JavaScriptのDate.now()値（ミリ秒）をデータベースに保存し、秒を期待するPythonスクリプトでそれを読み取ると、数万年先の未来の日付として解釈されます。対策として、APIの境界では常にtimestampの単位を明記し、一貫して変換することが重要です。

API設計のヒント： APIを設計する際は、フィールド名に単位を明示してください（例：created_at_msやexpires_at_unix_seconds）。これにより曖昧さがなくなり、APIの利用者のデバッグ時間を大幅に節約できます。StripeやTwilioなど多くの主要APIは、秒ベースのtimestampを使用し、それを明確にドキュメントに記載しています。