Integração de time, timezones & context

O pacote time do Go modela instantes, durações e eventos recorrentes.

context anexa prazos e cancelamento a essas operações para que os servidores parem o trabalho quando os clientes desconectam ou os orçamentos expiram.

Resumo

Use time.Time para instantes de calendário e time.Duration para intervalos decorridos.

Leituras de relógio monotônicas evitam que saltos de horário de verão corrompam medições de Since.

Carregue locais com time.LoadLocation para exibição local correta; armazene UTC em bancos de dados.

Combine context.WithTimeout com chamadas bloqueantes para que as goroutines saiam prontamente.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
 
timer := time.NewTimer(500 * time.Millisecond)
defer timer.Stop()
 
select {
case <-timer.C:
    // trabalho
case <-ctx.Done():
    return ctx.Err()
}

Quando usar isso:

• Medir latência com time.Since e time.Until.
• Agendar retentativas, batimentos cardíacos ou limites de taxa com time.Ticker.
• Respeitar prazos HTTP e RPC via context.Context.
• Converter timestamps entre UTC e escritórios regionais para exibição.

Exemplo de Trabalho

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func fetchWithDeadline(ctx context.Context, url string) error {
    ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
    defer cancel()
 
    done := make(chan error, 1)
    go func() {
        // substituto para chamada net/http ou banco de dados
        time.Sleep(300 * time.Millisecond)
        done <- nil
    }()
 
    select {
    case err := <-done:
        return err
    case <-ctx.Done():
        return fmt.Errorf("fetch %s: %w", url, ctx.Err())
    }
}
 
func nextBusinessOpen(now time.Time, loc *time.Location) time.Time {
    local := now.In(loc)
    // exemplo ingênuo: próximo 09:00 local em um dia de semana
    open := time.Date(local.Year(), local.Month(), local.Day(), 9, 0, 0, 0, loc)
    if !local.Before(open) {
        open = open.Add(24 * time.Hour)
    }
    return open.UTC()
}
 
func main() {
    loc, err := time.LoadLocation("America/New_York")
    if err != nil {
        panic(err)
    }
 
    if err := fetchWithDeadline(context.Background(), "https://example.com"); err != nil {
        panic(err)
    }
 
    utcNow := time.Now().UTC()
    fmt.Println("próximo aberto UTC:", nextBusinessOpen(utcNow, loc))
}

O que isso demonstra:

• Prazo aninhado em um context de entrada.
• Goroutine mais select conectando trabalho bloqueante e cancelamento.
• LoadLocation para nomes de zona IANA e conversão de instantes de exibição para UTC.

Mergulho Profundo

Como Funciona

• time.Now captura leituras de relógio de parede e monotônicas em um único valor time.Time.
• A subtração (t2.Sub(t1)) usa leituras monotônicas quando ambos os tempos compartilham a mesma base monotônica.
• time.Timer dispara uma vez; time.Ticker repete até Stop.
• context.WithDeadline e WithTimeout agendam cancel() automático em um instante derivado de time.Time.

Conceitos de Tempo

Notas do Go

// Analisa e formata com layouts explícitos (tempo de referência Seg 2 de Jan 15:04:05 MST 2006):
t, _ := time.Parse(time.RFC3339, "2026-07-15T12:00:00Z")
 
// Sleep não é cancelável - prefira select:
select {
case <-time.After(delay):
case <-ctx.Done():
    return ctx.Err()
}

Armadilhas

• Usar time.Sleep sem context - O desligamento e o cancelamento do cliente não podem interromper o sleep. Correção: select em ctx.Done() e time.After.
• Armazenar tempos locais em bancos de dados - Transições de horário de verão duplicam ou pulam horas. Correção: persista UTC; converta na fronteira da UI com Location.
• Esquecer timer.Stop() ou ticker.Stop() - Vazamentos de goroutines até o tempo de disparo. Correção: defer Stop() imediatamente após a criação.
• Comparar time.Time com == entre zonas - O mesmo instante pode diferir nos campos de exibição. Correção: compare t1.Equal(t2) ou converta ambos para UTC.
• Usar time.After em loops apertados - Cria um novo timer por iteração. Correção: reutilize time.NewTimer e reinicie cuidadosamente.
• Passar context.Background() em servidores - Ignora o cancelamento da solicitação de entrada. Correção: aceite ctx de r.Context() ou escopo pai.

Alternativas

FAQs

Relacionados

• Noções Básicas da Biblioteca Padrão - Exemplos de timeout de context e time.Since
• Pacotes runtime, debug & pprof - Perfis de agendador e bloqueio
• Visão Geral da Família de Pacotes database/sql & net - E/S ciente de context
• Noções Básicas de Concorrência - Padrões de goroutines e select
• Melhores Práticas de net/http - Configuração de timeout do servidor

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).