Serwer HTTP w Golang: routing net/http, JSON i kody statusu

Serwer w kilku liniach

Handler to funkcja, która dostaje żądanie i zapisuje odpowiedź. ServeMux kieruje żądania do handlerów.

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

Edytor nie może przyjmować połączeń z twojej przeglądarki, więc przykłady na tej stronie uruchamiają serwer przez httptest.NewServer i wywołują go z tego samego programu. W prawdziwym programie ostatnią część zastępuje jedna linia, która blokuje i obsługuje żądania bez końca:

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

Wtedy curl localhost:8080/hello/gopher wypisze Hello, gopher!. ListenAndServe zwraca tylko przy błędzie (np. gdy port jest zajęty), dlatego jest opakowane w log.Fatal.

Każde żądanie działa we własnej gorutynie. Wszystko, co współdzielą twoje handlery, np. mapa albo licznik, potrzebuje mutexu.

Handlery

Wszystko, co ma metodę ServeHTTP(http.ResponseWriter, *http.Request), jest http.Handler. http.HandlerFunc dopasowuje zwykłą funkcję do tego interfejsu, a mux.HandleFunc robi tę konwersję za ciebie. Handler w postaci struktury przydaje się, gdy handlery potrzebują zależności:

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)

*http.Request daje ci:

Wzorce routingu (Go 1.22)

Od Go 1.22 wzorce ServeMux mają postać [METHOD ][HOST]/[PATH], a ścieżki mogą zawierać wildcardy.

Gdy pasują dwa wzorce, wygrywa bardziej szczegółowy, więc /items/new wygrywa z /items/{id}. Jeśli żaden nie jest bardziej szczegółowy, np. /items/{id} i /{kind}/new (oba pasują do /items/new), rejestracja drugiego wywołuje panikę z komunikatem, który wymienia oba wzorce. Jeśli ścieżka pasuje, ale metoda nie, mux sam odpowiada 405 Method Not Allowed z nagłówkiem Allow, bez żadnego kodu z twojej strony.

Wzorzec "/" łapie wszystko. To zaskakuje osoby, które rejestrują stronę główną pod "/", a potem widzą, że odpowiada ona kodem 200 na każdy nieznany URL. Dla strony głównej użyj "GET /{$}".

Te wzorce wymagają go 1.22 lub nowszego w go.mod. Przy starszej wersji w tej linii mux wraca do dawnego zachowania: czyta "GET /items" jako nazwę hosta, po której następuje ścieżka, więc trasa nigdy nie pasuje i każde żądanie do /items dostaje 404.

Małe API w 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()
	}
}

Ostatnie żądanie używa DELETE, którego nie przyjmuje żadna trasa, więc mux sam odpowiada 405 z Allow: GET, HEAD: to metody zarejestrowane dla tej ścieżki (trasa GET przyjmuje też HEAD).

Kody statusu i kolejność zapisów

Odpowiedź ma trzy części i trzeba je zapisać w kolejności: nagłówki, status, body.

1. w.Header().Set(...) zmienia nagłówki. Działa tylko do momentu wysłania statusu.
2. w.WriteHeader(code) wysyła linię statusu i nagłówki.
3. w.Write(...) (albo fmt.Fprint(w, ...) lub enkoder) wysyła body. Jeśli WriteHeader nie zostało wywołane, pierwsze Write najpierw wysyła 200 OK.

Konsekwencje:

• Ustawienie nagłówka po rozpoczęciu body nic nie daje.
• Dwukrotne wywołanie WriteHeader zapisuje w logu http: superfluous response.WriteHeader call i zachowuje pierwszy status.
• Po odpowiedzi z błędem zrób return. http.Error nie zatrzymuje handlera, a kod po nim dalej pisze do tej samej odpowiedzi.

Używaj nazwanych stałych (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) zamiast gołych liczb. http.StatusText(404) zwraca "Not Found".

Middleware

Middleware to funkcja, która przyjmuje handler i zwraca handler, robiąc coś przed wywołaniem następnego albo po nim:

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

Linia log: zawsze pojawia się przed client got: dla tego samego żądania. Gorutyna handlera wypisuje ją, zanim zwróci, a serwer nie kończy odpowiedzi, dopóki handler nie zwróci.

statusRecorder osadza prawdziwy ResponseWriter i nadpisuje tylko WriteHeader, co jest standardowym sposobem na podejrzenie kodu statusu z poziomu middleware.

Ustawienia produkcyjne

http.ListenAndServe używa serwera bez timeoutów, więc wolny klient może trzymać połączenie otwarte w nieskończoność. Dla wszystkiego, co jest wystawione do internetu, skonfiguruj http.Server jawnie i zamykaj go łagodnie:

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 przestaje przyjmować nowe połączenia i czeka, aż aktywne żądania się zakończą, maksymalnie do terminu z kontekstu. ListenAndServe zwraca http.ErrServerClosed, gdy tylko zacznie się Shutdown, dlatego ten błąd nie jest traktowany jako awaria. W długo działających handlerach przekazuj r.Context() dalej, żeby przerywały pracę, gdy klient odejdzie.

Serwowanie plików statycznych to jedna linia: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Częste błędy

• Brak return po http.Error. Handler działa dalej i dopisuje kolejne dane do odpowiedzi.
• Ustawianie nagłówków po zapisaniu body. Są po cichu pomijane.
• Rejestrowanie strony głównej pod "/". Staje się ona łapaczem każdej nieznanej ścieżki. Użyj "/{$}".
• Współdzielenie stanu między handlerami bez blokady. Żądania działają współbieżnie.
• Używanie domyślnego serwera na produkcji. Nie ma timeoutów; ustaw je na http.Server.
• Ignorowane wzorce routingu. Jeśli "GET /x/{id}" nigdy nie pasuje, sprawdź, czy go.mod zawiera go 1.22 lub nowsze.