Golang HTTP-Server: Routing mit net/http, JSON und Statuscodes

Ein Server in wenigen Zeilen

Ein Handler ist eine Funktion, die den Request bekommt und die Antwort schreibt. ServeMux leitet Requests an Handler weiter.

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

Der Editor kann keine Verbindungen von deinem Browser annehmen, also starten die Beispiele auf dieser Seite den Server mit httptest.NewServer und rufen ihn aus demselben Programm auf. In einem echten Programm ersetzt eine einzige Zeile den letzten Teil, die blockiert und für immer bedient:

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

Dann gibt curl localhost:8080/hello/gopher Hello, gopher! aus. ListenAndServe kehrt nur bei einem Fehler zurück (etwa wenn der Port belegt ist), deshalb steht es in log.Fatal.

Jeder Request läuft in seiner eigenen Goroutine. Alles, was deine Handler teilen, etwa eine Map oder ein Zähler, braucht einen Mutex.

Handler

Alles mit einer Methode ServeHTTP(http.ResponseWriter, *http.Request) ist ein http.Handler. http.HandlerFunc passt eine einfache Funktion an dieses Interface an, und mux.HandleFunc übernimmt die Konvertierung für dich. Ein Struct als Handler ist praktisch, wenn Handler Abhängigkeiten brauchen:

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)

Der *http.Request liefert dir:

Routenmuster (Go 1.22)

Seit Go 1.22 haben Muster von ServeMux die Form [METHOD ][HOST]/[PATH], und Pfade können Wildcards enthalten.

Passen zwei Muster, gewinnt das spezifischere, also schlägt /items/new das Muster /items/{id}. Ist keines spezifischer, etwa /items/{id} und /{kind}/new (beide passen auf /items/new), löst das Registrieren des zweiten eine Panic mit einer Meldung aus, die beide Muster nennt. Passt ein Pfad, aber nicht die Methode, antwortet der Mux ohne jeden Code von dir mit 405 Method Not Allowed und einem Allow-Header.

Das Muster "/" fängt alles auf. Das überrascht alle, die eine Startseite mit "/" registrieren und dann feststellen, dass sie jede unbekannte URL mit 200 beantwortet. Nimm "GET /{$}" für die Startseite.

Diese Muster brauchen go 1.22 oder höher in go.mod. Mit einer älteren Versionszeile fällt der Mux auf das alte Verhalten zurück: Er liest "GET /items" als Hostnamen gefolgt von einem Pfad, also passt die Route nie, und jeder Request an /items bekommt ein 404.

Eine kleine JSON-API

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

Der letzte Request verwendet DELETE, das keine Route akzeptiert, und der Mux antwortet von selbst mit 405 und Allow: GET, HEAD: Das sind die Methoden, die für diesen Pfad registriert sind (eine GET-Route akzeptiert auch HEAD).

Statuscodes und die Reihenfolge der Schreibzugriffe

Eine Antwort hat drei Teile, und sie müssen in dieser Reihenfolge geschrieben werden: Header, Status, Body.

1. w.Header().Set(...) ändert Header. Das wirkt nur, bis der Status gesendet ist.
2. w.WriteHeader(code) sendet die Statuszeile und die Header.
3. w.Write(...) (oder fmt.Fprint(w, ...) oder ein Encoder) sendet den Body. Wurde WriteHeader nicht aufgerufen, sendet das erste Write zuerst 200 OK.

Die Folgen:

• Einen Header zu setzen, nachdem der Body begonnen hat, bewirkt nichts.
• WriteHeader zweimal aufzurufen loggt http: superfluous response.WriteHeader call und behält den ersten Status.
• Nach einer Fehlerantwort: return. http.Error stoppt deinen Handler nicht, und Code danach schreibt weiter in dieselbe Antwort.

Nimm die benannten Konstanten (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) statt nackter Zahlen. http.StatusText(404) gibt "Not Found" zurück.

Middleware

Middleware ist eine Funktion, die einen Handler nimmt und einen Handler zurückgibt und vor oder nach dem Aufruf des nächsten etwas tut:

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

Die Zeile log: erscheint für denselben Request immer vor client got:. Die Handler-Goroutine gibt sie aus, bevor sie zurückkehrt, und der Server schließt die Antwort erst ab, wenn der Handler zurückkehrt.

Der statusRecorder bettet den echten ResponseWriter ein und überschreibt nur WriteHeader. Das ist der Standardweg, um den Statuscode aus einer Middleware heraus zu beobachten.

Einstellungen für die Produktion

http.ListenAndServe nutzt einen Server ohne Timeouts, also kann ein langsamer Client eine Verbindung unbegrenzt offen halten. Konfigurier für alles, was im Internet erreichbar ist, explizit einen http.Server und fahr ihn geordnet herunter:

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 nimmt keine neuen Verbindungen mehr an und wartet, bis laufende Requests fertig sind, höchstens bis zur Deadline des Context. ListenAndServe gibt http.ErrServerClosed zurück, sobald Shutdown beginnt, deshalb wird dieser Fehler nicht als Fehlschlag behandelt. Reich bei lange laufenden Handlern r.Context() nach unten weiter, damit sie aufhören, wenn der Client weg ist.

Statische Dateien auszuliefern ist eine Zeile: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Häufige Fehler

• Nach http.Error nicht zurückkehren. Der Handler läuft weiter und schreibt mehr in die Antwort.
• Header nach dem Body setzen. Sie werden still verworfen.
• Die Startseite auf "/" registrieren. Sie fängt dann jeden unbekannten Pfad auf. Nimm "/{$}".
• Zustand zwischen Handlern ohne Lock teilen. Requests laufen nebenläufig.
• Den Standard-Server in Produktion verwenden. Er hat keine Timeouts; setz sie auf einem http.Server.
• Ignorierte Routenmuster. Passt "GET /x/{id}" nie, prüf, ob in go.mod go 1.22 oder höher steht.