Docs Go exécutables : Client HTTP

Q: Comment faire une requête GET en Go ?

resp, err := http.Get(url), vérifiez err, puis defer resp.Body.Close() et lisez le body avec io.ReadAll(resp.Body) ou décodez-le avec json.NewDecoder(resp.Body).Decode(&v). Vérifiez aussi resp.StatusCode : un 404 ou un 500 n'est pas une erreur pour http.Get.

Q: Comment définir un timeout sur une requête HTTP en Go ?

Créez un client avec un timeout, client := &http.Client{Timeout: 10 * time.Second}, et utilisez-le à la place de http.Get ou de http.DefaultClient, qui n'ont pas de timeout global : un serveur qui accepte la connexion et ne répond jamais bloque l'appel indéfiniment. Pour une limite par requête, construisez la requête avec http.NewRequestWithContext et un context issu de context.WithTimeout.

Q: Comment envoyer une requête POST avec un body JSON en Go ?

Sérialisez la valeur, puis envoyez-la : body, _ := json.Marshal(v) et http.Post(url, "application/json", bytes.NewReader(body)). Pour ajouter des en-têtes comme Authorization, construisez-la avec http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), définissez req.Header.Set("Content-Type", "application/json"), et envoyez-la avec client.Do(req).

Q: Pourquoi faut-il fermer resp.Body en Go ?

Le body est un flux sur une connexion ouverte. Le fermer rend la connexion au pool pour qu'elle soit réutilisée ; l'oublier fait fuir des connexions et des descripteurs de fichiers jusqu'à ce que le programme atteigne sa limite. Fermez-le même si vous ne le lisez pas, et lisez-le jusqu'au bout si vous voulez que la connexion soit réutilisée.

Une requête 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))
}

Chaque exemple de cette page démarre son propre serveur avec httptest.NewServer et l'appelle via une vraie connexion TCP sur localhost. Remplacez srv.URL par une vraie adresse comme https://api.example.com et le code client ne change pas.

Les trois règles visibles ici :

Vérifiez err en premier. Elle signale l'impossibilité d'obtenir la moindre réponse : erreurs DNS, connexions refusées, timeouts, problèmes TLS.
defer resp.Body.Close() juste après la vérification d'erreur. Le body garde la connexion ouverte. Un body non fermé fait fuir la connexion.
Lisez ou décodez le body. io.ReadAll pour du texte, json.NewDecoder(resp.Body).Decode(&v) pour du JSON.

Les codes de statut ne sont pas des erreurs

http.Get renvoie err == nil pour toute réponse envoyée par le serveur, y compris 404 et 500. Vous devez vérifier le statut vous-même :

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 plafonne la quantité lue d'un body d'erreur, pour qu'un serveur défaillant ne vous fasse pas charger des mégaoctets dans un message d'erreur. Beaucoup d'API renvoient 201, 202 ou 204 en cas de succès ; vérifiez resp.StatusCode >= 200 && resp.StatusCode < 300 quand n'importe quel 2xx convient.

Timeouts : n'utilisez jamais le client par défaut pour du vrai trafic

http.Get, http.Post et http.DefaultClient n'ont aucun timeout global (le transport par défaut ne limite que l'établissement de la connexion et la négociation TLS). Un serveur qui accepte la connexion et ne répond jamais bloque votre goroutine indéfiniment. Créez votre propre 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 couvre tout l'échange : la connexion, les redirections et la lecture du body. L'erreur qu'il renvoie est une *url.Error qui indique Timeout() == true, que errors.As trouve via l'interface net.Error. Créez un seul client et réutilisez-le partout ; un http.Client peut être utilisé en concurrence sans risque. Le pool de connexions vit dans son Transport, pas dans le Client : un nouveau http.Client{} par requête partage toujours http.DefaultTransport et son pool, mais un nouveau http.Transport par requête repart chaque fois d'un pool vide.

Requêtes avec un context et des en-têtes

