Docs executáveis de Go: Cliente HTTP

Q: Como fazer uma requisição GET em Go?

resp, err := http.Get(url), verifique o err, depois faça defer resp.Body.Close() e leia o corpo com io.ReadAll(resp.Body) ou decodifique-o com json.NewDecoder(resp.Body).Decode(&v). Verifique também resp.StatusCode: um 404 ou 500 não é um erro do http.Get.

Q: Como definir um timeout em uma requisição HTTP em Go?

Crie um cliente com timeout, client := &http.Client{Timeout: 10 * time.Second}, e use-o no lugar de http.Get ou http.DefaultClient, que não têm timeout geral: um servidor que aceita a conexão e nunca responde bloqueia a chamada para sempre. Para um limite por requisição, monte a requisição com http.NewRequestWithContext e um context vindo de context.WithTimeout.

Q: Como enviar uma requisição POST com corpo JSON em Go?

Faça o marshal do valor e depois o envie: body, _ := json.Marshal(v) e http.Post(url, "application/json", bytes.NewReader(body)). Para acrescentar headers como Authorization, monte-a com http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), defina req.Header.Set("Content-Type", "application/json") e envie com client.Do(req).

Q: Por que preciso fechar o resp.Body em Go?

O corpo é um fluxo sobre uma conexão aberta. Fechá-lo devolve a conexão ao pool para ser reutilizada; esquecer vaza conexões e descritores de arquivo até o programa chegar ao limite. Feche-o mesmo quando não for lê-lo, e leia até o fim se quiser que a conexão seja reutilizada.

Uma requisição GET

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

func main() {
	// A local test server stands in for a real API (the editor has no internet access).
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "you asked for %s", r.URL.Path)
	}))
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/status")
	if err != nil {
		fmt.Println("request failed:", err)
		return
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("reading body:", err)
		return
	}
	fmt.Println(resp.StatusCode, resp.Header.Get("Content-Type"))
	fmt.Println(string(body))
}

Todos os exemplos desta página iniciam o seu próprio servidor com httptest.NewServer e o chamam por uma conexão TCP real em localhost. Troque srv.URL por um endereço real como https://api.example.com e o código do cliente continua igual.

As três regras visíveis aqui:

Verifique o err primeiro. Ele reporta falhas em obter qualquer resposta: erros de DNS, conexões recusadas, timeouts, problemas de TLS.
defer resp.Body.Close() logo depois da verificação do erro. O corpo mantém a conexão aberta. Um corpo não fechado vaza a conexão.
Leia ou decodifique o corpo. io.ReadAll para texto, json.NewDecoder(resp.Body).Decode(&v) para JSON.

Códigos de status não são erros

http.Get devolve err == nil para qualquer resposta que o servidor envie, incluindo 404 e 500. Você precisa verificar o status por conta própria:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func getUser(baseURL string, id int) (User, error) {
	resp, err := http.Get(fmt.Sprintf("%s/users/%d", baseURL, id))
	if err != nil {
		return User{}, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		// Read a little of the body: APIs usually explain the error there.
		msg, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
		return User{}, fmt.Errorf("get user %d: %s: %s", id, resp.Status, bytes.TrimSpace(msg))
	}

	var u User
	if err := json.NewDecoder(resp.Body).Decode(&u); err != nil {
		return User{}, fmt.Errorf("decode user %d: %w", id, err)
	}
	return u, nil
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		if r.PathValue("id") != "1" {
			http.Error(w, "no such user", http.StatusNotFound)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprint(w, `{"id": 1, "name": "Grace"}`)
	})
	srv := httptest.NewServer(mux)
	defer srv.Close()

	fmt.Println(getUser(srv.URL, 1))
	fmt.Println(getUser(srv.URL, 2))
}

io.LimitReader limita quanto de um corpo de erro você lê, para que um servidor que se comporta mal não faça você carregar megabytes em uma mensagem de erro. Muitas APIs devolvem 201, 202 ou 204 em caso de sucesso; verifique resp.StatusCode >= 200 && resp.StatusCode < 300 quando qualquer 2xx servir.

Timeouts: nunca use o cliente padrão para tráfego real

http.Get, http.Post e http.DefaultClient não têm timeout geral (o transporte padrão só limita a conexão e o handshake TLS). Um servidor que aceita a conexão e nunca responde bloqueia a sua goroutine para sempre. Crie o seu próprio cliente:

package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		select {
		case <-time.After(2 * time.Second):
		case <-r.Context().Done(): // stop when the client gives up
		}
	}))
	defer slow.Close()

	client := &http.Client{Timeout: 100 * time.Millisecond}

	start := time.Now()
	_, err := client.Get(slow.URL)
	fmt.Println("gave up quickly:", time.Since(start) < time.Second)

	var netErr net.Error
	if errors.As(err, &netErr) && netErr.Timeout() {
		fmt.Println("timeout error:", netErr.Timeout())
	}
}

Client.Timeout cobre a troca inteira: conexão, redirecionamentos e leitura do corpo. O erro que ele devolve é um *url.Error que informa Timeout() == true, e o errors.As o encontra por meio da interface net.Error. Crie um cliente e reutilize-o em todo lugar; um http.Client é seguro para uso concorrente. O pool de conexões fica no Transport dele, não no Client: um http.Client{} novo por requisição ainda compartilha o http.DefaultTransport e o seu pool, mas um http.Transport novo por requisição começa com um pool vazio toda vez.

Requisições com context e headers

