Millisekunden vs. Sekunden: die Einheitenverwirrung, die jede App kaputt macht
Der häufigste Timestamp-Bug ist, Millisekunden zu übergeben, wo Sekunden erwartet werden, oder umgekehrt. Lerne die 10-vs-13-Stellen-Regel, die Sprach-Standards, die Datenbank-Implikationen und sichere Umwandlungsmuster.
Warum es zwei Standards gibt
Unix-Zeit wurde ursprünglich in Sekunden definiert — eine Ganzzahl wirkte natürlich für ein System, das pro Takt hochzählte. Das Date-Objekt von JavaScript wurde 1995 eingeführt und wählte Millisekunden, um Ereigniszeiten unter einer Sekunde im Browser zu unterstützen. Viele Datenbanken und Backend-Sprachen behielten Unix-Sekunden als Standard. Heute koexistieren beide Standards in jedem Code, der die JavaScript-Server-Grenze überschreitet — deshalb kann ein Wert gültig aussehen und doch ein Datum zehntausende Jahre entfernt darstellen.
Welche Einheit jede Sprache nutzt
Die sicherste Merkregel: Browser-Date-APIs wollen meist Millisekunden, Unix-artige Server-APIs liefern meist Sekunden, und neuere Zeitbibliotheken bieten oft beides. Schließe beim Lesen einer Drittanbieter-API-Doku nicht allein aus der Sprache auf die Einheit; prüfe Feldbeschreibung und Beispiele.
- Milliseconds: JavaScript Date.now(), Java System.currentTimeMillis(), Java Instant.toEpochMilli(), .NET ToUnixTimeMilliseconds()
- Seconds: Python time.time() (float), PHP time(), Go time.Now().Unix(), Ruby Time.now.to_i, C time(NULL), PostgreSQL EXTRACT(EPOCH)
- Both: Rust — duration.as_secs() for seconds, duration.as_millis() for milliseconds
- Python note: time.time() returns a float, so milliseconds are available as int(time.time() * 1000)
Die Einheit am Wert erkennen
Eine zuverlässige Heuristik für moderne Daten: eine 10-stellige Zahl sind Sekunden; eine 13-stellige Millisekunden. Aktuelle Unix-Sekunden liegen bei rund 1,7–2,1 Milliarden (10 Stellen) und erreichen erst im Jahr 33658 13 Stellen. Aktuelle Unix-Millisekunden haben bereits 13 Stellen. Die Heuristik ist von den 2000ern bis einige tausend Jahre voraus am stärksten; für historische, negative Daten oder kompakte Test-Fixtures nutze explizite Einheiten statt zu raten.
- 10-stelliger Wert → Sekunden (z. B. 1700000000 = 2023-11-14 UTC)
- 13-stelliger Wert → Millisekunden (z. B. 1700000000000 = 2023-11-14 UTC)
- 16-stelliger Wert → Mikrosekunden (durch 1,000,000 für Sekunden teilen)
- negativer Wert → Datum vor dem 1. Januar 1970 (Sekunden oder Millisekunden)
Sichere Umwandlungsmuster
Die Umwandlung selbst ist einfache Arithmetik; das Schwierige ist die Wahl, wo sie passiert. Wandle an der Systemgrenze um, benenne den umgewandelten Wert und vermeide es, mehrdeutige rohe Zahlen durch mehrere Schichten zu reichen.
- Seconds to milliseconds: seconds * 1000
- Milliseconds to whole seconds — JavaScript: Math.floor(ms / 1000)
- Milliseconds to whole seconds — Python: ms // 1000
- Milliseconds to whole seconds — Go: ms / 1000 (integer division)
- Universal guard in JavaScript: const toMs = ts => ts < 1e11 ? ts * 1000 : ts
Wie Einheiten-Bugs in Produktion auftreten
Ein Sekunden-vs-Millisekunden-Bug übersteht oft die Validierung, weil beide Werte nur Zahlen sind. Er zeigt sich später als unmögliches Datum: Januar 1970 in JavaScript, wenn Sekunden als Millisekunden behandelt wurden, oder ein fernes Zukunftsjahr, wenn ein Backend Millisekunden als Sekunden behandelte.
- 1970-Datum in der JavaScript-UI → Sekunden wurden an new Date() übergeben, ohne mit 1000 zu multiplizieren
- Jahr 50000+ in Python, Go oder PHP → Millisekunden wurden an eine API gegeben, die Sekunden erwartete
- Abgelaufene Tokens, die nie ablaufen → Ablauf-Timestamp in der falschen Einheit gespeichert
- Cache-Einträge, die sofort verschwinden → Millisekunden zweimal geteilt oder Sekunden zweimal multipliziert
- Analytics-Diagramme mit leeren Bereichen → Abfragegrenzen nutzen eine andere Einheit als die gespeicherten Ereignis-Timestamps
Namenskonventionen für APIs und Datenbanken
Eine kleine Namenskonvention verhindert die meisten dieser Bugs. Veröffentliche nie ein API-Feld namens timestamp, außer die Doku ist ungewöhnlich klar. Bevorzuge Feldnamen, die Bedeutung und Einheit enthalten.
- createdAtMs — Unix milliseconds, best for JavaScript clients
- createdAtSeconds — Unix seconds, common for backend services
- createdAtIso — ISO 8601 string, useful for human-readable API responses
- expiresAtUnixSeconds — explicit enough for auth tokens and signed URLs
- event_time TIMESTAMPTZ — native database time, with conversion handled by the database
FAQ Millisekunden vs. Sekunden
- Ist ein 13-stelliger Timestamp immer in Millisekunden?
- Für moderne reale Unix-Timestamps ja: 13 Stellen bedeuten meist Millisekunden. Sehr ferne Sekunden-Timestamps können ebenfalls 13 Stellen erreichen, daher sollten kritische Systeme explizite Einheiten-Metadaten mitführen.
- Soll ich Sekunden oder Millisekunden speichern?
- Speichere die Einheit, die dein System natürlich nutzt, aber dokumentiere sie und halte sie konsistent. JavaScript-lastige Systeme nutzen oft Millisekunden; Unix-artige Backends und viele Datenbanken oft Sekunden oder native datetime-Spalten.
- Warum Math.floor(ms / 1000) statt ms / 1000?
- Unix-Sekunden sind meist ganze Sekunden. Math.floor entfernt den Nachkommateil, damit APIs, die ganze Sekunden erwarten, keinen Dezimalwert erhalten.
- Wie wandle ich Millisekunden in Sekunden um?
- Teile durch 1000 und verwirf den Bruchteil: Math.floor(ms / 1000) in JavaScript, ms // 1000 in Python oder ms / 1000 mit Ganzzahldivision in Go. Umgekehrt multipliziere Sekunden mit 1000.