Noções básicas de context

10 exemplos para você começar com o Pacote context - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Crie um módulo: mkdir ctxdemo && cd ctxdemo && go mod init example.com/ctxdemo.
• Salve cada trecho como main.go (ou arquivos separados em um pacote) e execute com go run ..

Exemplos Básicos

1. context.Background e TODO

Contextos raiz iniciam cadeias que não têm cancelamento pai.

package main
 
import (
    "context"
    "fmt"
)
 
func main() {
    fmt.Println(context.Background().Err() == nil)
    fmt.Println(context.TODO().Err() == nil)
}

• context.Background() é o context vazio de nível superior para main, servidores e testes.
• context.TODO() é um placeholder durante refatorações quando o pai ainda não está conectado.
• Nenhum deles carrega um deadline ou valores até que você os envolva.

Relacionado: context.Context: Cancelamento como uma API de Primeira Classe - por que o context existe

2. WithCancel

O cancelamento manual interrompe o trabalho descendente.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()
 
    go func() {
        <-ctx.Done()
        fmt.Println("parou:", ctx.Err())
    }()
 
    time.Sleep(50 * time.Millisecond)
    cancel()
    time.Sleep(20 * time.Millisecond)
}

• WithCancel retorna um context filho e uma função cancel.
• Sempre use defer cancel() para liberar recursos, mesmo que você cancele antecipadamente.
• ctx.Err() retorna context.Canceled após o cancelamento manual.

Relacionado: Propagação de Cancelamento em Manipuladores HTTP - tempos de vida de requisição reais

3. WithTimeout

Um deadline relativo cancela automaticamente.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
    defer cancel()
 
    select {
    case <-time.After(250 * time.Millisecond):
        fmt.Println("trabalho concluído")
    case <-ctx.Done():
        fmt.Println("tempo esgotado:", ctx.Err())
    }
}

• WithTimeout(parent, d) é um atalho para WithDeadline(parent, time.Now().Add(d)).
• Quando o deadline expira, Done() fecha e Err() é context.DeadlineExceeded.
• Timeouts filhos mais curtos devem permanecer dentro do orçamento do deadline pai.

Relacionado: Deadlines e Timeouts Entre Limites de Serviço - orçamentos de serviço

4. WithDeadline

Tempos absolutos de relógio de parede são adequados para expiração fornecida por upstream.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func main() {
    deadline := time.Now().Add(80 * time.Millisecond)
    ctx, cancel := context.WithDeadline(context.Background(), deadline)
    defer cancel()
 
    if d, ok := ctx.Deadline(); ok {
        fmt.Println("deadline:", d.Format(time.RFC3339))
    }
    <-ctx.Done()
    fmt.Println(ctx.Err())
}

• Deadline() reporta o corte e se um deadline está definido.
• Prefira WithTimeout quando você pensa em durações; use WithDeadline ao sincronizar com um timestamp externo.
• Deadlines pais restringem filhos - um filho não pode sobreviver ao seu pai.

Relacionado: Deadlines e Timeouts Entre Limites de Serviço - propagando expiração

5. Verificando ctx.Done() em um loop

Trabalho longo deve verificar o cancelamento entre iterações.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func work(ctx context.Context) error {
    for i := 0; i < 10; i++ {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            time.Sleep(30 * time.Millisecond)
            fmt.Println("tick", i)
        }
    }
    return nil
}
 
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
    defer cancel()
    fmt.Println(work(ctx))
}

• Um único select com default evita bloqueio quando o ctx ainda está ativo.
• Retorne ctx.Err() para que os chamadores distingam cancelamento de outras falhas.
• APIs de bloqueio devem aceitar ctx em vez de polling feito manualmente quando disponível.

Relacionado: Testando Código Que Aceita context.Context - afirmando caminhos de cancelamento

6. Passando ctx como o primeiro parâmetro

A forma padrão da função propaga o ciclo de vida para baixo na pilha.

package main
 
import (
    "context"
    "fmt"
)
 