http.NewRequestWithContext monta uma requisição que você pode personalizar antes de enviar com client.Do. O context dá um prazo ou um cancelamento por requisição, além do timeout do cliente, e liga as chamadas de saída ao tempo de vida de uma requisição de entrada em um servidor.

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"net/url"
	"time"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "auth=%q agent=%q q=%q page=%q",
			r.Header.Get("Authorization"), r.Header.Get("User-Agent"),
			r.URL.Query().Get("q"), r.URL.Query().Get("page"))
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 10 * time.Second}

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

	// Build the query string safely: url.Values escapes spaces and symbols.
	params := url.Values{}
	params.Set("q", "go & rust")
	params.Set("page", "2")
	target := srv.URL + "/search?" + params.Encode()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Set("Authorization", "Bearer token123")
	req.Header.Set("User-Agent", "docs-example/1.0")

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
	fmt.Println("encoded query:", params.Encode())
}

Concatenar entrada do usuário em uma URL ("?q=" + q) quebra com &, # e espaços. O url.Values e o seu método Encode fazem o escape e ordenam as chaves. Para segmentos de caminho, use url.PathEscape.

POST com JSON

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"time"
)

type Order struct {
	Item     string `json:"item"`
	Quantity int    `json:"quantity"`
}

type Created struct {
	ID     int    `json:"id"`
	Status string `json:"status"`
}

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		var o Order
		if r.Header.Get("Content-Type") != "application/json" {
			http.Error(w, "want JSON", http.StatusUnsupportedMediaType)
			return
		}
		if err := json.NewDecoder(r.Body).Decode(&o); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusCreated)
		json.NewEncoder(w).Encode(Created{ID: 101, Status: fmt.Sprintf("%d x %s", o.Quantity, o.Item)})
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 5 * time.Second}

	payload, err := json.Marshal(Order{Item: "coffee", Quantity: 2})
	if err != nil {
		fmt.Println(err)
		return
	}

	resp, err := client.Post(srv.URL+"/orders", "application/json", bytes.NewReader(payload))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusCreated {
		msg, _ := io.ReadAll(resp.Body)
		fmt.Println("unexpected status:", resp.Status, string(msg))
		return
	}
	var c Created
	if err := json.NewDecoder(resp.Body).Decode(&c); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%d %+v\n", resp.StatusCode, c)
}

client.Post(url, contentType, body) é um atalho para uma requisição com aquele header Content-Type. Para qualquer outra coisa (um header de autenticação, PUT, PATCH, DELETE), use http.NewRequestWithContext com o método e client.Do. Para envio de formulários, client.PostForm(url, url.Values{...}) codifica os valores e define application/x-www-form-urlencoded.

Reutilização de conexões

O cliente só reutiliza uma conexão TCP quando você lê o corpo anterior até o fim e o fecha. Se você parar de ler antes (por exemplo, depois de um status de erro), esvazie o corpo antes de fechar quando fizer muitas requisições ao mesmo host:

defer func() {
	io.Copy(io.Discard, resp.Body)
	resp.Body.Close()
}()

Para corpos que podem ser enormes, esvazie por meio de um io.LimitReader, ou aceite perder a conexão.

Redirecionamentos

O cliente segue até 10 redirecionamentos automaticamente, e resp.Request.URL diz onde você foi parar. Para parar no primeiro redirecionamento, por exemplo para ler um header Location, defina CheckRedirect:

client := &http.Client{
	Timeout: 10 * time.Second,
	CheckRedirect: func(req *http.Request, via []*http.Request) error {
		return http.ErrUseLastResponse // return the 3xx response itself
	},
}

Erros comuns

Usar http.Get ou http.DefaultClient em produção. Sem timeout. Crie um http.Client com Timeout.
Esquecer o resp.Body.Close(). As conexões vazam até as requisições começarem a falhar.
Fechar o corpo antes de verificar o err. Quando o err não é nil, resp é nil e resp.Body.Close() causa panic.
Tratar err == nil como sucesso. Verifique resp.StatusCode.
Criar um http.Transport novo por requisição. Cada transporte tem o seu próprio pool de conexões, então toda requisição abre uma conexão nova (e um handshake TLS novo). Compartilhe um transporte, normalmente por meio de um único http.Client compartilhado.
Montar query strings à mão. Use url.Values.

Perguntas frequentes

Como fazer uma requisição GET em Go?

resp, err := http.Get(url), verifique o err, depois faça defer resp.Body.Close() e leia o corpo com io.ReadAll(resp.Body) ou decodifique-o com json.NewDecoder(resp.Body).Decode(&v). Verifique também resp.StatusCode: um 404 ou 500 não é um erro do http.Get.

Como definir um timeout em uma requisição HTTP em Go?

Crie um cliente com timeout, client := &http.Client{Timeout: 10 * time.Second}, e use-o no lugar de http.Get ou http.DefaultClient, que não têm timeout geral: um servidor que aceita a conexão e nunca responde bloqueia a chamada para sempre. Para um limite por requisição, monte a requisição com http.NewRequestWithContext e um context vindo de context.WithTimeout.

Como enviar uma requisição POST com corpo JSON em Go?

Faça o marshal do valor e depois o envie: body, _ := json.Marshal(v) e http.Post(url, "application/json", bytes.NewReader(body)). Para acrescentar headers como Authorization, monte-a com http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), defina req.Header.Set("Content-Type", "application/json") e envie com client.Do(req).

Por que preciso fechar o resp.Body em Go?

O corpo é um fluxo sobre uma conexão aberta. Fechá-lo devolve a conexão ao pool para ser reutilizada; esquecer vaza conexões e descritores de arquivo até o programa chegar ao limite. Feche-o mesmo quando não for lê-lo, e leia até o fim se quiser que a conexão seja reutilizada.

Conceitos relacionados