Guia de Unix timestamp: conversão segundos/milissegundos/microssegundos e melhores práticas com fusos horários
Os Unix timestamps representam o tempo como “a quantidade de tempo decorrida desde o Unix epoch (1 de janeiro de 1970, 00:00:00 UTC).” Mais de 95% dos servidores web e 90% dos sistemas de banco de dados no mundo utilizam essa representação internamente. Este guia cobre as diferenças de precisão, implementações em linguagens de programação, tratamento de fusos horários e considerações sobre o horário de verão (DST).
Origens e definição do Unix timestamp
O Unix Epoch começou em 1 de janeiro de 1970, 00:00:00 UTC. O Unix timestamp 0 corresponde a esse momento, enquanto 1262304000 representa 2010-01-01 00:00:00 UTC. O sistema ignora os efeitos dos segundos intercalares por padrão.
Originalmente armazenado como inteiros com sinal de 32 bits, isso criou o Problema do Ano 2038 — o valor máximo transborda em 19 de janeiro de 2038, 03:14:07 UTC. Os sistemas modernos usam inteiros de 64 bits, estendendo significativamente os intervalos de tempo representáveis.
Diferenças de precisão temporal
| Unidade | Quantidade por Segundo | Dígitos | Aplicações Típicas |
|---|---|---|---|
| Segundos (s) | 1 | 10 | Sistemas Unix/Linux tradicionais |
| Milissegundos (ms) | 1.000 | 13 | JavaScript, Java, logging |
| Microssegundos (μs) | 1.000.000 | 16 | Rastreamento distribuído, bancos de dados |
| Nanossegundos (ns) | 1.000.000.000 | 19 | Linguagem Go, análise de desempenho |
Regra prática: Timestamps de 10 dígitos geralmente representam segundos, 13 dígitos representam milissegundos, 16 dígitos representam microssegundos e 19 dígitos representam nanossegundos.
Timestamps em JavaScript
JavaScript usa milissegundos nativamente. O construtor Date() assume que os números de entrada são milissegundos — para timestamps em nível de segundos, multiplique por 1000.
// Obter o Unix timestamp atual (em milissegundos)
const timestampMs = Date.now();
console.log(timestampMs); // Exemplo de saída: 1692268800123
// Para timestamps em nível de segundos, divida os milissegundos por 1000 e arredonde para baixo
const timestampSec = Math.floor(Date.now() / 1000);
console.log(timestampSec); // Exemplo de saída: 1692268800
// Converter Unix timestamp de volta para objeto Date
let ts = 1692268800;
let date = new Date(ts * 1000);
console.log(date.toISOString()); // "2023-08-17T16:00:00.000Z"Timestamps em Python
O time.time() do Python retorna Unix timestamps em nível de segundos como valores de ponto flutuante:
import time
from datetime import datetime, timezone
# Obter o Unix timestamp atual (segundos, ponto flutuante)
now_sec = time.time()
print(now_sec) # Exemplo de saída: 1692268800.123456
# Obter milissegundos (inteiro)
now_millis = int(time.time() * 1000)
print(now_millis) # Exemplo: 1692268800123
# Obter nanossegundos (Python 3.7+)
now_nanos = time.time_ns()
print(now_nanos) # Exemplo: 1692268800123456789
# Converter para datetime
ts = 1692268800
dt_local = datetime.fromtimestamp(ts)
dt_utc = datetime.fromtimestamp(ts, timezone.utc)
print(dt_local.strftime("%Y-%m-%d %H:%M:%S")) # Hora local
print(dt_utc.strftime("%Y-%m-%d %H:%M:%S")) # Hora UTCTimestamps em Go
A biblioteca time do Go fornece múltiplos níveis de precisão:
package main
import (
"fmt"
"time"
)
func main() {
// Obter o Unix timestamp atual
sec := time.Now().Unix() // Segundos
msec := time.Now().UnixMilli() // Milissegundos (Go 1.17+)
nsec := time.Now().UnixNano() // Nanossegundos
fmt.Println(sec) // Exemplo: 1692268800
fmt.Println(msec) // Exemplo: 1692268800123
fmt.Println(nsec) // Exemplo: 1692268800123456789
// Converter timestamp para objeto Time
t := time.Unix(sec, 0)
fmt.Println(t.UTC())
fmt.Println(t)
}Erros comuns e melhores práticas
Exemplo de erro: unidades ambíguas
// ✗ Incorreto: unidade do timestamp não está clara
const timestamp = 1692268800;
const date = new Date(timestamp); // Erro: tratado como milissegundos, mostra 1970
// ✓ Correto: indica claramente as unidades
const timestampSec = 1692268800;
const timestampMs = 1692268800000;
const dateFromSec = new Date(timestampSec * 1000);Melhor prática para nomes de campos
log_entry = {
"timestamp_ms": 1692268800123, # Nível de milissegundos
"timestamp_iso": "2023-08-17T16:00:00Z", # ISO 8601 UTC
"event_type": "user_login",
"user_id": 12345
}Problemas com fusos horários
Existem quatro problemas principais ao trabalhar com fusos horários:
- Confundir hora local com UTC — Os Unix timestamps são sempre baseados em UTC; converta para local apenas ao exibir
- Não salvar a informação de fuso horário — Cria ambiguidade; armazene sempre em UTC ou inclua o deslocamento
- Inconsistências de fuso horário entre sistemas — Todos os sistemas devem usar a mesma referência de fuso horário (recomenda-se UTC)
- Calcular manualmente os deslocamentos de horário de verão — Confie nas bibliotecas integradas, não escreva valores fixos no código
A abordagem recomendada: “Armazenamento padronizado, exibição localizada.” Use UTC ou Unix timestamps nas fases de armazenamento e transmissão para garantir a consistência; formate de acordo com o fuso horário do usuário ao exibir.
Problemas com o horário de verão (DST)
O DST cria dois períodos problemáticos:
- Tempo omitido: Quando o horário de verão começa, os relógios avançam. Por exemplo, as 02:00 pulam diretamente para as 03:00, fazendo com que as 02:30 não existam.
- Tempo repetido: Quando o horário de verão termina, o período de 01:00 a 01:59 aparece duas vezes, criando ambiguidade.
Os Unix timestamps em si permanecem contínuos e não são afetados pelo DST, mas as conversões para hora local requerem tratamento cuidadoso.
Melhores práticas para logging, bancos de dados e APIs
Sistemas de logging
Unifique o fuso horário UTC + formato ISO 8601; inclua timestamps em milissegundos ou precisão de microssegundos quando necessário.
Bancos de dados
Prefira tipos de calendário nativos com fuso horário; use BIGINT para timestamps numéricos com indicação clara de unidades nos nomes dos campos (ex. *_epoch_ms).
APIs
Especifique claramente os formatos e unidades. As interfaces externas devem usar ISO 8601 (legível, inclui fuso horário); os sistemas internos podem usar timestamps numéricos com unidades documentadas.
Cenários de erro comuns
- Falha na análise de 13 dígitos: Timestamps em milissegundos enviados a funções que esperam segundos provocam estouro. Determine as unidades primeiro pelo número de dígitos.
- Desajuste de formatos: Datas inválidas, fusos horários ausentes ou pontos de mudança de DST causam erros de análise.
- Deslocamentos de fuso horário: Desvios de horas inteiras (±8h) tipicamente indicam problemas de unificação. Recomenda-se usar UTC internamente.
- Estouro numérico: Sistemas de 32 bits enfrentam os limites de 2038; priorize inteiros de 64 bits.
Perguntas frequentes
Por que 1 de janeiro de 1970?
O desenvolvimento do sistema operacional Unix começou em 1970, e era um ano de década redonda — fácil de lembrar e calcular. Os inteiros de 32 bits podiam representar datas de 1970 a 2038, o que era suficiente na época.
Como identificar segundos vs. milissegundos?
Três métodos: verifique o número de dígitos (10 dígitos = segundos, 13 = milissegundos, 16 = microssegundos, 19 = nanossegundos), calcule a verificação analisando e conferindo a razoabilidade, ou use ferramentas de conversão online.
O problema de 2038 ainda é relevante?
Os sistemas modernos que usam inteiros de 64 bits já resolveram isso em grande parte. As principais linguagens de programação já suportam timestamps de 64 bits. Sistemas legados de 32 bits e dispositivos embarcados ainda podem precisar de atenção.
Por que o DST causa problemas?
A descontinuidade temporal das horas omitidas e a repetição temporal das horas repetidas criam ambiguidade na análise. Diferentes sistemas tratam as horas ambíguas com estratégias diferentes. Solução: use UTC internamente, converta para hora local apenas ao exibir.
Por que os timestamps de JavaScript e Python diferem?
O Date.now() do JavaScript retorna milissegundos (13 dígitos); o time.time() do Python retorna segundos (ponto flutuante com precisão de microssegundos). A conversão requer dividir/multiplicar por 1000.
Experimente você mesmo
Converta Unix timestamps instantaneamente com nosso Conversor de Unix Timestamp — detecta automaticamente segundos, milissegundos e microssegundos. 100% no seu navegador.
Trabalha com PostgreSQL? Leia O que é armazenado exatamente em uma coluna timestamp do PostgreSQL? para ver os problemas de fuso horário específicos do Postgres.
Resumo
Este guia cobre os fundamentos dos Unix timestamps — desde as origens do epoch e as conversões de múltipla precisão até as implementações em diferentes linguagens, o tratamento de fusos horários, os problemas do DST e as melhores práticas de engenharia em logging, bancos de dados e design de APIs. A conclusão principal: armazene em UTC, exiba em hora local, e seja sempre explícito sobre as unidades do timestamp.
Os timestamps são apenas uma peça do kit de ferramentas do desenvolvedor. Explore mais ferramentas essenciais para desenvolvedores de codificação, hashing e conversão de dados.