Melhores Práticas Avançadas de Concorrência

Padrões para APIs e serviços concorrentes resilientes.

Estas regras destilam a seção de concorrência avançada: paralelismo limitado, propagação de cancelamento, encerramento limpo e prova de segurança com testes e perfis.

Como Usar Esta Lista

• Aplique ao projetar um novo serviço concorrente ou revisar um caminho crítico antes do lançamento
• Use Nível A em todo PR que toque em goroutines ou canais
• Promova para Nível B após o primeiro incidente de produção ou teste de carga
• Emparelhe com Evitando Vazamentos de Goroutine e Deadlocks de Canal durante incidentes
• Revise quando as versões menores do Go alterarem o comportamento do scheduler ou de x/sync

A - Limitado e protegido

• Limite o I/O paralelo de saída com semáforo ou pool. Corresponda os limites a MaxOpenConns do banco de dados e às cotas de APIs parceiras.
• Limite a taxa de início de requisições na borda. Use token bucket antes que o trabalho entre em um fan-out caro.
• Descarte carga com erros explícitos quando as filas estiverem cheias. Retorne 503 ou erros retryable em vez de buffer ilimitado.
• Dimensiona buffers de canal deliberadamente. Documente por que cada profundidade de buffer existe; evite padrões de "9999".
• Faça fan-out apenas quando a capacidade downstream suportar. Meça 429s e latência antes de aumentar o paralelismo.

B - Contexto e cancelamento

• Passe context.Context como o primeiro parâmetro após o receiver. O cancelamento se propaga através de QueryContext, clientes gRPC e HTTP.
• Use r.Context() em manipuladores HTTP. Vincule o trabalho do manipulador à desconexão do cliente e ao encerramento do servidor.
• Derive o contexto do errgroup com WithContext. A primeira falha cancela os irmãos que ainda estão fazendo I/O.
• Separe o contexto de jobs em background do contexto de requisição. Workers de cron e outbox cancelam em SIGTERM, não em inatividade do cliente.
• Respeite ctx.Done() em todo loop longo ou retry bloqueante. Nenhuma goroutine deve ignorar o cancelamento por segundos.

C - Estrutura e propriedade

• Documente quem fecha cada canal na wiki da equipe ou em comentários no código. Um remetente fecha; receptores nunca fecham entradas compartilhadas.
• Use pools de workers para streams constantes; errgroup para lotes de uso único. Não misture metáforas sem limites claros.
• Propague erros com errgroup ou structs Result tipadas. Não entre em pânico de goroutines worker.
• Prefira trocas de configuração imutáveis via atomic.Pointer. Leitores carregam snapshots; escritores publicam novas structs.
• Mantenha os estágios do pipeline pequenos e testáveis. Alimente canais fechados em testes unitários para cada estágio.

D - Encerramento e ciclo de vida

• Implemente encerramento HTTP gracioso com timeout. Server.Shutdown e depois cancele o contexto raiz.
• Feche os canais de jobs apenas após os produtores terminarem. Use WaitGroup nos produtores antes de fechar.
• Aguarde os workers antes da saída do processo. WaitGroup, Wait do errgroup, ou Shutdown do pool em main.
• Conecte SIGTERM ao mesmo caminho do encerramento intencional. Kubernetes espera drenagem dentro de terminationGracePeriodSeconds.
• Afirme que a contagem de goroutines retorna ao baseline em testes de integração. Capture vazamentos antes da produção.

E - Observabilidade e verificação

• Execute go test -race em pacotes concorrentes em CI. Bloqueie merge em data races.
• Exporte métricas de tarefas em andamento e profundidade de fila. Alerte sobre crescimento sustentado sem aumento de tráfego.
• Perfilar goroutines sob carga em staging. Endpoint de goroutine pprof antes de grandes lançamentos.
• Teste de carga com latência downstream realista. Mocks ilimitados escondem bugs de backpressure.
• Registre eventos de descarte e limitação de taxa em info com contadores. Operadores precisam de visibilidade ao proteger dependências.

FAQs

Relacionados

• Concorrência em Produção: Padrões Além do Hello Goroutine - visão geral conceitual
• Básico de Concorrência Avançada - padrões executáveis
• Evitando Vazamentos de Goroutine e Deadlocks de Canal - cheat sheet de incidentes
• Melhores Práticas Fundamentais de Concorrência - noções básicas de canais e mutex
• Melhores Práticas do Pacote Contexto - hábitos de cancelamento

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 - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).