Guide

Trabalhando com carimbos de data/hora UTC – Guia completo

Introdução

UTC (Tempo Universal Coordenado) é a referência de tempo padrão usada em computação e redes. Compreender como trabalhar com carimbos de data/hora UTC é essencial para criar aplicativos que funcionem em vários fusos horários e precisem de cálculos de tempo precisos.

Compreendendo o UTC

Qual é o horário UTC?

UTC é um padrão de horário que:

Não tem diferença de fuso horário (sem horário de verão)
Usa um formato de relógio de 24 horas (00:00:00 a 23:59:59.999)
Representado como "Z" na ISO 8601 (por exemplo, 2025-01-07T12:00:00.000Z)
Serve de base para todos os outros fusos horários

UTC versus hora local

Conceito crucial: A hora local varia de acordo com a localização geográfica e o fuso horário. UTC é constante em todo o mundo.

Característica	Hora UTC	Hora Local
Compensação de fuso horário	Sempre UTC+00:00	Varia de acordo com o local (por exemplo, UTC-5, UTC+8, UTC-10)
Horário de verão	Sem ajustes de horário de verão	Varia de acordo com a estação e região
Consistência	Globalmente consistente	Sistemas diferentes podem ter horários locais diferentes
Caso de uso principal	Sistemas globais, bancos de dados, APIs	Aplicativos voltados para o usuário, eventos de calendário
Tamanho de armazenamento	Igual a qualquer carimbo de data/hora (sem sobrecarga extra)	Igual a DateTime (armazenamento maior)
Desempenho de consulta	Excelente (comparações numéricas)	Lento (requer análise de data e hora)

Aviso: Sempre armazene carimbos de data/hora UTC em seu banco de dados. Converta para a hora local apenas para fins de exibição.

Formato de carimbo de data/hora UTC

ISO 8601

Os carimbos de data e hora UTC na ISO 8601 sempre terminam com “Z”:

2025-01-07T12:00:00.000Z  // January 7, 2025, 12:00:00 UTC

Carimbo de data e hora Unix

Os carimbos de data e hora UTC são o número de segundos desde a época Unix (1970-01-01 00:00:00 UTC):

1735689600 // January 1, 2025, 00:00:00 UTC

Convertendo UTC para hora local

JavaScript

// Convert UTC timestamp (seconds) to local time
function utcToLocal(utcTimestampSeconds, timezoneOffsetHours = 0) {
  const date = new Date(
    (utcTimestampSeconds * 1000) + (timezoneOffsetHours * 60 * 60 * 1000),
  );
  return date.toLocaleString(); // Returns string like "1/7/2025, 6:12:00 PM"
}

// Get UTC timestamp and convert to local
const now = Math.floor(Date.now() / 1000);
console.log(utcToLocal(now, -5)); // UTC-5 for EST

###Píton

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# Convert UTC to specific timezone
def utc_to_local(utc_timestamp: int, timezone_str: str) -> datetime:
    """
    Convert UTC timestamp to local datetime in specified timezone.

    Args:
        utc_timestamp: Unix timestamp in seconds
        timezone_str: IANA timezone name (e.g., 'America/New_York')

    Returns:
        Local datetime object
    """
    utc_time = datetime.fromtimestamp(utc_timestamp, tz=timezone.utc)
    return utc_time.astimezone(ZoneInfo(timezone_str))

# Example
print(utc_to_local(1735689600, "America/Los_Angeles"))

###SQL

-- MySQL: Convert UTC timestamp to datetime
-- Note: Use FROM_UNIXTIME() which respects the system timezone setting

-- Convert UTC timestamp to MySQL DATETIME
SELECT
  id,
  FROM_UNIXTIME(created_at) AS mysql_datetime,
  created_at
FROM events
WHERE id = ?;

-- Store current UTC timestamp
UPDATE events
SET created_at = UNIX_TIMESTAMP(NOW());

-- PostgreSQL: Use TIMESTAMPTZ for timezone-aware storage
CREATE TABLE events (
  id BIGSERIAL PRIMARY KEY,
  event_timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  event_date TIMESTAMP WITH TIME ZONE 'UTC'
);

-- Query events with local time display
SELECT
  id,
  event_timestamp,
  TO_CHAR(event_timestamp, 'YYYY-MM-DD HH24:MI:SS') AS local_time
FROM events;

