Server HTTP in Golang: routing net/http, JSON e status code

Un server in poche righe

Un handler è una funzione che riceve la richiesta e scrive la risposta. ServeMux instrada le richieste verso gli handler.

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'editor non può accettare connessioni dal tuo browser, quindi gli esempi di questa pagina avviano il server con httptest.NewServer e lo chiamano dallo stesso programma. In un programma reale l'ultima parte è sostituita da una riga che si blocca e serve richieste per sempre:

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

A quel punto curl localhost:8080/hello/gopher stampa Hello, gopher!. ListenAndServe ritorna solo in caso di errore (la porta è già occupata, per esempio), ed è per questo che è avvolto in log.Fatal.

Ogni richiesta gira nella propria goroutine. Tutto ciò che i tuoi handler condividono, come una map o un contatore, ha bisogno di un mutex.

Handler

Qualsiasi cosa abbia un metodo ServeHTTP(http.ResponseWriter, *http.Request) è un http.Handler. http.HandlerFunc adatta una funzione normale a quell'interfaccia, e mux.HandleFunc fa la conversione per te. Un handler basato su struct è comodo quando gli handler hanno delle dipendenze:

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)

L'*http.Request ti dà:

Pattern di routing (Go 1.22)

Da Go 1.22, i pattern di ServeMux hanno la forma [METHOD ][HOST]/[PATH], e i percorsi possono contenere wildcard.

Quando corrispondono due pattern, vince quello più specifico, quindi /items/new batte /items/{id}. Se nessuno dei due è più specifico, per esempio /items/{id} e /{kind}/new (entrambi corrispondono a /items/new), registrare il secondo causa un panic con un messaggio che nomina entrambi i pattern. Se un percorso corrisponde ma il metodo no, il mux risponde 405 Method Not Allowed con un header Allow, senza bisogno di codice da parte tua.

Il pattern "/" è quello pigliatutto. Sorprende chi registra una home page con "/" e la trova a rispondere 200 a ogni URL sconosciuto. Usa "GET /{$}" per la home page.

Questi pattern richiedono go 1.22 o successivo in go.mod. Con una riga di versione più vecchia, il mux torna al comportamento precedente: legge "GET /items" come un nome host seguito da un percorso, quindi la route non corrisponde mai e ogni richiesta a /items riceve un 404.

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

L'ultima richiesta usa DELETE, che nessuna route accetta, e il mux risponde da solo 405 con Allow: GET, HEAD: sono i metodi registrati per quel percorso (una route GET accetta anche HEAD).

Status code e ordine delle scritture

Una risposta ha tre parti, e vanno scritte in ordine: header, status, body.

1. w.Header().Set(...) modifica gli header. Ha effetto solo finché lo status non è stato inviato.
2. w.WriteHeader(code) invia la riga di status e gli header.
3. w.Write(...) (oppure fmt.Fprint(w, ...), o un encoder) invia il body. Se WriteHeader non è stato chiamato, il primo Write invia prima 200 OK.

Conseguenze:

• Impostare un header dopo che il body è partito non fa niente.
• Chiamare WriteHeader due volte scrive nel log http: superfluous response.WriteHeader call e mantiene il primo status.
• Dopo una risposta di errore, fai return. http.Error non ferma il tuo handler, e il codice che viene dopo continua a scrivere nella stessa risposta.

Usa le costanti con nome (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) invece dei numeri nudi. http.StatusText(404) restituisce "Not Found".

Middleware

Un middleware è una funzione che prende un handler e restituisce un handler, facendo qualcosa prima o dopo aver chiamato il successivo:

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

Per la stessa richiesta, la riga log: compare sempre prima di client got:. La goroutine dell'handler la stampa prima di ritornare, e il server non completa la risposta finché l'handler non ritorna.

Lo statusRecorder incorpora il vero ResponseWriter e sovrascrive solo WriteHeader, che è il modo standard per osservare lo status code da un middleware.

Impostazioni per la produzione

http.ListenAndServe usa un server senza timeout, quindi un client lento può tenere aperta una connessione a tempo indeterminato. Configura esplicitamente un http.Server per qualsiasi cosa esposta su internet, e spegnilo in modo graduale:

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 smette di accettare nuove connessioni e aspetta che le richieste attive finiscano, fino alla scadenza del context. ListenAndServe restituisce http.ErrServerClosed non appena parte Shutdown, ed è per questo che quell'errore non viene trattato come un fallimento. Per gli handler che durano a lungo, passa r.Context() verso il basso così si fermano quando il client se ne va.

Servire file statici richiede una riga: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Errori comuni

• Non fare return dopo http.Error. L'handler continua a girare e scrive altro nella risposta.
• Impostare header dopo aver scritto il body. Vengono scartati senza avvisi.
• Registrare la home page su "/". Diventa il pigliatutto per ogni percorso sconosciuto. Usa "/{$}".
• Condividere stato tra handler senza lock. Le richieste girano in modo concorrente.
• Usare il server di default in produzione. Non ha timeout; impostali su un http.Server.
• Pattern di routing ignorati. Se "GET /x/{id}" non corrisponde mai, controlla che go.mod dica go 1.22 o successivo.