http.NewRequestWithContext construit une requête que vous pouvez personnaliser avant de l'envoyer avec client.Do. Le context ajoute une échéance ou une annulation par requête en plus du timeout du client, et lie les appels sortants à la durée de vie d'une requête entrante dans un serveur.

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

Concaténer une saisie utilisateur dans une URL ("?q=" + q) casse avec &, # et les espaces. url.Values et sa méthode Encode font l'échappement, et trient les clés. Pour les segments de chemin, utilisez url.PathEscape.

POST 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) est un raccourci pour une requête avec cet en-tête Content-Type. Pour tout le reste (un en-tête d'authentification, PUT, PATCH, DELETE), utilisez http.NewRequestWithContext avec la méthode et client.Do. Pour les envois de formulaire, client.PostForm(url, url.Values{...}) encode les valeurs et définit application/x-www-form-urlencoded.

Réutilisation des connexions

Le client ne réutilise une connexion TCP que si vous lisez le body précédent jusqu'au bout et le fermez. Si vous arrêtez de lire plus tôt (par exemple après un statut d'erreur), videz-le avant de le fermer quand vous faites de nombreuses requêtes vers le même hôte :

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

Pour des bodies qui pourraient être énormes, videz plutôt via io.LimitReader, ou acceptez de perdre la connexion.

Redirections

Le client suit automatiquement jusqu'à 10 redirections, et resp.Request.URL vous indique où vous avez abouti. Pour vous arrêter à la première redirection, par exemple pour lire un en-tête Location, définissez 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
	},
}

Erreurs courantes

Utiliser http.Get ou http.DefaultClient en production. Pas de timeout. Créez un http.Client avec Timeout.
Oublier resp.Body.Close(). Les connexions fuient jusqu'à ce que les requêtes commencent à échouer.
Fermer le body avant de vérifier err. Quand err n'est pas nil, resp vaut nil et resp.Body.Close() provoque un panic.
Considérer err == nil comme un succès. Vérifiez resp.StatusCode.
Créer un nouveau http.Transport par requête. Chaque transport a son propre pool de connexions, donc chaque requête ouvre une nouvelle connexion (et une nouvelle négociation TLS). Partagez un seul transport, généralement via un seul http.Client partagé.
Construire les chaînes de requête à la main. Utilisez url.Values.

Questions fréquentes

Comment faire une requête GET en Go ?

resp, err := http.Get(url), vérifiez err, puis defer resp.Body.Close() et lisez le body avec io.ReadAll(resp.Body) ou décodez-le avec json.NewDecoder(resp.Body).Decode(&v). Vérifiez aussi resp.StatusCode : un 404 ou un 500 n'est pas une erreur pour http.Get.

Comment définir un timeout sur une requête HTTP en Go ?

Créez un client avec un timeout, client := &http.Client{Timeout: 10 * time.Second}, et utilisez-le à la place de http.Get ou de http.DefaultClient, qui n'ont pas de timeout global : un serveur qui accepte la connexion et ne répond jamais bloque l'appel indéfiniment. Pour une limite par requête, construisez la requête avec http.NewRequestWithContext et un context issu de context.WithTimeout.

Comment envoyer une requête POST avec un body JSON en Go ?

Sérialisez la valeur, puis envoyez-la : body, _ := json.Marshal(v) et http.Post(url, "application/json", bytes.NewReader(body)). Pour ajouter des en-têtes comme Authorization, construisez-la avec http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), définissez req.Header.Set("Content-Type", "application/json"), et envoyez-la avec client.Do(req).

Pourquoi faut-il fermer resp.Body en Go ?

Le body est un flux sur une connexion ouverte. Le fermer rend la connexion au pool pour qu'elle soit réutilisée ; l'oublier fait fuir des connexions et des descripteurs de fichiers jusqu'à ce que le programme atteigne sa limite. Fermez-le même si vous ne le lisez pas, et lisez-le jusqu'au bout si vous voulez que la connexion soit réutilisée.

Concepts liés