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étodo | Significado |
|---|---|
Done() <-chan struct{} | fechado quando o contexto é cancelado ou o prazo passa |
Err() error | nil enquanto ativo; context.Canceled ou context.DeadlineExceeded depois |
Deadline() (time.Time, bool) | quando o trabalho deve terminar, se houver prazo |
Value(key any) any | dados 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:
- 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.
- 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
trueao comparar os dois prazos.
Diagram: A request context tree
3. Os construtores
| Construtor | Use para | Desde |
|---|---|---|
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ário | 1.7 |
WithValue(parent, key, v) | dados do escopo da requisição | 1.7 |
WithCancelCause(parent) e Cause(ctx) | registrar por que um contexto foi cancelado | 1.20 |
WithTimeoutCause / WithDeadlineCause | nomear o motivo de um timeout | 1.21 |
WithoutCancel(parent) | manter os valores mas descartar o cancelamento | 1.21 |
AfterFunc(ctx, f) | rodar f na própria goroutine quando ctx terminar | 1.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:
- Chamadas bloqueantes que recebem um contexto. Use-as:
http.NewRequestWithContext,db.QueryContext,exec.CommandContext,net.Dialer.DialContext,sem.Acquire(ctx, n). Elas devolvemctx.Err()cedo. - Laços e esperas que você mesmo escreve. Ponha
ctx.Done()noselect:
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.
- Trabalho longo de CPU. Verifique
ctx.Err()a cada tantas iterações; um laço apertado nunca chega a umselectsozinho.
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
context.Canceled: alguém chamoucancel(). Em um servidor isso geralmente significa que o cliente desconectou. Normalmente não é um bug seu e muitas vezes não vale um log de erro.context.DeadlineExceeded: um timeout ou prazo passou. Pode indicar lentidão e vale uma métrica.
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:
- Trabalho que precisa sobreviver à resposta (enviar e-mail, log de auditoria) precisa de
context.WithoutCancel(r.Context())mais seu próprio timeout, ou de uma fila em segundo plano. Usarr.Context()em uma goroutine iniciada pelo handler a cancela assim que o handler retorna. - Um contexto não substitui timeouts do servidor. Defina
ReadHeaderTimeout,IdleTimeoute os outros emhttp.Server, e defina um timeout emhttp.Clientou em cada requisição, porquehttp.DefaultClientnão tem nenhum.
9. Passando contextos
- Ponha
ctx context.Contextprimeiro e chame-o dectx. - Não o guarde em uma struct. Um contexto tem o escopo de uma chamada; guardado em uma struct ele sobrevive a essa chamada e esconde o que governa. (
http.Requesté uma exceção histórica.) - Nunca passe
nil. Se ainda não tem um, usecontext.TODO(), que ferramentas conseguem encontrar depois. - Não passe um contexto só para carregar uma função cancel; cancele de onde ele foi criado.
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
- Não chamar
cancel(vaza timers e filhos). - Iniciar uma goroutine com
r.Context()que precisa sobreviver à requisição. - Pôr parâmetros opcionais, configuração ou handles de banco em valores de contexto.
- Usar chaves
stringouint, que colidem entre pacotes. - Laços e envios que nunca olham
ctx.Done(). - Tratar
context.Canceledcomo erro do servidor. - Guardar o contexto em uma struct e reutilizá-lo entre chamadas.
- Passar
nil, oucontext.Background()no fundo de uma cadeia de chamadas onde havia um contexto disponível. - Depender do contexto como único timeout, sem timeouts de cliente ou servidor.
12. O que mencionar em uma entrevista
- Um contexto é um nó imutável de uma árvore que carrega cancelamento, prazo e valores; o cancelamento vai dos pais para os filhos.
- O cancelamento é cooperativo: o código precisa fazer select em
Done()ou chamar APIs que aceitam contexto. - Sempre
defer cancel(); ogo vetreporta os esquecidos. CanceledversusDeadlineExceeded,errors.Is, eCausepara o motivo.- Valores são para dados do escopo da requisição com tipos de chave privados, não para parâmetros.
WithoutCancelpara trabalho que precisa sobreviver à requisição;AfterFuncpara callbacks de limpeza.
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
- The Go Authors, package context.
- Sameer Ajmani, Go Concurrency Patterns: Context e Contexts and structs.
- The Go Authors, Pipelines and cancellation e package errgroup.
- The Go Authors, notas de versão do Go 1.20 e do Go 1.21 (
WithCancelCause,WithoutCancel,AfterFunc).
Pratique este tema: Go