Guida Go interattiva: Client HTTP

Q: Come faccio una richiesta GET in Go?

resp, err := http.Get(url), controlla err, poi defer resp.Body.Close() e leggi il body con io.ReadAll(resp.Body) oppure decodificalo con json.NewDecoder(resp.Body).Decode(&v). Controlla anche resp.StatusCode: un 404 o un 500 non è un errore per http.Get.

Q: Come imposto un timeout su una richiesta HTTP in Go?

Crea un client con un timeout, client := &http.Client{Timeout: 10 * time.Second}, e usalo al posto di http.Get o http.DefaultClient, che non hanno un timeout complessivo: un server che accetta la connessione e non risponde mai blocca la chiamata per sempre. Per un limite per singola richiesta, costruisci la richiesta con http.NewRequestWithContext e un context da context.WithTimeout.

Q: Come invio una richiesta POST con un body JSON in Go?

Fai il marshal del valore, poi invialo: body, _ := json.Marshal(v) e http.Post(url, "application/json", bytes.NewReader(body)). Per aggiungere header come Authorization, costruiscila con http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), imposta req.Header.Set("Content-Type", "application/json") e inviala con client.Do(req).

Q: Perché devo chiudere resp.Body in Go?

Il body è uno stream su una connessione aperta. Chiuderlo restituisce la connessione al pool per riusarla; dimenticarsene fa perdere connessioni e file descriptor finché il programma non raggiunge il suo limite. Chiudilo anche quando non lo leggi, e leggilo fino in fondo se vuoi che la connessione venga riusata.

Una richiesta 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))
}

Ogni esempio di questa pagina avvia il proprio server con httptest.NewServer e lo chiama attraverso una vera connessione TCP su localhost. Sostituisci srv.URL con un indirizzo reale come https://api.example.com e il codice del client resta identico.

Le tre regole che si vedono qui:

Controlla prima err. Segnala i casi in cui non arriva proprio nessuna risposta: errori DNS, connessioni rifiutate, timeout, problemi TLS.
defer resp.Body.Close() subito dopo il controllo dell'errore. Il body tiene aperta la connessione. Un body non chiuso fa perdere la connessione.
Leggi o decodifica il body. io.ReadAll per il testo, json.NewDecoder(resp.Body).Decode(&v) per il JSON.

Gli status code non sono errori

http.Get restituisce err == nil per qualsiasi risposta mandi il server, compresi 404 e 500. Lo status devi controllarlo tu:

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 quanta parte di un body di errore leggi, così un server che si comporta male non può farti caricare megabyte in un messaggio di errore. Molte API restituiscono 201, 202 o 204 in caso di successo; controlla resp.StatusCode >= 200 && resp.StatusCode < 300 quando va bene qualsiasi 2xx.

Timeout: mai il client di default per il traffico reale

http.Get, http.Post e http.DefaultClient non hanno un timeout complessivo (il transport di default limita solo la connessione e l'handshake TLS). Un server che accetta la connessione e non risponde mai blocca la tua goroutine per sempre. Crea il tuo client:

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 copre l'intero scambio: connessione, redirect e lettura del body. L'errore che restituisce è un *url.Error che riporta Timeout() == true, e errors.As lo trova attraverso l'interfaccia net.Error. Crea un solo client e riusalo ovunque; un http.Client è sicuro per l'uso concorrente. Il pool di connessioni vive nel suo Transport, non nel Client: un nuovo http.Client{} per ogni richiesta condivide comunque http.DefaultTransport e il suo pool, mentre un nuovo http.Transport per ogni richiesta parte ogni volta con un pool vuoto.

Richieste con context e header

http.NewRequestWithContext costruisce una richiesta che puoi personalizzare prima di inviarla con client.Do. Il context aggiunge una scadenza o una cancellazione per singola richiesta sopra il timeout del client, e lega le chiamate in uscita alla durata di una richiesta in arrivo in un server.

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())
}

Concatenare l'input dell'utente in un URL ("?q=" + q) si rompe con &, # e gli spazi. url.Values e il suo metodo Encode fanno l'escaping e ordinano le chiavi. Per i segmenti di percorso, usa url.PathEscape.

POST di 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) è una scorciatoia per una richiesta con quell'header Content-Type. Per tutto il resto (un header di autenticazione, PUT, PATCH, DELETE) usa http.NewRequestWithContext con il metodo e client.Do. Per l'invio di form, client.PostForm(url, url.Values{...}) codifica i valori e imposta application/x-www-form-urlencoded.

Riuso delle connessioni

Il client riusa una connessione TCP solo quando leggi fino in fondo il body precedente e lo chiudi. Se smetti di leggere prima (per esempio dopo uno status di errore), svuotalo prima di chiuderlo quando fai molte richieste allo stesso host:

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

Per body che potrebbero essere enormi, svuotali invece attraverso io.LimitReader, oppure accetta di perdere la connessione.

Redirect

Il client segue automaticamente fino a 10 redirect, e resp.Request.URL ti dice dove sei arrivato. Per fermarti al primo redirect, per esempio per leggere un header Location, imposta 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
	},
}

Errori comuni

Usare http.Get o http.DefaultClient in produzione. Nessun timeout. Crea un http.Client con Timeout.
Dimenticare resp.Body.Close(). Le connessioni si perdono finché le richieste iniziano a fallire.
Chiudere il body prima di controllare err. Quando err non è nil, resp è nil e resp.Body.Close() va in panic.
Considerare err == nil un successo. Controlla resp.StatusCode.
Creare un nuovo http.Transport per ogni richiesta. Ogni transport ha il suo pool di connessioni, quindi ogni richiesta apre una connessione nuova (e un nuovo handshake TLS). Condividi un solo transport, di solito attraverso un unico http.Client condiviso.
Costruire le query string a mano. Usa url.Values.

Domande frequenti

Come faccio una richiesta GET in Go?

resp, err := http.Get(url), controlla err, poi defer resp.Body.Close() e leggi il body con io.ReadAll(resp.Body) oppure decodificalo con json.NewDecoder(resp.Body).Decode(&v). Controlla anche resp.StatusCode: un 404 o un 500 non è un errore per http.Get.

Come imposto un timeout su una richiesta HTTP in Go?

Crea un client con un timeout, client := &http.Client{Timeout: 10 * time.Second}, e usalo al posto di http.Get o http.DefaultClient, che non hanno un timeout complessivo: un server che accetta la connessione e non risponde mai blocca la chiamata per sempre. Per un limite per singola richiesta, costruisci la richiesta con http.NewRequestWithContext e un context da context.WithTimeout.

Come invio una richiesta POST con un body JSON in Go?

Fai il marshal del valore, poi invialo: body, _ := json.Marshal(v) e http.Post(url, "application/json", bytes.NewReader(body)). Per aggiungere header come Authorization, costruiscila con http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), imposta req.Header.Set("Content-Type", "application/json") e inviala con client.Do(req).

Perché devo chiudere resp.Body in Go?

Il body è uno stream su una connessione aperta. Chiuderlo restituisce la connessione al pool per riusarla; dimenticarsene fa perdere connessioni e file descriptor finché il programma non raggiunge il suo limite. Chiudilo anche quando non lo leggi, e leggilo fino in fondo se vuoi che la connessione venga riusata.

Concetti correlati