Serveur HTTP en Golang : routage net/http, JSON et codes de statut

Un serveur en quelques lignes

Un handler est une fonction qui reçoit la requête et écrit la réponse. ServeMux achemine les requêtes vers les handlers.

package main

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

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /hello/{name}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello, %s!\n", r.PathValue("name"))
	})

	// httptest starts a real server on a random local port.
	srv := httptest.NewServer(mux)
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/hello/gopher")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Print(resp.Status, " ", string(body))
}

L'éditeur ne peut pas accepter de connexions depuis votre navigateur, donc les exemples de cette page démarrent le serveur avec httptest.NewServer et l'appellent depuis le même programme. Dans un vrai programme, la dernière partie est remplacée par une seule ligne qui bloque et sert indéfiniment :

log.Fatal(http.ListenAndServe(":8080", mux))

Ensuite curl localhost:8080/hello/gopher affiche Hello, gopher!. ListenAndServe ne retourne qu'en cas d'erreur (le port est déjà pris, par exemple), c'est pourquoi il est enveloppé dans log.Fatal.

Chaque requête s'exécute dans sa propre goroutine. Tout ce que vos handlers partagent, comme une map ou un compteur, a besoin d'un mutex.

Handlers

Tout ce qui a une méthode ServeHTTP(http.ResponseWriter, *http.Request) est un http.Handler. http.HandlerFunc adapte une simple fonction à cette interface, et mux.HandleFunc fait la conversion pour vous. Un handler sous forme de struct est pratique quand les handlers ont besoin de dépendances :

type API struct {
	db *sql.DB
}

func (a *API) listItems(w http.ResponseWriter, r *http.Request) { /* uses a.db */ }

mux.HandleFunc("GET /items", api.listItems)

Le *http.Request vous donne :

Motifs de routage (Go 1.22)

Depuis Go 1.22, les motifs de ServeMux ont la forme [METHOD ][HOST]/[PATH], et les chemins peuvent contenir des jokers.

Quand deux motifs correspondent, le plus spécifique l'emporte, donc /items/new bat /items/{id}. Si aucun n'est plus spécifique, par exemple /items/{id} et /{kind}/new (qui correspondent tous deux à /items/new), enregistrer le second provoque un panic avec un message qui nomme les deux motifs. Si un chemin correspond mais pas la méthode, le mux répond 405 Method Not Allowed avec un en-tête Allow, sans aucun code de votre part.

Le motif "/" est le fourre-tout. Cela surprend ceux qui enregistrent une page d'accueil sur "/" et la voient répondre 200 à toute URL inconnue. Utilisez "GET /{$}" pour la page d'accueil.

Ces motifs exigent go 1.22 ou plus dans go.mod. Avec une ligne de version plus ancienne, le mux revient à l'ancien comportement : il lit "GET /items" comme un nom d'hôte suivi d'un chemin, donc la route ne correspond jamais et chaque requête vers /items reçoit un 404.

Une petite API JSON

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strconv"
	"strings"
	"sync"
)

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

type Store struct {
	mu     sync.Mutex
	items  map[int]Item
	nextID int
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json") // headers first
	w.WriteHeader(status)                              // then the status
	json.NewEncoder(w).Encode(v)                       // then the body
}

