CS Fundamentals Trainer · Guias

Context em Go: cancelamento, prazos, valores e causas

Como usar o pacote context corretamente: os quatro métodos, a árvore de contextos derivados, todos os construtores, incluindo WithCancelCause, WithoutCancel e AfterFunc, por que chamar cancel, como respeitar o cancelamento em laços e chamadas bloqueantes, Canceled contra DeadlineExceeded, valores de requisição, servidores HTTP, orçamentos de retentativa e os erros comuns.

9 min de leitura

Todo serviço Go que chama um banco de dados, outro serviço ou uma função lenta acaba tendo de responder a duas perguntas: "quanto tempo estou disposto a esperar?" e "o que interrompe este trabalho quando quem chamou foi embora?". O pacote context é a resposta padrão. Ele é pequeno, mas suas regras são fáceis de errar, e os erros (timers vazados, trabalho que nunca para, valores usados como parâmetros escondidos) só aparecem sob carga. Este guia cobre o que é um contexto, como contextos formam uma árvore, os construtores, incluindo os mais novos, como respeitar o cancelamento, como servidores HTTP o usam, e os padrões e erros que surgem em revisões. As saídas mostradas foram produzidas com Go 1.24.

1. O que é um contexto

context.Context é uma interface com quatro métodos:

MétodoSignificado
Done() <-chan struct{}fechado quando o contexto é cancelado ou o prazo passa
Err() errornil enquanto ativo; context.Canceled ou context.DeadlineExceeded depois
Deadline() (time.Time, bool)quando o trabalho deve terminar, se houver prazo
Value(key any) anydados do escopo da requisição anexados ao contexto

Um contexto é imutável. Você nunca altera um; deriva um novo a partir dele. É isso que o torna seguro para compartilhar entre goroutines.

2. Contextos formam uma árvore

context.Background() é a raiz vazia, usada em main, nos testes e no topo de uma requisição. context.TODO() é a mesma coisa com um recado para quem lê: "ainda não decidi qual contexto pertence aqui". Todos os outros construtores recebem um pai e devolvem um filho.

Duas regras sobre a árvore:

  1. O cancelamento desce, nunca sobe. Cancelar um pai cancela todos os seus filhos. Cancelar um filho não toca no pai nem nos irmãos.
  2. Um filho não sobrevive ao prazo do pai. Um filho criado com timeout de uma hora sob um pai que expira em 20 ms recebe o prazo do pai; o teste imprimiu true ao comparar os dois prazos.

Diagram: A request context tree

3. Os construtores

ConstrutorUse paraDesde
WithCancel(parent)parar o trabalho chamando cancel()1.7
WithTimeout(parent, d) / WithDeadline(parent, t)desistir após uma duração ou em um horário1.7
WithValue(parent, key, v)dados do escopo da requisição1.7
WithCancelCause(parent) e Cause(ctx)registrar por que um contexto foi cancelado1.20
WithTimeoutCause / WithDeadlineCausenomear o motivo de um timeout1.21
WithoutCancel(parent)manter os valores mas descartar o cancelamento1.21
AfterFunc(ctx, f)rodar f na própria goroutine quando ctx terminar1.21

Os mais novos resolvem problemas reais. Err() sozinho não diz o motivo:

ctx, cancel := context.WithCancelCause(context.Background())
cancel(errors.New("shutting down"))
fmt.Println(ctx.Err(), "|", context.Cause(ctx))
// context canceled | shutting down

t, c := context.WithTimeoutCause(context.Background(), 10*time.Millisecond, errors.New("db too slow"))
defer c()
<-t.Done()
fmt.Println(t.Err(), "|", context.Cause(t))
// context deadline exceeded | db too slow

errors.Is(t.Err(), context.DeadlineExceeded) continua verdadeiro, então as verificações existentes seguem funcionando; Cause acrescenta informação por cima.

WithoutCancel é a resposta para "quero registrar auditoria ou fazer uma limpeza depois que a requisição termina, mas isso precisa manter o id de rastreamento". O contexto derivado não tem prazo e nunca é cancelado, mas Value ainda encontra os valores do pai:

wc := context.WithoutCancel(parent)
cancelParent()
fmt.Println(parent.Err(), wc.Err(), wc.Value(key{}))
// context canceled <nil> v

Como ele nunca termina, você é responsável por dar a esse trabalho seu próprio timeout.

4. Sempre chame cancel

WithCancel, WithTimeout e WithDeadline devolvem uma função cancel. Chamá-la libera o timer e remove o filho da lista do pai. Se você esquecer, os recursos ficam até o timeout disparar (ou para sempre no caso de WithCancel). Use o par na mesma linha:

ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()

Chamar cancel depois de o trabalho terminar normalmente é correto e esperado. O go vet tem uma verificação, lostcancel, que reporta caminhos em que ela não é chamada; em um teste ele imprimiu "the cancel function is not used on all paths (possible context leak)". Rode go vet no CI.