Prática recomendada: Sempre armazene carimbos de data/hora UTC. Use a conversão de fuso horário no nível do aplicativo apenas para exibição.

Tratamento de fuso horário

Compreendendo as compensações de fuso horário

As compensações de fuso horário são expressas como:

UTC+XX:00 (por exemplo, UTC-5:00)
UTC-XX:00 (por exemplo, UTC+8:00)

Deslocamento	Horas	Cidade	Região
UTC-5:00	-5	Nova York, Toronto, Bogotá, Lima	Horário Padrão do Leste
UTC-8:00	-8	Los Angeles, São Francisco, Tijuana	Horário padrão do Pacífico
UTC+0:00	0	Londres, Dublin, Lisboa	Hora da Europa Ocidental
UTC+1:00	+1	Paris, Berlim, Roma	Hora da Europa Central
UTC+8:00	+8	Singapura, Hong Kong, Perth	Horário Padrão da China
UTC+9:00	+9	Tóquio, Seul, Pyongyang	Horário padrão do Japão
UTC+10:00	+10	Sydney, Melbourne, Brisbane	Horário padrão do leste da Austrália
UTC+12:00	+12	Auckland	Horário padrão da Nova Zelândia

Exemplos de conversão de fuso horário

Conversões de fuso horário JavaScript

// Convert between UTC and different timezones
function convertToTimezone(utcDate, timezone) {
  const options = { timeZone: timezone };
  return utcDate.toLocaleString('en-US', options);
}

// Examples
const utcDate = new Date('2025-01-07T12:00:00.000Z');

console.log(convertToTimezone(utcDate, 'America/New_York'));    // "1/7/2025, 7:00:00 AM EST"
console.log(convertToTimezone(utcDate, 'Asia/Tokyo'));      // "2025/1/7, 21:00:00 JST"
console.log(convertToTimeDate, 'Europe/London'));     // "1/7/2025, 12:00:00 GMT"
console.log(convertToTimezone(utcDate, 'Asia/Shanghai'));   // "2025/1/7, 20:00:00 CST"

// Python timezone handling
from datetime import datetime, timezone

# Get current UTC time and convert to timezone
now_utc = datetime.now(timezone.utc)

# Convert to specific timezone
now_tokyo = now_utc.astimezone('Asia/Tokyo')
now_est = now_utc.astimezone('America/New_York')
now_gmt = now_utc.astimezone('Etc/GMT')

print(f"UTC: {now_utc}")
print(f"Tokyo: {now_tokyo}")
print(f"EST: {now_est}")
print(f"GMT: {now_gmt}")

Melhores práticas

Diretrizes de armazenamento UTC

Armazenamento: Sempre armazene carimbos de data/hora UTC. Eles são independentes de fuso horário e eficientes para aplicativos globais.

Exibição: Converta para fuso horário local somente na camada da IU. Nunca armazene horários locais no banco de dados.

Consultas: Sempre filtre e classifique por carimbos de data/hora UTC. Isso garante uma ordem consistente, independentemente do fuso horário do usuário.

APIs: sempre use carimbos de data/hora UTC nas respostas da API. Documente o fuso horário na documentação da API.

Aviso crítico: Nunca misture carimbos de data/hora UTC com carimbos de data/hora locais na mesma coluna. Isso cria problemas de integridade de dados e inconsistências de consulta.

Armadilhas Comuns

Armadilha 1: Esquecer os fusos horários

Problema: Nem todos os locais observam o horário de verão ao mesmo tempo.

Exemplo: Arizona não segue o horário de verão, mas Nova York sim. Isso pode causar diferenças de 1 hora entre eles durante determinados períodos.

Solução: Use bancos de dados de fuso horário da IANA (banco de dados tz) que incluem regras de horário de verão históricas e atuais.

Armadilha 2: deslocamentos de fuso horário incorretos

Problema: Usando deslocamentos codificados em vez de nomes de fuso horário.

Ruim: const offset = -5 * 3600000; // EST é sempre -5, mas o Arizona não observa o horário de verão

Bom: const offset = 'America/New_York'; // Usa banco de dados IANA com horário de verão histórico correto

Armadilha 3: presumir que todos os horários estão no mesmo formato

Problema: Nem todos os sistemas usam UTC (por exemplo, alguns usam GMT, outros usam UTC+X).

Exemplo: Os carimbos de data/hora Unix são sempre baseados em UTC, mas os sistemas de arquivos podem variar.