func (s *Store) getItem(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.Atoi(r.PathValue("id"))
	if err != nil {
		http.Error(w, "id must be a number", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	item, ok := s.items[id]
	s.mu.Unlock()
	if !ok {
		http.Error(w, "item not found", http.StatusNotFound)
		return
	}
	writeJSON(w, http.StatusOK, item)
}

func (s *Store) createItem(w http.ResponseWriter, r *http.Request) {
	var in Item
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // refuse bodies over 1 MB
	if err := json.NewDecoder(r.Body).Decode(&in); err != nil || in.Name == "" {
		http.Error(w, "invalid JSON body", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	s.nextID++
	in.ID = s.nextID
	s.items[in.ID] = in
	s.mu.Unlock()

	w.Header().Set("Location", fmt.Sprintf("/items/%d", in.ID))
	writeJSON(w, http.StatusCreated, in)
}

func main() {
	store := &Store{items: map[int]Item{}}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /items/{id}", store.getItem)
	mux.HandleFunc("POST /items", store.createItem)

	srv := httptest.NewServer(mux)
	defer srv.Close()

	show := func(resp *http.Response, err error) {
		if err != nil {
			fmt.Println("error:", err)
			return
		}
		defer resp.Body.Close()
		body, _ := io.ReadAll(resp.Body)
		fmt.Printf("%d %s", resp.StatusCode, body)
		if loc := resp.Header.Get("Location"); loc != "" {
			fmt.Println("  Location:", loc)
		}
	}

	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{"name":"lamp"}`)))
	show(http.Get(srv.URL + "/items/1"))
	show(http.Get(srv.URL + "/items/99"))
	show(http.Get(srv.URL + "/items/abc"))
	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{bad json`)))

	req, _ := http.NewRequest(http.MethodDelete, srv.URL+"/items/1", nil)
	resp, err := http.DefaultClient.Do(req)
	if err == nil {
		fmt.Println(resp.StatusCode, "Allow:", resp.Header.Get("Allow"))
		resp.Body.Close()
	}
}

La dernière requête utilise DELETE, qu'aucune route n'accepte, et le mux répond 405 avec Allow: GET, HEAD tout seul : ce sont les méthodes enregistrées pour ce chemin (une route GET accepte aussi HEAD).

Codes de statut et ordre des écritures

Une réponse a trois parties, et elles doivent être écrites dans l'ordre : en-têtes, statut, body.

1. w.Header().Set(...) modifie les en-têtes. Cela n'a d'effet que tant que le statut n'est pas envoyé.
2. w.WriteHeader(code) envoie la ligne de statut et les en-têtes.
3. w.Write(...) (ou fmt.Fprint(w, ...), ou un encodeur) envoie le body. Si WriteHeader n'a pas été appelé, le premier Write envoie d'abord 200 OK.

Conséquences :

• Définir un en-tête après le début du body ne fait rien.
• Appeler WriteHeader deux fois journalise http: superfluous response.WriteHeader call et garde le premier statut.
• Après une réponse d'erreur, faites return. http.Error n'arrête pas votre handler, et le code qui suit continue d'écrire dans la même réponse.

Utilisez les constantes nommées (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) plutôt que des nombres bruts. http.StatusText(404) renvoie "Not Found".

Middlewares

Un middleware est une fonction qui prend un handler et renvoie un handler, en faisant quelque chose avant ou après l'appel au suivant :

package main

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

func requireKey(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("X-API-Key") != "secret" {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		next.ServeHTTP(w, r)
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

func logRequests(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)
		fmt.Printf("log: %s %s -> %d\n", r.Method, r.URL.Path, rec.status)
	})
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /report", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "the report")
	})

	handler := logRequests(requireKey(mux)) // outermost runs first
	srv := httptest.NewServer(handler)
	defer srv.Close()

	for _, key := range []string{"", "secret"} {
		req, _ := http.NewRequest(http.MethodGet, srv.URL+"/report", nil)
		req.Header.Set("X-API-Key", key)
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			fmt.Println(err)
			return
		}
		resp.Body.Close()
		fmt.Println("client got:", resp.Status)
	}
}

La ligne log: apparaît toujours avant client got: pour une même requête. La goroutine du handler l'affiche avant de retourner, et le serveur ne termine pas la réponse avant le retour du handler.

Le statusRecorder embarque le vrai ResponseWriter et ne redéfinit que WriteHeader, ce qui est la façon standard d'observer le code de statut depuis un middleware.

Réglages de production

http.ListenAndServe utilise un serveur sans timeouts, donc un client lent peut garder une connexion ouverte indéfiniment. Configurez explicitement un http.Server pour tout ce qui est exposé à Internet, et arrêtez-le proprement :

srv := &http.Server{
	Addr:              ":8080",
	Handler:           mux,
	ReadHeaderTimeout: 5 * time.Second,
	ReadTimeout:       10 * time.Second,
	WriteTimeout:      30 * time.Second,
	IdleTimeout:       120 * time.Second,
}

go func() {
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done() // wait for Ctrl+C or a SIGTERM from the orchestrator

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil { // finish in-flight requests
	log.Println("shutdown:", err)
}

Shutdown cesse d'accepter de nouvelles connexions et attend la fin des requêtes actives, jusqu'à l'échéance du context. ListenAndServe renvoie http.ErrServerClosed dès que Shutdown commence, c'est pourquoi cette erreur n'est pas traitée comme un échec. Pour les handlers de longue durée, passez r.Context() plus bas pour qu'ils s'arrêtent quand le client s'en va.

Servir des fichiers statiques tient en une ligne : mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Erreurs courantes

• Ne pas retourner après http.Error. Le handler continue de s'exécuter et écrit davantage dans la réponse.
• Définir des en-têtes après avoir écrit le body. Ils sont ignorés sans bruit.
• Enregistrer la page d'accueil sur "/". Elle devient le fourre-tout pour tous les chemins inconnus. Utilisez "/{$}".
• Partager un état entre handlers sans verrou. Les requêtes s'exécutent en concurrence.
• Utiliser le serveur par défaut en production. Il n'a pas de timeouts ; définissez-les sur un http.Server.
• Des motifs de routage ignorés. Si "GET /x/{id}" ne correspond jamais, vérifiez que go.mod indique go 1.22 ou plus.