Solução de Problemas de Go Context Timeout: 7 causas raiz de context deadline exceeded e Controle de Precisão
编程语言
Seu microsserviço foi esmagado por context deadline exceeded novamente
3 da manhã, o canal de alertas explode — latência P99 do serviço de pedidos dispara para 5 segundos, o gateway upstream relata context deadline exceeded sem parar. Você aumenta o timeout de 3s para 5s, de 5s para 10s, mas está apenas adiando o problema. Pior ainda, você descobre milhares de vazamentos de goroutine, o uso de memória sobe constantemente, até ocorrer um OOM kill.
O controle de timeout do Go Context não é apenas adicionar context.WithTimeout. Quanto deve ser o timeout? Como a cancelamento se propaga? Como as goroutines filhas são limpas? Como os timeouts em cascata na cadeia de microsserviços se comportam? Sem entender isso, context deadline exceeded vai assombrá-lo repetidamente.
Este artigo parte de 7 causas raiz e guia você através do pipeline completo configuração de timeout → propagação de cancelamento → limpeza de goroutine → controle de cascata de microsserviços.
Conceitos essenciais do Context
| Conceito | Descrição |
|---|---|
| context.Context | Interface da biblioteca padrão do Go que transporta deadline, sinal de cancelamento e valores com escopo de requisição |
| context.WithTimeout | Cria um Context filho com timeout, cancela automaticamente após a duração |
| context.WithDeadline | Cria um Context filho com deadline absoluto |
| context.WithCancel | Cria um Context filho cancelável manualmente |
| context.WithoutCancel | Go 1.21+, cria um Context filho não afetado pelo cancelamento do pai |
| context.AfterFunc | Go 1.21+, executa automaticamente um callback após o cancelamento do Context |
| context.Cause | Go 1.20+, recupera a causa raiz do cancelamento do Context |
Mecanismo de propagação de timeout
Request Chain:
Gateway(5s) → OrderService(3s) → PaymentService(2s) → InventoryService(1s)
Propagation Rules:
1. Child Context timeout cannot exceed parent Context
2. Parent Context cancellation auto-cancels all children
3. After timeout, Done channel closes, Err returns deadline exceeded
4. Cancellation is idempotent, multiple Cancel() calls won't error
Análise do problema: 7 causas raiz de context deadline exceeded
- Timeout muito curto: Não considerou flutuação de rede e carga do serviço, latência P99 excede o limite de timeout
- Context não propagado: A função aceita Context mas o chamador passa
context.TODO()oucontext.Background() - Vazamento de goroutine: Após o cancelamento do Context, as goroutines filhas não verificam o canal Done, continuam executando
- Amplificação em cascata do timeout: Cada camada de microsserviço define timeout, o timeout total é comprimido camada por camada
- Cliente HTTP não configurado:
http.Client{}não tem timeout por padrão, requisições podem bloquear indefinidamente - Consulta de banco de dados sem timeout: Tempo de execução SQL não controlado, consultas longas arrastam toda a requisição
- Sobrescrita de Context: Função interna cria novo Context com
context.Background(), perdendo o sinal de cancelamento externo
Passo a passo: Implementação de controle de timeout de precisão
Passo 1: Controle de timeout básico
package main
import (
"context"
"fmt"
"time"
)
func fetchUserData(ctx context.Context, userID string) (string, error) {
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
resultCh := make(chan string, 1)
errCh := make(chan error, 1)
go func() {
data, err := queryDatabase(ctx, userID)
if err != nil {
errCh <- err
return
}
resultCh <- data
}()
select {
case data := <-resultCh:
return data, nil
case err := <-errCh:
return "", err
case <-ctx.Done():
return "", fmt.Errorf("fetch user data: %w", ctx.Err())
}
}
func queryDatabase(ctx context.Context, userID string) (string, error) {
select {
case <-time.After(2 * time.Second):
return fmt.Sprintf("user_data_%s", userID), nil
case <-ctx.Done():
return "", ctx.Err()
}
}
func main() {
ctx := context.Background()
data, err := fetchUserData(ctx, "12345")
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Data: %s\n", data)
}
Passo 2: Propagação de timeout na cadeia de microsserviços
package middleware
import (
"context"
"time"
)
type TimeoutConfig struct {
GatewayTimeout time.Duration
OrderServiceTimeout time.Duration
PaymentTimeout time.Duration
InventoryTimeout time.Duration
}
func DefaultTimeoutConfig() *TimeoutConfig {
return &TimeoutConfig{
GatewayTimeout: 5 * time.Second,
OrderServiceTimeout: 3 * time.Second,
PaymentTimeout: 2 * time.Second,
InventoryTimeout: 1 * time.Second,
}
}
type contextKey string
const timeoutKey contextKey = "timeout_config"
func WithTimeoutConfig(ctx context.Context, cfg *TimeoutConfig) context.Context {
return context.WithValue(ctx, timeoutKey, cfg)
}
func TimeoutConfigFromContext(ctx context.Context) *TimeoutConfig {
if cfg, ok := ctx.Value(timeoutKey).(*TimeoutConfig); ok {
return cfg
}
return DefaultTimeoutConfig()
}
func DeriveServiceTimeout(ctx context.Context, serviceTimeout time.Duration) (context.Context, context.CancelFunc) {
if deadline, ok := ctx.Deadline(); ok {
remaining := time.Until(deadline)
if remaining < serviceTimeout {
return context.WithDeadline(ctx, deadline)
}
}
return context.WithTimeout(ctx, serviceTimeout)
}
Passo 3: Prevenção de vazamento de goroutine
package pool
import (
"context"
"sync"
)
type WorkerPool struct {
maxWorkers int
tasks chan func() error
wg sync.WaitGroup
}
func NewWorkerPool(maxWorkers, queueSize int) *WorkerPool {
return &WorkerPool{
maxWorkers: maxWorkers,
tasks: make(chan func() error, queueSize),
}
}
func (p *WorkerPool) Start(ctx context.Context) {
for i := 0; i < p.maxWorkers; i++ {
p.wg.Add(1)
go func(workerID int) {
defer p.wg.Done()
for {
select {
case <-ctx.Done():
return
case task, ok := <-p.tasks:
if !ok {
return
}
task()
}
}
}(i)
}
}
func (p *WorkerPool) Submit(ctx context.Context, task func() error) error {
select {
case p.tasks <- task:
return nil
case <-ctx.Done():
return ctx.Err()
default:
return fmt.Errorf("task queue is full")
}
}
func (p *WorkerPool) Stop() {
close(p.tasks)
p.wg.Wait()
}
Passo 4: Configuração de timeout do cliente HTTP
package httpclient
import (
"context"
"net"
"net/http"
"time"
)
type ClientConfig struct {
Timeout time.Duration
DialTimeout time.Duration
TLSHandshakeTimeout time.Duration
MaxIdleConns int
MaxIdleConnsPerHost int
IdleConnTimeout time.Duration
}
func DefaultClientConfig() *ClientConfig {
return &ClientConfig{
Timeout: 10 * time.Second,
DialTimeout: 3 * time.Second,
TLSHandshakeTimeout: 3 * time.Second,
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10,
IdleConnTimeout: 90 * time.Second,
}
}
func NewClient(cfg *ClientConfig) *http.Client {
transport := &http.Transport{
DialContext: (&net.Dialer{
Timeout: cfg.DialTimeout,
KeepAlive: 30 * time.Second,
}).DialContext,
TLSHandshakeTimeout: cfg.TLSHandshakeTimeout,
MaxIdleConns: cfg.MaxIdleConns,
MaxIdleConnsPerHost: cfg.MaxIdleConnsPerHost,
IdleConnTimeout: cfg.IdleConnTimeout,
ResponseHeaderTimeout: cfg.Timeout,
}
return &http.Client{
Timeout: cfg.Timeout,
Transport: transport,
}
}
func DoRequest(ctx context.Context, client *http.Client, req *http.Request) (*http.Response, error) {
req = req.WithContext(ctx)
resp, err := client.Do(req)
if err != nil {
if ctx.Err() != nil {
return nil, fmt.Errorf("request cancelled: %w", ctx.Err())
}
return nil, fmt.Errorf("request failed: %w", err)
}
return resp, nil
}
Passo 5: Timeout de consulta de banco de dados
package db
import (
"context"
"database/sql"
"time"
)
type DBOption struct {
MaxOpenConns int
MaxIdleConns int
ConnMaxLifetime time.Duration
ConnMaxIdleTime time.Duration
QueryTimeout time.Duration
}
func DefaultDBOption() *DBOption {
return &DBOption{
MaxOpenConns: 25,
MaxIdleConns: 5,
ConnMaxLifetime: 5 * time.Minute,
ConnMaxIdleTime: 1 * time.Minute,
QueryTimeout: 3 * time.Second,
}
}
func OpenDB(driverName, dataSource string, opt *DBOption) (*sql.DB, error) {
db, err := sql.Open(driverName, dataSource)
if err != nil {
return nil, err
}
db.SetMaxOpenConns(opt.MaxOpenConns)
db.SetMaxIdleConns(opt.MaxIdleConns)
db.SetConnMaxLifetime(opt.ConnMaxLifetime)
db.SetConnMaxIdleTime(opt.ConnMaxIdleTime)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
return nil, fmt.Errorf("ping database: %w", err)
}
return db, nil
}
func QueryWithTimeout(ctx context.Context, db *sql.DB, query string, args ...any) (*sql.Rows, error) {
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
if ctx.Err() == context.DeadlineExceeded {
return nil, fmt.Errorf("query timeout after 3s: %w", err)
}
return nil, err
}
return rows, nil
}
Guia de armadilhas
Armadilha 1: Armazenar Context em um Struct
// ❌ Wrong: storing Context in a struct
type UserService struct {
ctx context.Context
}
func (s *UserService) GetUser(id string) error {
return s.queryDatabase(s.ctx, id)
}
// ✅ Correct: pass Context as function parameter
type UserService struct {
db *sql.DB
}
func (s *UserService) GetUser(ctx context.Context, id string) error {
return s.queryDatabase(ctx, id)
}
Armadilha 2: Esquecer de chamar Cancel causa vazamento
// ❌ Wrong: cancel from WithTimeout not called
ctx, _ := context.WithTimeout(parentCtx, 5*time.Second)
result, err := doWork(ctx)
// ✅ Correct: always defer cancel
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
defer cancel()
result, err := doWork(ctx)
Armadilha 3: Sobrescrever o Context pai com context.Background()
// ❌ Wrong: inner function uses Background, losing cancellation signal
func processOrder(ctx context.Context, orderID string) error {
innerCtx := context.Background()
return paymentService.charge(innerCtx, orderID)
}
// ✅ Correct: pass parent Context to maintain cancellation propagation
func processOrder(ctx context.Context, orderID string) error {
return paymentService.charge(ctx, orderID)
}
Armadilha 4: A goroutine não verifica o canal Done
// ❌ Wrong: goroutine doesn't respond to cancellation
go func() {
result := heavyComputation()
resultCh <- result
}()
// ✅ Correct: check Context cancellation inside goroutine
go func() {
result, err := heavyComputationWithCtx(ctx)
if err != nil {
return
}
select {
case resultCh <- result:
case <-ctx.Done():
}
}()
Armadilha 5: Conflito entre timeout do cliente HTTP e do Transport
// ❌ Wrong: Client.Timeout and Transport timeout overlap, may timeout early
client := &http.Client{
Timeout: 5 * time.Second,
Transport: &http.Transport{
ResponseHeaderTimeout: 5 * time.Second,
},
}
// ✅ Correct: Client.Timeout controls overall, Transport only connection phase
client := &http.Client{
Timeout: 10 * time.Second,
Transport: &http.Transport{
DialContext: (&net.Dialer{Timeout: 3 * time.Second}).DialContext,
TLSHandshakeTimeout: 3 * time.Second,
},
}
Solução de problemas de erros
| # | Mensagem de erro | Causa | Solução |
|---|---|---|---|
| 1 | context deadline exceeded |
Operação excedeu o timeout do Context | Verificar se o timeout é razoável, otimizar consultas/requisições lentas |
| 2 | context canceled |
Context cancelado manualmente (cancel() chamado) | Verificar a fonte do cancelamento, confirmar se é comportamento esperado |
| 3 | grpc: context canceled |
Context cancelado durante chamada gRPC | Verificar timeout do cliente e tempo de processamento do servidor |
| 4 | net/http: request canceled |
Requisição HTTP cancelada durante transferência | Verificar Client.Timeout e timeout do Context |
| 5 | driver: bad connection |
Conexão do BD expirou durante consulta | Aumentar ConnMaxLifetime, verificar timeout do QueryContext |
| 6 | i/o timeout |
Operação de I/O de rede expirou | Aumentar DialTimeout, verificar conectividade de rede |
| 7 | TLS handshake timeout |
Handshake TLS expirou | Aumentar TLSHandshakeTimeout, verificar cadeia de certificados |
| 8 | connection reset by peer |
O par fechou a conexão após o timeout | Verificar configurações de timeout do par, garantir que ambos os lados concordem |
| 9 | goroutine leak detected |
Goroutine não saiu após o cancelamento do Context | Verificar ctx.Done() nas goroutines, garantir saída oportuna |
| 10 | queue is full |
Fila de requisições cheia, envio falhou | Aumentar capacidade da fila, adicionar workers, adicionar contrapressão |
Otimização avançada
1. Controle de timeout adaptativo
package adaptive
import (
"context"
"sort"
"sync"
"time"
)
type AdaptiveTimeout struct {
mu sync.Mutex
history []time.Duration
maxHistory int
percentile float64
minTimeout time.Duration
maxTimeout time.Duration
safetyMargin float64
}
func NewAdaptiveTimeout(percentile float64, minTimeout, maxTimeout time.Duration) *AdaptiveTimeout {
return &AdaptiveTimeout{
history: make([]time.Duration, 0, 100),
maxHistory: 100,
percentile: percentile,
minTimeout: minTimeout,
maxTimeout: maxTimeout,
safetyMargin: 1.5,
}
}
func (a *AdaptiveTimeout) Record(duration time.Duration) {
a.mu.Lock()
defer a.mu.Unlock()
a.history = append(a.history, duration)
if len(a.history) > a.maxHistory {
a.history = a.history[1:]
}
}
func (a *AdaptiveTimeout) Timeout() time.Duration {
a.mu.Lock()
defer a.mu.Unlock()
if len(a.history) == 0 {
return a.maxTimeout
}
sorted := make([]time.Duration, len(a.history))
copy(sorted, a.history)
sort.Slice(sorted, func(i, j int) bool { return sorted[i] < sorted[j] })
idx := int(float64(len(sorted)) * a.percentile)
if idx >= len(sorted) {
idx = len(sorted) - 1
}
timeout := time.Duration(float64(sorted[idx]) * a.safetyMargin)
if timeout < a.minTimeout {
timeout = a.minTimeout
}
if timeout > a.maxTimeout {
timeout = a.maxTimeout
}
return timeout
}
func (a *AdaptiveTimeout) Context(ctx context.Context) (context.Context, context.CancelFunc) {
return context.WithTimeout(ctx, a.Timeout())
}
2. Middleware de propagação de timeout
package middleware
import (
"context"
"fmt"
"strconv"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/metadata"
)
const timeoutMetadataKey = "x-request-timeout-ms"
func TimeoutPropagationInterceptor() grpc.UnaryClientInterceptor {
return func(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
if deadline, ok := ctx.Deadline(); ok {
remainingMs := time.Until(deadline).Milliseconds()
if remainingMs > 0 {
md, _ := metadata.FromOutgoingContext(ctx)
md = md.Copy()
md.Set(timeoutMetadataKey, fmt.Sprintf("%d", remainingMs))
ctx = metadata.NewOutgoingContext(ctx, md)
}
}
return invoker(ctx, method, req, reply, cc, opts...)
}
}
func TimeoutPropagationServerInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return handler(ctx, req)
}
values := md.Get(timeoutMetadataKey)
if len(values) == 0 {
return handler(ctx, req)
}
remainingMs, err := strconv.ParseInt(values[0], 10, 64)
if err != nil || remainingMs <= 0 {
return handler(ctx, req)
}
remaining := time.Duration(remainingMs) * time.Millisecond
if deadline, ok := ctx.Deadline(); ok {
if time.Until(deadline) < remaining {
remaining = time.Until(deadline)
}
}
ctx, cancel := context.WithTimeout(ctx, remaining)
defer cancel()
return handler(ctx, req)
}
}
3. Detecção de vazamento de goroutine
package leak
import (
"context"
"log"
"runtime"
"time"
)
type LeakDetector struct {
checkInterval time.Duration
threshold int
}
func NewLeakDetector(checkInterval time.Duration, threshold int) *LeakDetector {
return &LeakDetector{
checkInterval: checkInterval,
threshold: threshold,
}
}
func (d *LeakDetector) Start(ctx context.Context) {
ticker := time.NewTicker(d.checkInterval)
defer ticker.Stop()
var prevGoroutines int
var growthCount int
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
current := runtime.NumGoroutine()
if current > d.threshold {
log.Printf("[LEAK WARNING] goroutine count %d exceeds threshold %d", current, d.threshold)
}
growth := current - prevGoroutines
if growth > 10 {
growthCount++
if growthCount >= 3 {
log.Printf("[LEAK ALERT] goroutine count growing continuously: %d -> %d (%d consecutive growths)", prevGoroutines, current, growthCount)
}
} else {
growthCount = 0
}
prevGoroutines = current
}
}
}
Análise comparativa
| Dimensão | context.WithTimeout | context.WithDeadline | context.WithCancel | time.After | select+timer |
|---|---|---|---|---|---|
| Precisão de timeout | Milissegundo | Tempo absoluto | Sem timeout | Milissegundo | Milissegundo |
| Propagação de cancelamento | ✅ Automática | ✅ Automática | ✅ Manual | ❌ Nenhuma | ❌ Nenhuma |
| Seguro para goroutine | ✅ | ✅ | ✅ | ⚠️ Risco de vazamento | ⚠️ Risco de vazamento |
| Cascata de microsserviços | ✅ | ✅ | ✅ | ❌ | ❌ |
| Propagação de valores | ✅ | ✅ | ✅ | ❌ | ❌ |
| Sobrecarga de recursos | Baixa | Baixa | Baixa | Alta (vazamento) | Média |
| Caso de uso | Timeout geral | Tarefas agendadas | Cancelamento manual | Espera simples | Timeout local |
Resumo:
context deadline exceedednão se resolve "aumentando o timeout." Entre as 7 causas raiz, as mais perigosas são vazamentos de goroutine e sobrescrita de Context — o primeiro "sangra" lentamente seu serviço até o OOM, o segundo torna o controle de timeout inútil. Práticas de timeout em microsserviços Go 2026: 1) Definir timeout global no gateway, propagar o tempo restante via metadata; 2) Cada camada de serviço usaDeriveServiceTimeoutpegando min(timeout próprio, tempo restante); 3) Todas as goroutines devem verificarctx.Done(); 4) Usar timeout adaptativo em vez de timeout estático; 5) Implantar detecção de vazamento de goroutine. Lembre-se: timeout não é sobre ser mais longo, é sobre ser preciso.
Ferramentas online recomendadas
- Formatador JSON: /pt-BR/json/format
- Codificação/Decodificação Base64: /pt-BR/encode/base64
- Calculadora Hash: /pt-BR/encode/hash
- Decodificador JWT: /pt-BR/encode/jwt-decode
Experimente estas ferramentas executadas localmente no navegador — nenhum cadastro necessário →
#Go#Context#超时控制#goroutine#微服务#2026#并发编程