Solução: sempre especifique explicitamente o fuso horário ao analisar a entrada do usuário.

Trabalhando com fusos horários diferentes

JavaScript

// Best practice: Always specify timezone when creating dates
const date1 = new Date('2025-01-07T12:00:00'); // UTC time (good)

const date2 = new Date('2025-01-07T12:00:00-08:00'); // Bad: assumes local timezone

// Convert between timezones
function convertTimezones(fromDate, fromTz, toTz) {
  return {
    fromTime: fromDate.toLocaleString('en-US', { timeZone: fromTz }),
    toTime: fromDate.toLocaleString('en-US', { timeZone: toTz }),
    fromTimestamp: fromDate.getTime(),
    toTimestamp: fromDate.toLocaleString('en-US', { timeZone: toTz }),
  };
}

// Example: Convert UTC to multiple timezones
const utcDate = new Date('2025-01-07T12:00:00.000Z');
const conversions = [
  convertTimezones(utcDate, 'UTC', 'America/New_York'),
  convertTimezones(utcDate, 'UTC', 'Asia/Tokyo'),
  convertTimezones(utcDate, 'UTC', 'Europe/London'),
];

###Píton

from datetime import datetime, timezone

# Best practice: Use pytz library
import pytz

def convert_to_timezone(utc_time: datetime, timezone: str) -> datetime:
    """
    Convert UTC datetime to specified timezone using IANA timezone database.

    Args:
        utc_time: UTC datetime object
        timezone_str: IANA timezone name

    Returns:
        Localized datetime object
    """
    utc_time = utc_time.replace(tzinfo=timezone.tzinfo(utc_time))
    return utc_time.astimezone(timezone)

# Example: Convert current UTC to multiple timezones
now_utc = datetime.now(timezone.utc)
now_est = now_utc.astimezone('America/New_York')
now_gmt = now_utc.astimezone('Etc/GMT')
now_tokyo = now_utc.astimezone('Asia/Tokyo')

print(f"UTC: {now_utc}")
print(f"EST: {now_est}")
print(f"GMT: {now_gmt}")
print(f"JST: {now_tokyo}")

Melhores práticas de fuso horário

Diretrizes para seleção de fuso horário

<ol> <li>Sempre use nomes de fuso horário da IANA (por exemplo, "América/Nova_Iorque", "Europa/Londres")</li> <li>Use bancos de dados de fuso horário (banco de dados IANA tz, banco de dados tz) em vez de compensações codificadas</li> <li>Teste as transições do horário de verão nas regiões-alvo (especialmente na primavera e no outono)</li> <li>Documente claramente suas suposições de fuso horário na documentação da API</li> <li>Considere usar o UTC para todos os cálculos e armazenamento interno</li> <li>Exibir nomes de fuso horário e horários locais separadamente na IU (armazenar UTC internamente)</li> </ol>

Ferramentas e referências

Ferramentas relacionadas

Conversor UTC/Local - Converte entre UTC e hora local
Navegador de fuso horário - Navegar no banco de dados de fuso horário da IANA
[Carimbo de data e hora atual](/carimbo de data e hora atual) - Obtenha o carimbo de data e hora UTC atual
Unix Timestamp Converter - Converter entre formatos
Validador de carimbo de data/hora - Validar formatos de carimbo de data/hora
Conversor de formato Timestamp - Centro de conversão multiformato

Resumo

Principal vantagem: Sempre armazene carimbos de data/hora UTC. Lide com a conversão de fuso horário no aplicativo ou na camada de consulta. Isso garante a consistência dos dados e torna seu aplicativo compatível globalmente.

Crítico: Nunca misture carimbos de data/hora UTC e locais no armazenamento do banco de dados. Sempre armazene o UTC e converta para local somente quando necessário.

Dica de desempenho: Os carimbos de data/hora UTC são ideais para:

Indexação de banco de dados (comparações numéricas)

Consultas de intervalo (filtros numéricos)

Operações de classificação (ordem numérica)

Particionamento baseado em tempo

Repositório de exemplos de código

Para obter mais exemplos de códigos de carimbo de data/hora e fuso horário, consulte nossas ferramentas e guias relacionados para trabalhar com casos de uso específicos:

Timestamp Format Converter - Conversões de formato com geração de código
Unix Timestamp Converter - Conversões bidirecionais
Conversor UTC/Local - Conversões específicas de fuso horário