func fetch(ctx context.Context, id int) (string, error) {
    if err := ctx.Err(); err != nil {
        return "", err
    }
    return fmt.Sprintf("user-%d", id), nil
}
 
func handler(ctx context.Context) error {
    name, err := fetch(ctx, 42)
    if err != nil {
        return err
    }
    fmt.Println(name)
    return nil
}
 
func main() {
    _ = handler(context.Background())
}

• Nomeie o parâmetro ctx e coloque-o primeiro - revisores e linters esperam isso.
• Verifique ctx.Err() antes de trabalho caro quando as chamadas são profundas.
• Passe o mesmo ctx para baixo; não crie um novo Background() no meio da requisição.

Relacionado: Melhores Práticas do Pacote context - regras de nomenclatura da equipe

7. WithValue para metadados de requisição

Chaves tipadas carregam dados de corte transversal com moderação.

package main
 
import (
    "context"
    "fmt"
)
 
type ctxKey string
 
const requestIDKey ctxKey = "requestID"
 
func withRequestID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, requestIDKey, id)
}
 
func requestID(ctx context.Context) string {
    v, _ := ctx.Value(requestIDKey).(string)
    return v
}
 
func main() {
    ctx := withRequestID(context.Background(), "req-abc")
    fmt.Println(requestID(ctx))
}

• Use tipos de chave não exportados para evitar colisões entre pacotes.
• Valores são para metadados de escopo de requisição, não parâmetros opcionais.
• Prefira argumentos de função explícitos para dados de negócios.

Relacionado: Valores de Contexto: Quando e Quando Não - disciplina de valores

Exemplos Intermediários

8. O cancelamento filho não para o pai

O cancelamento flui apenas do pai para o filho.

package main
 
import (
    "context"
    "fmt"
)
 
func main() {
    parent, parentCancel := context.WithCancel(context.Background())
    defer parentCancel()
 
    child, childCancel := context.WithCancel(parent)
    defer childCancel()
 
    childCancel()
    fmt.Println("erro pai:", parent.Err())
    fmt.Println("erro filho:", child.Err())
}

• Chamar childCancel() define child.Err() como context.Canceled.
• O pai permanece ativo até que parentCancel() seja executado.
• Projete APIs para que o upstream possua o ciclo de vida raiz.

Relacionado: Antipadrões de Mau Uso de Contexto - erros de ciclo de vida

9. Derivando um timeout mais curto de um pai

Cada camada deve subtrair a sobrecarga do orçamento restante.

package main
 
import (
    "context"
    "fmt"
    "time"
)
 
func callDownstream(parent context.Context) error {
    ctx, cancel := context.WithTimeout(parent, 50*time.Millisecond)
    defer cancel()
 
    select {
    case <-time.After(200 * time.Millisecond):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}
 
func main() {
    parent, cancel := context.WithTimeout(context.Background(), 1*time.Second)
    defer cancel()
    fmt.Println(callDownstream(parent))
}

• Timeouts filhos devem ser menores ou iguais ao tempo restante do pai.
• Middleware frequentemente corta milissegundos para serialização antes de chamar serviços.
• Registre DeadlineExceeded na camada que definiu o timeout mais curto para facilitar a depuração.

Relacionado: Deadlines e Timeouts Entre Limites de Serviço - orçamentos de salto

10. context.WithCancelCause (Go 1.20+)

Anexe uma razão ao cancelamento para erros mais claros.

package main
 
import (
    "context"
    "errors"
    "fmt"
)
 
func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil)
 
    cause := errors.New("falha na validação upstream")
    cancel(cause)
 
    fmt.Println(context.Cause(ctx))
}

• WithCancelCause emparelha com context.Cause(ctx) para observabilidade.
• Use causas para razões de parada específicas do domínio, não strings genéricas de log.
• Ainda retorne ctx.Err() nas fronteiras da API, a menos que os chamadores precisem da causa.

Relacionado: Testando Código Que Aceita context.Context - afirmando causas de cancelamento

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, 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).