5. Respeitando o cancelamento

Um contexto não cancela nada sozinho. Ele só sinaliza, e o código precisa olhar o sinal. Três lugares para olhar:

  1. Chamadas bloqueantes que recebem um contexto. Use-as: http.NewRequestWithContext, db.QueryContext, exec.CommandContext, net.Dialer.DialContext, sem.Acquire(ctx, n). Elas devolvem ctx.Err() cedo.
  2. Laços e esperas que você mesmo escreve. Ponha ctx.Done() no select:
func poll(ctx context.Context, every time.Duration, fn func() error) error {
    t := time.NewTicker(every)
    defer t.Stop()
    for {
        select {
        case <-ctx.Done():
            return context.Cause(ctx)
        case <-t.C:
            if err := fn(); err != nil {
                return err
            }
        }
    }
}

Com timeout de 55 ms e ticker de 10 ms, rodou fn cerca de cinco vezes e devolveu context deadline exceeded.

  1. Trabalho longo de CPU. Verifique ctx.Err() a cada tantas iterações; um laço apertado nunca chega a um select sozinho.

Lembre também dos envios e recebimentos: ch <- v bloqueia para sempre se ninguém lê, então em goroutines que podem ser abandonadas use select { case ch <- v: case <-ctx.Done(): return }. Esta é a principal cura para vazamentos de goroutines.

6. Qual erro eu recebo

Compare com errors.Is, porque as bibliotecas embrulham o erro. Use context.Cause(ctx) quando você registrou um motivo, mas ainda devolva algo que combine com ctx.Err() se quem chama depende disso.

7. Valores

WithValue anexa dados ao contexto. Use-o para dados que viajam com uma requisição por fronteiras de API e que as funções não precisam declarar: id de rastreamento, id da requisição, usuário autenticado, logger com campos da requisição. Não o use para parâmetros opcionais, configuração ou dependências: o compilador não consegue verificá-los, eles se escondem da assinatura da função e deixam os testes mais difíceis de ler.

Defina a chave como um tipo privado para que pacotes não colidam:

type ctxKey struct{}

func WithUser(ctx context.Context, u User) context.Context {
    return context.WithValue(ctx, ctxKey{}, u)
}

func UserFrom(ctx context.Context) (User, bool) {
    u, ok := ctx.Value(ctxKey{}).(User)
    return u, ok
}

A busca sobe a cadeia um pai por vez, então serve para um punhado de valores e é errada como armazenamento geral.

8. Contextos e HTTP

Em um servidor net/http, r.Context() é cancelado quando a conexão do cliente fecha, quando a requisição termina ou quando ServeHTTP retorna. Passe-o a toda chamada que o handler faz, e o trabalho para quando o cliente desiste. Duas consequências:

9. Passando contextos

10. Padrões

Errgroup com contexto compartilhado. errgroup.WithContext devolve um grupo e um contexto que é cancelado na primeira vez que uma tarefa devolve erro (ou quando Wait retorna). As outras tarefas precisam observá-lo. g.SetLimit(n) limita a concorrência.

Timeout por tentativa, prazo para a operação inteira. Derive um contexto curto para cada nova tentativa a partir de um pai mais longo, para que as tentativas não excedam o orçamento total:

ctx, cancel := context.WithTimeout(ctx, 5*time.Second) // whole operation
defer cancel()
for attempt := 0; attempt < 3; attempt++ {
    actx, acancel := context.WithTimeout(ctx, time.Second) // one attempt
    err := call(actx)
    acancel()
    if err == nil || ctx.Err() != nil {
        return err
    }
}

Limpeza no cancelamento. context.AfterFunc(ctx, f) roda f quando ctx termina e devolve uma função stop. Evita iniciar uma goroutine que só espera Done.

11. Erros comuns

  1. Não chamar cancel (vaza timers e filhos).
  2. Iniciar uma goroutine com r.Context() que precisa sobreviver à requisição.
  3. Pôr parâmetros opcionais, configuração ou handles de banco em valores de contexto.
  4. Usar chaves string ou int, que colidem entre pacotes.
  5. Laços e envios que nunca olham ctx.Done().
  6. Tratar context.Canceled como erro do servidor.
  7. Guardar o contexto em uma struct e reutilizá-lo entre chamadas.
  8. Passar nil, ou context.Background() no fundo de uma cadeia de chamadas onde havia um contexto disponível.
  9. Depender do contexto como único timeout, sem timeouts de cliente ou servidor.

12. O que mencionar em uma entrevista

Resumo rápido

Passe ctx primeiro, derive com um timeout e defer cancel(), e faça toda espera dar select em ctx.Done(). O cancelamento desce pela árvore. Use causas para explicar o motivo, valores só para dados da requisição e WithoutCancel quando o trabalho precisa sobreviver à requisição.

Fontes

Pratique este tema: Go

Mais guias