Resposta rápida: um cliente HTTP em Go de produção não usa http.DefaultClient. Você cria um *http.Client reutilizável, define Timeout, configura o http.Transport (dial, TLS, response headers, keep-alive, idle conns), propaga context.Context, faz retry só em falhas transitórias e operações idempotentes, e observa erros com logs/métricas. Isso protege goroutines, conexões e latência do seu serviço quando a API externa trava. Combine com circuit breaker, httptrace e context com timeout — não substitua um pelo outro.
Este guia monta o client do zero: defaults perigosos, Transport, retries, headers, testes com httptest, comparação com resty e um checklist de produção. Se você está do outro lado da conexão (servidor), veja middleware em Go, Chi Router e o tutorial de API REST.
Por que DefaultClient quebra em produção
http.DefaultClient parece conveniente:
resp, err := http.Get("https://api.exemplo.com/v1/status")
O problema é estrutural:
| Comportamento | DefaultClient | Client de produção |
|---|---|---|
| Timeout total | 0 (infinito) | Explícito (ex.: 10s) |
| Transport | Global compartilhado | Próprio, afinado |
| Cancelamento | Só se você passar context | Sempre via context |
| Retry | Nenhum | Controlado e idempotente |
| Observabilidade | Manual e fácil de esquecer | Encapsulada no client |
Sem timeout, um fornecedor lento prende a goroutine do request, satura o pool de conexões e eleva a latência de todo o serviço — mesmo endpoints que não chamam essa API. Em backends brasileiros que falam com antifraude, PIX, ERP, CRM e gateways, isso aparece como “o pod congelou” sem panic.
A regra prática: um *http.Client por processo (ou por dependência), criado no bootstrap, injetado nos pacotes que falam com o mundo externo.
Cliente mínimo seguro
package payments
import (
"net"
"net/http"
"time"
)
func NewHTTPClient() *http.Client {
transport := &http.Transport{
Proxy: http.ProxyFromEnvironment,
DialContext: (&net.Dialer{
Timeout: 5 * time.Second,
KeepAlive: 30 * time.Second,
}).DialContext,
ForceAttemptHTTP2: true,
MaxIdleConns: 100,
MaxIdleConnsPerHost: 20,
MaxConnsPerHost: 50,
IdleConnTimeout: 90 * time.Second,
TLSHandshakeTimeout: 5 * time.Second,
ExpectContinueTimeout: 1 * time.Second,
ResponseHeaderTimeout: 10 * time.Second,
}
return &http.Client{
Timeout: 15 * time.Second,
Transport: transport,
}
}
O que cada peça controla:
Client.Timeout: teto absoluto da chamada (dial + TLS + headers + body).DialContext: quanto tempo esperar para abrir TCP.TLSHandshakeTimeout: handshake TLS lento não prende o worker sem limite.ResponseHeaderTimeout: o servidor aceitou a conexão mas não devolveu headers a tempo.MaxIdleConns/MaxIdleConnsPerHost: reuso de keep-alive sem abrir socket novo a cada request.MaxConnsPerHost: teto duro contra stampede em um único host.
Client.Timeout sozinho não substitui os timeouts do Transport: ele cancela a chamada inteira, mas o Transport deixa falhas parciais mais previsíveis e mensagens de erro mais claras.
Context por request
O client compartilhado define o teto. O context do request de entrada (ou do job) define o deadline real:
package payments
import (
"context"
"fmt"
"io"
"net/http"
"time"
)
type Client struct {
baseURL string
http *http.Client
}
func (c *Client) FetchStatus(ctx context.Context, id string) ([]byte, error) {
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/v1/charges/"+id, nil)
if err != nil {
return nil, err
}
req.Header.Set("Accept", "application/json")
req.Header.Set("User-Agent", "golang-com-br-payments/1.0")
resp, err := c.http.Do(req)
if err != nil {
return nil, fmt.Errorf("payments fetch: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) // 1 MiB
if err != nil {
return nil, fmt.Errorf("payments read body: %w", err)
}
if resp.StatusCode >= 400 {
return nil, fmt.Errorf("payments status %d: %s", resp.StatusCode, body)
}
return body, nil
}
Pontos que evitam incidentes:
- Sempre
NewRequestWithContext, nuncahttp.NewRequest+Dosem context. - Limite o tamanho do body (
LimitReader) — resposta gigante também é DoS. - Feche o body sempre (
defer resp.Body.Close()), mesmo em erro de status. - Encapsule a URL base e headers comuns no tipo
Client, não no handler.
Para cancelamento em cascata e timeouts encadeados, o guia de context em Go é o complemento direto.
Retry com backoff — só quando é seguro
Retry mal feito piora o incidente: multiplica carga no fornecedor e duplica efeitos colaterais. A política segura:
| Situação | Retry? |
|---|---|
| Timeout de rede / conexão resetada | Sim, com limite |
| HTTP 408, 429, 502, 503, 504 | Sim, se a operação for idempotente |
| HTTP 400, 401, 403, 404, 422 | Não |
| POST de criação sem chave de idempotência | Não |
| GET, PUT idempotente, DELETE idempotente | Sim, com cuidado |
| Body parcialmente lido / erro depois do commit remoto | Não adivinhe — use idempotency-key |
Esboço mínimo sem biblioteca:
package payments
import (
"context"
"errors"
"io"
"math/rand"
"net"
"net/http"
"strconv"
"time"
)
func (c *Client) doWithRetry(ctx context.Context, req *http.Request, maxAttempts int) (*http.Response, error) {
var lastErr error
for attempt := 1; attempt <= maxAttempts; attempt++ {
// Body precisa ser recriável: use GetBody ou buffer.
if attempt > 1 && req.GetBody != nil {
body, err := req.GetBody()
if err != nil {
return nil, err
}
req.Body = body
}
resp, err := c.http.Do(req)
if err == nil && !retryableStatus(resp.StatusCode) {
return resp, nil
}
if err == nil {
io.Copy(io.Discard, resp.Body)
resp.Body.Close()
lastErr = errors.New("retryable status " + strconv.Itoa(resp.StatusCode))
if ra := resp.Header.Get("Retry-After"); ra != "" {
if sec, parseErr := strconv.Atoi(ra); parseErr == nil {
if err := sleep(ctx, time.Duration(sec)*time.Second); err != nil {
return nil, err
}
continue
}
}
} else {
lastErr = err
if !retryableNetErr(err) {
return nil, err
}
}
if attempt == maxAttempts {
break
}
backoff := time.Duration(1<<uint(attempt-1)) * 100 * time.Millisecond
jitter := time.Duration(rand.Intn(100)) * time.Millisecond
if err := sleep(ctx, backoff+jitter); err != nil {
return nil, err
}
}
return nil, lastErr
}
func retryableStatus(code int) bool {
switch code {
case 408, 429, 500, 502, 503, 504:
return true
default:
return false
}
}
func retryableNetErr(err error) bool {
var netErr net.Error
return errors.As(err, &netErr) && netErr.Timeout()
}
func sleep(ctx context.Context, d time.Duration) error {
t := time.NewTimer(d)
defer t.Stop()
select {
case <-ctx.Done():
return ctx.Err()
case <-t.C:
return nil
}
}
Na prática, muitas equipes preferem uma lib pequena de backoff ou o retry embutido de um wrapper interno. O importante é a política, não a lib. Para filas e workers, o padrão completo de idempotência, retry e DLQ evita duplicar efeitos financeiros. Quando o fornecedor fica ruim de verdade, circuit breaker corta o tráfego — retry sozinho não basta.
Transport: conexões, HTTP/2 e armadilhas
Reutilize o mesmo Transport (via o mesmo *http.Client). Criar http.Client{Transport: &http.Transport{}} por request descarta keep-alive e explode o número de sockets.
Cuidados frequentes:
MaxIdleConnsPerHostbaixo demais — sob carga, Go abre conexões novas sem reuso; suba para 10–64 conforme o host.- Esquecer
IdleConnTimeout— conexões mortas ficam no pool e falham no próximo uso. - Proxy corporativo —
ProxyFromEnvironmentrespeitaHTTP_PROXY/HTTPS_PROXY; em Kubernetes isso às vezes surpreende. - HTTP/2 —
ForceAttemptHTTP2: trueé o padrão moderno; se o fornecedor tiver bug de multiplexação, teste com HTTP/1.1 só nesse host. - TLS custom — mTLS e root CAs vão em
transport.TLSClientConfig; não misture clients com políticas de certificado diferentes no mesmo Transport se os hosts exigem configs distintas. - Redirects —
Client.CheckRedirectlimita saltos; para APIs autenticadas, valide se o Authorization não vaza para outro host.
Para inspecionar DNS, connect, TLS e TTFB em runtime, use httptrace no client de debug — não deixe trace ligado em todo request de produção sem amostragem.
Headers, autenticação e corpos
Padronize no wrapper:
AccepteContent-TypeexplícitosUser-Agentcom nome do serviço e versão (ajuda suporte do fornecedor)Authorizationvia RoundTripper ou middleware interno — não espalhe token em cada handler- Idempotency-Key em POST de pagamento / criação
- Correlation / trace id alinhado ao OpenTelemetry
Para JSON:
req.Header.Set("Content-Type", "application/json")
Encode para um bytes.Buffer, defina req.ContentLength e, se houver retry, configure req.GetBody para reabrir o buffer. Sem GetBody, a segunda tentativa envia body vazio.
resty vs net/http
| Critério | net/http | resty |
|---|---|---|
| Dependência | Biblioteca padrão | Externa |
| Controle fino de Transport | Total | Bom, mas atrás da API fluente |
| Retry / middleware | Você monta | Já vem |
| Testabilidade | Excelente com httptest | Boa |
| Ideal quando | Client estável, política própria | Prototipar rápido / muitos endpoints |
Recomendação para APIs de produção no Brasil: comece com net/http encapsulado. Se o pacote interno crescer demais só por boilerplate, avalie resty ou codegen OpenAPI (oapi-codegen). Evite misturar três clients diferentes no mesmo serviço sem motivo.
Testes com httptest
package payments_test
import (
"context"
"net/http"
"net/http/httptest"
"testing"
"time"
)
func TestFetchStatusTimeout(t *testing.T) {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
time.Sleep(200 * time.Millisecond)
w.WriteHeader(http.StatusOK)
}))
t.Cleanup(srv.Close)
client := &http.Client{Timeout: 50 * time.Millisecond}
ctx := context.Background()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL, nil)
if err != nil {
t.Fatal(err)
}
_, err = client.Do(req)
if err == nil {
t.Fatal("esperava timeout")
}
}
Cubra também:
- status 429 com
Retry-After - body maior que o limite
- cancelamento via
context.WithCancel - retry que eventualmente sucede
- erro 4xx sem retry
O guia de mocks e httptest detalha a fronteira entre fake HTTP e mock de interface.
Observabilidade mínima
Sem telemetria, timeout vira “está lento” no Slack. Instrumente por dependência:
- contador de requests por host + status
- histograma de latência (dial vs total, se possível)
- contador de retries e de circuit open
- log estruturado com
slog(guia de slog) incluindourl_host,method,attempt,err
Não logue Authorization, cookies nem bodies com PII. Em pagamentos, trate payloads como sensíveis por padrão — o panorama de Go em fintechs reforça idempotência e auditoria além do client.
Checklist de produção
- Nenhum uso de
http.DefaultClient/http.Get/http.Postno caminho quente -
*http.Clientcriado uma vez, comTimeout> 0 -
Transportpróprio com dial, TLS, response header e idle conns -
NewRequestWithContextem todas as chamadas - Body limitado na leitura;
Closegarantido - Retry só para erros transitórios + operações idempotentes
- Backoff com jitter e respeito a
Retry-After - Circuit breaker nas dependências críticas
- User-Agent e correlation id padrão
- Testes httptest para timeout, 429 e cancelamento
- Métricas e logs sem vazar segredo
Perguntas frequentes
Devo usar http.DefaultClient em produção?
Não. Ele não tem timeout e compartilha Transport global. Crie um *http.Client com Timeout e Transport afinado, e reutilize no processo. DefaultClient é aceitável em scripts one-shot, não em API ou worker.
Qual timeout configurar no http.Client?
Use um teto no Client (por exemplo 5–15s conforme o SLA) e timeouts parciais no Transport (DialContext, TLSHandshakeTimeout, ResponseHeaderTimeout). O context do request pode apertar ainda mais o deadline. Timeout zero = espera infinita.
Como fazer retry seguro em cliente HTTP Go?
Repita só falhas transitórias (timeout de rede, 429, 5xx) em operações idempotentes. Exija idempotency-key para POST de efeito colateral. Backoff exponencial com jitter, limite de tentativas, Retry-After e cancelamento via context. Some circuit breaker quando o fornecedor cai de verdade.
Preciso de resty ou o net/http basta?
net/http basta na maioria dos clients de produção. resty reduz boilerplate se o time quer API fluente e retry pronto. Se você já tem um pacote interno claro, a dependência extra raramente se justifica.
Como testar um cliente HTTP em Go?
Suba httptest.NewServer, simule latência, 429, body enorme e cancelamento de context. Reserve chamadas reais para testes de contrato em sandbox. Evite mockar Do com framework se um servidor fake cobre o comportamento.
Conclusão
Cliente HTTP em Go é infraestrutura, não detalhe de sintaxe. Timeout, Transport, context, retry idempotente e observabilidade separam um serviço que sobrevive a um fornecedor instável de um serviço que cai junto. Encapsule o client, teste com httptest e combine com circuit breaker — em vez de espalhar http.Get pelos handlers.
Para seguir: circuit breaker, httptrace, context e cancelamento, idempotência e DLQ, rate limiting e OpenTelemetry. Se a meta é backend no mercado brasileiro, acompanhe as vagas Go e o guia de salários.