Skip to content

Modul 10: HTTP-Server & CLI-Tools

Go-Dienste produktionsreif bauen: Router und Handler mit net/http, JSON-APIs mit sauberen Statuscodes, Middleware für Logging, Recovery und Timeouts, Graceful Shutdown samt Server-Konfiguration und CLI-Tools mit flag — abgeschlossen durch ein REST-Capstone.

Fortschritt0/5 Lektionen
46

net/http: Router, Handler & ServerMux-Grundlagen

Lektion 46 von 100

Ein Server, null Abhängigkeiten

Der Task-Tracker des Teams läuft bisher als Tabelle im Gruppenchat: Niemand weiß, welche Tickets offen sind, und die Wochenplanung friert die Liste jeden Freitag ein. Zeit für einen kleinen HTTP-Service, den jeder mit curl abfragen kann. In den meisten Sprachen beginnt so ein Projekt mit der Framework-Auswahl — in Go reicht net/http aus der Standardbibliothek. Kein go get, kein Versions-Chaos, und die Erfahrung vieler Teams nach Jahren lautet: Für die Mehrheit der Dienste reicht der eingebaute Router.

Alles dreht sich um zwei Dinge. Erstens das Handler-Interface: Alles mit einer Methode ServeHTTP(ResponseWriter, *Request) ist ein Handler — auch dein Store, auch der Mux selbst. Zweitens der http.ServeMux, der seit Go 1.22 ein echter Router ist: Patterns können HTTP-Methode, wörtliche Segmente und Wildcards kombinieren, und das spezifischste Pattern gewinnt.

Ein Handler ist ein Interface mit einer Methode

net/http verlangt keine Basisklasse und kein Framework. Ein Typ, der ServeHTTP(w, r) implementiert, ist ein vollwertiger Handler; eine gewöhnliche Funktion wird per http.HandlerFunc oder mux.HandleFunc dazu. Genau deshalb lässt sich alles als Handler verdrahten — der Mux, ein FileServer, deine eigene Struct — und Middleware (Lektion 48) wird ohne Magie möglich.

Hier der kleinste sinnvolle Server — mit Method-Pattern und Wildcard:

// hello/main.go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	mux := http.NewServeMux()

	// Seit Go 1.22: HTTP-Methode und Wildcard direkt im Pattern
	mux.HandleFunc("GET /hello/{name}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hallo, %s!", r.PathValue("name"))
	})

	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("ok"))
	})

	fmt.Println("Server läuft auf http://localhost:8080")
	if err := http.ListenAndServe(":8080", mux); err != nil {
		fmt.Println("Server beendet:", err)
	}
}

// Terminal: curl http://localhost:8080/hello/Ada
// → Hallo, Ada!
//
// Terminal: curl http://localhost:8080/health
// → ok

http.ListenAndServe startet den Server und blockiert, bis er stoppt (Lektion 49 behandelt das saubere Beenden). Wer nil als Handler übergibt, landet beim DefaultServeMux — für eigenes Routing besser einen eigenen Mux bauen und weiterreichen.

Methoden, Wildcards und der Task-Store

Jetzt der eigentliche Service. Zwei Neuerungen im Pattern fallen auf: "POST /tasks" matcht nur POST-Requests — ein DELETE auf diese Route beantwortet der Mux automatisch mit 405 Method Not Allowed samt Allow-Header. Und {id} fängt genau ein Segment ab, lesbar über r.PathValue("id"). Ein Wildcard matcht übrigens auch Nicht-Zahlen, deshalb prüft der Handler das selbst und antwortet mit http.Error — dem eingebauten Helfer für Text-Fehler mit Statuscode.

Beachte außerdem den sync.Mutex im Store. Das ist kein Stil-Detail, sondern Überlebenstechnik — dazu gleich mehr.

// taskd/main.go
package main

import (
	"fmt"
	"log"
	"net/http"
	"strconv"
	"sync"
)

// Task ist eine Zeile im Task-Tracker.
type Task struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
	Done  bool   `json:"done"`
}

// Store hält die Tasks im Speicher. Der Mutex ist Pflicht:
// net/http bedient jeden Request in einer eigenen Goroutine.
type Store struct {
	mu    sync.Mutex
	tasks map[int]Task
	next  int
}

func (s *Store) Add(title string) Task {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.next++
	t := Task{ID: s.next, Title: title}
	s.tasks[t.ID] = t
	return t
}

func (s *Store) Get(id int) (Task, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	t, ok := s.tasks[id]
	return t, ok
}

func main() {
	store := &Store{tasks: map[int]Task{}}

	mux := http.NewServeMux()
	mux.HandleFunc("POST /tasks", func(w http.ResponseWriter, r *http.Request) {
		// der JSON-Decode folgt in Lektion 47
		t := store.Add("neue Aufgabe")
		fmt.Fprintf(w, "angelegt: #%d %s", t.ID, t.Title)
	})
	mux.HandleFunc("GET /tasks/{id}", func(w http.ResponseWriter, r *http.Request) {
		id, err := strconv.Atoi(r.PathValue("id"))
		if err != nil {
			http.Error(w, "id muss eine Zahl sein", http.StatusBadRequest)
			return
		}
		if t, ok := store.Get(id); ok {
			fmt.Fprintf(w, "#%d %s (erledigt: %v)", t.ID, t.Title, t.Done)
			return
		}
		http.NotFound(w, r)
	})

	log.Println("taskd lauscht auf :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

// Terminal: curl http://localhost:8080/tasks/1
// → #1 neue Aufgabe (erledigt: false)
//
// Terminal: curl -i http://localhost:8080/tasks/abc
// → HTTP/1.1 400 Bad Request
// → id muss eine Zahl sein
//
// Terminal: curl -i -X DELETE http://localhost:8080/tasks/1
// → HTTP/1.1 405 Method Not Allowed
// → Allow: GET

Bei der Pattern-Auswahl gilt: Das spezifischere Pattern gewinnt — ein wörtliches Segment wie export schlägt {id}, und {id} schlägt den Catch-All unter /. Registrierst du zwei identische Patterns, panikt der Mux sofort beim Start. Das klingt hart, ist aber ein Geschenk: Routen-Konflikte fallen beim Booten auf, nicht um 3 Uhr nachts beim ersten Request.

⚠ Häufiger Fehler: Den Store als nackte map[int]Task ohne Synchronisation zu bauen. net/http bedient jeden Request in einer eigenen Goroutine — sobald zwei gleichzeitige POSTs in die Map schreiben, stürzt nicht der Request ab, sondern der gesamte Prozess mit fatal error: concurrent map writes. Maps in Go sind nicht nebenläufigkeitssicher: Ein sync.Mutex um jeden Zugriff (wie im Store oben) gehört auf jeden geteilten Zustand in Handlern.

✅ Wichtige Erkenntnisse

Haken setzen, um deinen Lernfortschritt zu markieren:

    47

    JSON-APIs: Encoding, Validation & Statuscodes

    Lektion 47 von 100

    JSON rein, JSON raus — mit Vertrag

    Der Service aus Lektion 46 spricht noch Klartext. Für curl reicht das, aber das Frontend-Team und die anderen Dienste wollen JSON — und zwar mit einem klar definierten Vertrag: Welche Felder hat ein Task? Was passiert bei einem Tippfehler im Feldnamen? Welchen Statuscode bekommt der Client, wenn der Titel fehlt? Diese Lektion macht aus dem Text-Endpoint eine JSON-API mit strikter Validierung.

    Beim Senden nutzen wir json.NewEncoder(w).Encode(v): Der Encoder schreibt direkt in den ResponseWriter, ohne den Body erst in einem Byte-Slice im RAM zu puffern. Beim Empfangen arbeiten wir mit json.NewDecoder(r.Body) — dasselbe Muster wie beim LLM-Client aus Modul 4, nur in die andere Richtung. Und wir schalten mit DisallowUnknownFields auf strikt: Felder, die das Struct nicht kennt, sind dann Fehler statt stillschweigend ignorierte Daten.

    Statuscodes sagen dem Client, wer den Fehler gemacht hat

    Drei Klassen, drei Codes: 400 heißt »dein JSON ist kaputt oder verletzt das Schema« — der Client kann den Request selbst reparieren. 422 heißt »JSON in Ordnung, Inhalt unzulässig« — etwa ein leerer Titel. 500 heißt »das Problem liegt bei mir« — der Client kann nichts tun außer später erneut zu versuchen. Wer alles mit 500 beantwortet, zwingt Clients zu unnötigen Retries und sich selbst zu vergeblicher Fehlersuche.

    Der Handler für POST /tasks — mit Validierung, Location-Header und den passenden Statuscodes:

    // api/tasks.go
    package api
    
    import (
    	"encoding/json"
    	"net/http"
    	"strconv"
    	"strings"
    )
    
    // writeJSON setzt Header und Status, BEVOR kodiert wird.
    func writeJSON(w http.ResponseWriter, status int, v any) error {
    	w.Header().Set("Content-Type", "application/json")
    	w.WriteHeader(status)
    	return json.NewEncoder(w).Encode(v)
    }
    
    func (s *Server) handleCreateTask(w http.ResponseWriter, r *http.Request) {
    	var req struct {
    		Title string `json:"title"`
    	}
    
    	dec := json.NewDecoder(r.Body)
    	dec.DisallowUnknownFields()
    	if err := dec.Decode(&req); err != nil {
    		// Klasse 1: unlesbares oder schemafremdes JSON
    		writeJSON(w, http.StatusBadRequest,
    			map[string]string{"error": "unlesbares JSON: " + err.Error()})
    		return
    	}
    
    	// Klasse 2: JSON korrekt, Inhalt verboten
    	req.Title = strings.TrimSpace(req.Title)
    	if req.Title == "" {
    		writeJSON(w, http.StatusUnprocessableEntity,
    			map[string]string{"error": "title darf nicht leer sein"})
    		return
    	}
    
    	task := s.store.Add(req.Title)
    	w.Header().Set("Location", "/tasks/"+strconv.Itoa(task.ID))
    	writeJSON(w, http.StatusCreated, task)
    }
    
    // Terminal: curl -i -X POST localhost:8080/tasks -d '{"title":"On-Call-Rotation prüfen"}'
    // → HTTP/1.1 201 Created
    // → Content-Type: application/json
    // → Location: /tasks/7
    // → {"id":7,"title":"On-Call-Rotation prüfen","done":false}
    

    Die drei Fehlerklassen in der Praxis

    Der Unterschied zwischen den Klassen ist nicht Kosmetik, sondern Debugging-Zeit. Ein curl-Lauf gegen die fertige API zeigt alle drei:

    // Terminal: die drei Fehlerklassen im Vergleich
    //
    // kaputtes JSON (Syntaxfehler) → 400
    // → $ curl -s -i -X POST localhost:8080/tasks -d '{"title":'
    // → HTTP/1.1 400 Bad Request
    // → {"error":"unlesbares JSON: unexpected EOF"}
    //
    // unbekanntes Feld (Schema-Verletzung dank DisallowUnknownFields) → 400
    // → $ curl -s -i -X POST localhost:8080/tasks -d '{"titel":"Tippfehler"}'
    // → HTTP/1.1 400 Bad Request
    // → {"error":"unlesbares JSON: json: unknown field \"titel\""}
    //
    // gültiges JSON, verbotener Inhalt → 422
    // → $ curl -s -i -X POST localhost:8080/tasks -d '{"title":"   "}'
    // → HTTP/1.1 422 Unprocessable Entity
    // → {"error":"title darf nicht leer sein"}
    

    Ohne DisallowUnknownFields würde der zweite Fall still durchgehen: Der Tippfehler titel würde ignoriert, Title bliebe leer, und der Client bekäme eine 422 mit »title darf nicht leer sein« — eine irreführende Fehlermeldung, weit weg von der eigentlichen Ursache. Striktes Dekodieren verwandelt den Tippfehler in eine sofortige, präzise Antwort. Für Feld-Semantiken, die über »nicht leer« hinausgehen (Formate, Längen, Bereiche), reicht im Zweifel eine handgeschriebene validate-Methode — Validierungs-Frameworks braucht man in Go erst, wenn die Regeln ein Dutzend überschreiten.

    ⚠ Häufiger Fehler: w.Header().Set("Content-Type", "application/json") erst NACH w.WriteHeader(...) oder dem ersten Write aufrufen. Header gehen mit dem Status auf die Reise — der spätere Set wird stillschweigend ignoriert. Der Client rät dann per Content-Sniffing (meist auf text/plain), und strikte JSON-Clients brechen mit kryptischen Parse-Fehlern ab, obwohl der Body perfekt ist. Reihenfolge immer: Header setzen, dann Status, dann Body.

    ✅ Wichtige Erkenntnisse

    Haken setzen, um deinen Lernfortschritt zu markieren:

      48

      Middleware: Logging, Recovery & Timeouts

      Lektion 48 von 100

      Panics, die niemand sieht

      Der Service läuft zwei Wochen stabil — bis der Berichts-Endpoint bei einer bestimmten Abfrage auf ein nil-Feld greift und panikt. Was passiert? Der Prozess stirbt nicht: net/http fängt Panics pro Verbindung ab und loggt http: panic serving. Aber der Client bekommt keine saubere 500-Antwort, sondern nur eine abgebrochene Verbindung — und im Access-Log steht keine Zeile zu dem Request. Um 3 Uhr nachts will man aber genau zwei Dinge wissen: Welche Route war es, und wie lange lief sie.

      Die Antwort ist Middleware: eine Funktion, die einen Handler umhüllt und einen neuen Handler zurückgibt — func(http.Handler) http.Handler. Kein Framework, keine Interfaces-Hierarchie, keine Magie. Die Middleware kann vor dem Aufruf arbeiten (Request loggen, Body prüfen), den Aufruf selbst überwachen (recover, Timeout) und nach dem Aufruf aufräumen.

      Middleware ist eine Funktion — die Reihenfolge ist Ausführungsreihenfolge

      Gestapelt entsteht eine Zwiebel: Bei Chain(mux, Recovery, Logging) läuft ein Request erst durch Recovery, dann Logging, dann den Handler — und die Antwort läuft rückwärts wieder heraus. Was außen liegt, sieht alles Darunterliegende: Recovery fängt deshalb auch Panics aus der Logging-Middleware, nicht nur aus Handlern. Wer die Reihenfolge dreht, dreht die Verantwortung.

      Zuerst Logging. Die einzige Hürde: Der ResponseWriter verrät den gesetzten Statuscode nicht zurück. Die Lösung ist ein kleines Wrapper-Struct, das WriteHeader abfängt und mitprotokolliert:

      // middleware/middleware.go
      package middleware
      
      import (
      	"log"
      	"net/http"
      	"time"
      )
      
      // Middleware umhüllt einen Handler und gibt einen neuen zurück.
      type Middleware func(http.Handler) http.Handler
      
      // Chain stapelt Middleware: Chain(h, A, B) liefert A(B(h)) —
      // A liegt außen und läuft zuerst.
      func Chain(h http.Handler, mw ...Middleware) http.Handler {
      	for i := len(mw) - 1; i >= 0; i-- {
      		h = mw[i](h)
      	}
      	return h
      }
      
      // statusRecorder merkt sich den Statuscode des inneren Handlers.
      type statusRecorder struct {
      	http.ResponseWriter
      	status int
      }
      
      func (r *statusRecorder) WriteHeader(code int) {
      	r.status = code
      	r.ResponseWriter.WriteHeader(code)
      }
      
      func WithLogging(next http.Handler) http.Handler {
      	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
      		start := time.Now()
      		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
      		next.ServeHTTP(rec, r)
      		log.Printf("%s %s -> %d (%s)",
      			r.Method, r.URL.Path, rec.status, time.Since(start).Round(time.Microsecond))
      	})
      }
      
      // Terminal: curl localhost:8080/tasks
      // → 2026/11/05 21:14:03 GET /tasks -> 200 (213µs)
      

      Ein ehrlicher Hinweis: Für Streaming-Antworten müsste der Recorder zusätzlich Flush() weiterreichen (Stichwort http.Flusher, Modul 4). Für JSON-Antworten, die in einem Stück geschrieben werden, reicht er exakt so.

      Recovery und Timeouts: der Schutzschild-Gürtel

      Recovery-Middleware nutzt nichts als defer/recover und runtime/debug.Stack() — und verwandelt einen Panic in eine saubere 500-Antwort mit Stacktrace im Server-Log:

      // middleware/recovery.go
      package middleware
      
      import (
      	"encoding/json"
      	"log"
      	"net/http"
      	"runtime/debug"
      )
      
      func WithRecovery(next http.Handler) http.Handler {
      	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
      		defer func() {
      			if err := recover(); err != nil {
      				log.Printf("panic in %s %s: %v\n%s",
      					r.Method, r.URL.Path, err, debug.Stack())
      				w.Header().Set("Content-Type", "application/json")
      				w.WriteHeader(http.StatusInternalServerError)
      				json.NewEncoder(w).Encode(map[string]string{"error": "interner Fehler"})
      			}
      		}()
      		next.ServeHTTP(w, r)
      	})
      }
      
      // server/main.go — Verkabelung: Recovery außen, Logging innen
      func main() {
      	mux := newMux() // die Routen aus Lektion 46 und 47
      	handler := middleware.Chain(mux, middleware.WithRecovery, middleware.WithLogging)
      	log.Println("Server lauscht auf :8080")
      	log.Fatal(http.ListenAndServe(":8080", handler))
      }
      
      // Terminal: curl -s -i localhost:8080/report/huge
      // → HTTP/1.1 500 Internal Server Error
      // → {"error":"interner Fehler"}
      //
      // Server-Log, Stacktrace gekürzt:
      // → panic in GET /report/huge: runtime error: invalid memory address or nil pointer dereference
      

      Das dritte Standardelement sind Timeouts. Nicht jeder Handler ist schnell: Ein Bericht über die eigene http.Client-Schnittstelle kann hängen, während der Client längst weg ist. http.TimeoutHandler stoppt einzelne Routen nach einer Frist und antwortet mit 503:

      // Timeout pro Route: nach 5s Bearbeitungszeit ist Schluss
      mux.Handle("GET /report", http.TimeoutHandler(
      	reportHandler,
      	5*time.Second,
      	`{"error":"Bearbeitung dauerte zu lange"}`,
      ))
      
      // Terminal: curl -s -i --max-time 10 localhost:8080/report
      // → HTTP/1.1 503 Service Unavailable
      // → {"error":"Bearbeitung dauerte zu lange"}
      

      Dazu kommen die Server-weiten Timeouts aus der nächsten Lektion — TimeoutHandler begrenzt die Bearbeitungszeit pro Route, ReadHeaderTimeout und Kollegen begrenzen die Verbindung selbst.

      ⚠ Häufiger Fehler: Logging-Middleware, die für Audit-Logs den Request-Body mitliest — etwa per io.ReadAll(r.Body) — und ihn nicht zurücksetzt. Der nächste Decode im Handler liest dann nur noch EOF: Jeder POST kommt mit leerem Body an, und die Validierung aus Lektion 47 meldet »title darf nicht leer sein«, obwohl der Client alles korrekt geschickt hat. Wer den Body in Middleware lesen muss: einlesen, dann vor next.ServeHTTP mit r.Body = io.NopCloser(bytes.NewReader(buf)) zurücksetzen.

      ✅ Wichtige Erkenntnisse

      Haken setzen, um deinen Lernfortschritt zu markieren:

        49

        Graceful Shutdown & Produktions-Konfiguration

        Lektion 49 von 100

        Deploy um 14:32 — ohne einen Request zu verlieren

        Am Montag um 14:32 rollt Kubernetes die neue Version aus und sendet SIGTERM. Der naive Server stirbt mittendrin — und ein Request, der gerade einen Task in die Datenbank schreibt, bleibt halbfertig liegen. Graceful Shutdown ist der Unterschied zwischen »Deploy« und »Datenverlust«: neue Requests ablehnen, laufende in Ruhe fertigstellen, dann erst aussteigen.

        Das Werkzeug dafür ist signal.NotifyContext: Es verwandelt SIGINT (Strg+C) und SIGTERM (Container, systemd) in einen gewöhnlichen Kontext-Ablauf — denselben Mechanismus, den wir seit Modul 7 für Timeouts und Abbruch nutzen. Dazu der http.Server als Wert statt http.ListenAndServe als Einzeiler, denn nur der Typ bringt Shutdown und die Timeouts mit.

        Graceful Shutdown ist ein Dreiklang

        Erstens: Listener sofort schließen — neue Verbindungen werden abgewiesen. Zweitens: laufende Requests auslaufen lassen — der Store darf seine Transaktion zu Ende schreiben. Drittens: nach einer Frist aufgeben — Shutdown kehrt dann mit dem Fehler des Kontexts zurück. Die Frist gehört dazu, weil ein hängender Request sonst das Herunterfahren blockiert und der Orchestrierer irgendwann SIGKILL schickt, das noch weniger gnädig ist.

        Das komplette produktive main — Signal-Handling, Server-Konfiguration und geordnetes Auslaufen:

        // taskd/main.go
        package main
        
        import (
        	"context"
        	"errors"
        	"log"
        	"net/http"
        	"os"
        	"os/signal"
        	"syscall"
        	"time"
        )
        
        func main() {
        	srv := &http.Server{
        		Addr:              ":8080",
        		Handler:           newHandler(), // Mux + Middleware aus Lektion 48
        		ReadHeaderTimeout: 5 * time.Second,
        		ReadTimeout:       10 * time.Second,
        		WriteTimeout:      15 * time.Second,
        		IdleTimeout:       60 * time.Second,
        	}
        
        	// SIGINT (Strg+C) und SIGTERM (Container) abonnieren
        	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
        	defer stop()
        
        	errCh := make(chan error, 1)
        	go func() {
        		// ErrServerClosed kommt bei sauberem Shutdown — das ist KEIN Fehler
        		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        			errCh <- err
        		}
        	}()
        
        	select {
        	case err := <-errCh:
        		log.Fatalf("Server-Fehler: %v", err)
        	case <-ctx.Done():
        		log.Println("Signal empfangen — laufende Requests dürfen auslaufen")
        
        		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
        		defer cancel()
        		if err := srv.Shutdown(shutdownCtx); err != nil {
        			log.Printf("Frist abgelaufen, erzwinge Stopp: %v", err)
        		}
        	}
        	log.Println("Server sauber beendet")
        }
        
        // Terminal: Strg+C, während ein langsamer GET /report noch läuft
        // → 2026/11/05 21:30:01 Server lauscht auf :8080
        // → 2026/11/05 21:31:44 Signal empfangen — laufende Requests dürfen auslaufen
        // → 2026/11/05 21:31:46 GET /report -> 200 (3.9s)   ← der Request durfte enden
        // → 2026/11/05 21:31:46 Server sauber beendet
        

        Shutdown, Close — und die Timeouts als Rüstung

        Shutdown ist der Standardweg, aber nicht das einzige Werkzeug. Und die Timeouts am Server sind keine Option, sondern Rüstung gegen Angriffe und Trottel-Clients:

        // Shutdown oder Close?
        //
        //	srv.Shutdown(ctx) // Listener sofort zu; laufende Requests auslaufen
        //	                  // lassen, höchstens bis ctx abläuft — Standardweg
        //	srv.Close()       // alle Verbindungen SOFORT trennen — Notbremse,
        //	                  // laufende Requests brechen mitten im Body ab
        //
        // Und ohne die Timeouts ist der Server offen für Slowloris:
        // ein Client, der Header in Zeitlupe sendet, hält sonst Verbindungen
        // und Datei-Deskriptoren beliebig lange offen.
        srv := &http.Server{
        	Addr:              ":8080",
        	Handler:           handler,
        	ReadHeaderTimeout: 5 * time.Second,  // Slowloris-Schutz
        	ReadTimeout:       10 * time.Second, // Zeit für den kompletten Request
        	WriteTimeout:      15 * time.Second, // Zeit für die Antwort
        	IdleTimeout:       60 * time.Second, // Keep-Alive-Pause zwischen Requests
        }
        
        // Terminal: ein Client, der Header in Zeitlupe sendet (Slowloris)
        // → curl: (28) Operation timed out — der Server trennt nach 5 Sekunden
        

        Zum Abschluss der ehrliche Blick auf BaseContext und Co.: Sobald einzelne Handler Minuten dauern dürfen (lange Exporte), lohnt es sich, in ihnen r.Context() zu respektieren — ein abgebrochener Client sollte auch den Handler stoppen lassen. Das ist keine Shutdown-Sonderlogik, sondern gewöhnliche Kontext-Disziplin aus Modul 7.

        ⚠ Häufiger Fehler: log.Fatal(http.ListenAndServe(":8080", mux)) in der Haupt-Goroutine. Bei jedem sauberen Shutdown gibt ListenAndServe den erwarteten Wert http.ErrServerClosed zurück — und log.Fatal behandelt die erfolgreiche Neu-Ausrollung als Absturz: Exit-Code 1, Alert um 3 Uhr nachts, Deploy-Pipeline rot. Richtig: ListenAndServe in einer Goroutine starten, den Fehler prüfen und errors.Is(err, http.ErrServerClosed) als Erfolg werten.

        ✅ Wichtige Erkenntnisse

        Haken setzen, um deinen Lernfortschritt zu markieren:

          50

          CLI-Tools mit flag & ein REST-Capstone

          Lektion 50 von 100

          Ein Binary, viele Gesichter

          Der Server ist nur die halbe Miete. Ops will ihn starten, du willst ihn lokal testen, und in der Deploy-Pipeline steht am Ende ein einzelnes Binary, das in jeden Container passt. Go-Dienste werden deshalb traditionell als CLI mit Unterbefehlen ausgeliefert: tasksrv serve startet die API, tasksrv version verrät, was im Container liegt. Das flag-Paket der Standardbibliothek bringt Subcommands und Flags ohne eine einzige Abhängigkeit bei — für Werkzeuge dieser Größe reicht es vollständig aus.

          Das Muster ist immer gleich: os.Args[1] entscheidet über den Befehl, jeder Befehl bekommt sein eigenes flag.NewFlagSet und parst nur seinen eigenen Argumentteil.

          Flags für Menschen, Umgebungsvariablen für Maschinen

          In der Konsole tippst du --addr :7070; im Container kommt die Konfiguration als Umgebungsvariable. Die etablierte Rangfolge lautet: Flag schlägt Env, Env schlägt Default. Technisch ist das ein Einzeiler — der Default des Flags ist bereits der Env-Wert: Wer das Flag setzt, gewinnt; wer nur die Variable setzt, bekommt sie; wer nichts setzt, bekommt den festen Default.

          // main.go — ein Binary, mehrere Befehle
          package main
          
          import (
          	"flag"
          	"fmt"
          	"os"
          )
          
          func main() {
          	if len(os.Args) < 2 {
          		fmt.Fprintln(os.Stderr, "Benutzung: tasksrv (serve|version) [flags]")
          		os.Exit(2)
          	}
          
          	switch os.Args[1] {
          	case "serve":
          		cmdServe(os.Args[2:])
          	case "version":
          		fmt.Println("tasksrv v1.4.0")
          	default:
          		fmt.Fprintln(os.Stderr, "unbekannter Befehl:", os.Args[1])
          		os.Exit(2)
          	}
          }
          
          func cmdServe(args []string) {
          	fs := flag.NewFlagSet("serve", flag.ExitOnError)
          	addr := fs.String("addr", envOrDefault("TASKSRV_ADDR", ":8080"), "Listen-Adresse")
          	fs.Parse(args)
          
          	fmt.Println("tasksrv lauscht auf", *addr)
          	runServer(*addr) // der fertige Server aus den Lektionen 46 bis 49
          }
          
          // Terminal: go run . serve --addr :9090
          // → tasksrv lauscht auf :9090
          //
          // Terminal: go run . version
          // → tasksrv v1.4.0
          //
          // Terminal: go run . help
          // → unbekannter Befehl: help     (Exit-Code 2)
          

          flag.ExitOnError sorgt für sinnvolle Automatik: Ein falsches Flag druckt die Nutzung des FlagSets und beendet mit Exit-Code 2 — genau der Code, an dem Skripte einen Nutzerfehler erkennen. Wer das selbst behandeln will, wählt flag.ContinueOnError und prüft den Fehler von fs.Parse.

          Die Env-Fallback-Hilfsfunktion ist bewusst unspektakulär — drei Zeilen, keine Abhängigkeit:

          // config/config.go
          package config
          
          import "os"
          
          // envOrDefault liefert den Wert der Umgebungsvariable oder den Default.
          func envOrDefault(key, def string) string {
          	if v := os.Getenv(key); v != "" {
          		return v
          	}
          	return def
          }
          
          // Der Default des -addr-Flags ist bereits der Env-Wert: Rangfolge
          // Flag über Env über Default, ohne weitere Logik.
          func serveFlags(args []string) *flag.FlagSet {
          	fs := flag.NewFlagSet("serve", flag.ExitOnError)
          	fs.String("addr", envOrDefault("TASKSRV_ADDR", ":8080"), "Listen-Adresse")
          	return fs
          }
          
          // Terminal: TASKSRV_ADDR=:9443 go run . serve
          // → tasksrv lauscht auf :9443
          //
          // Terminal: TASKSRV_ADDR=:9443 go run . serve --addr :7070
          // → tasksrv lauscht auf :7070
          

          Der Capstone: alles aus diesem Modul in einem Binary

          Damit ist der Werkzeugkasten zu. Der Capstone verbindet die Teile: den Router aus Lektion 46, die JSON-Verträge aus Lektion 47, das Middleware-Dreigestirn aus Lektion 48, das Signal-Handling aus Lektion 49 — gestartet über die CLI dieser Lektion. Ein Härtetest von außen:

          // Terminal: der fertige Capstone im Einsatz
          //
          // → $ tasksrv serve --addr :8080
          // → tasksrv lauscht auf :8080
          //
          // → $ curl -s -X POST localhost:8080/tasks -d '{"title":"Capstone abgeben"}'
          // → angelegt: #1 Capstone abgeben
          //
          // → $ curl -s localhost:8080/tasks/1
          // → #1 Capstone abgeben (erledigt: false)
          //
          // → $ curl -s -i -X POST localhost:8080/tasks -d '{"titel":"Tippfehler"}'
          // → HTTP/1.1 400 Bad Request
          // → {"error":"unlesbares JSON: json: unknown field \"titel\""}
          //
          // → $ tasksrv version
          // → tasksrv v1.4.0
          

          Von der ersten curl-Antwort bis hierher waren es fünf Lektionen — und keine Zeile Framework-Code. Genau das ist die Stärke von net/http: Der komfortable Pfad und der korrekte Pfad sind derselbe.

          ⚠ Häufiger Fehler: Flags hinter Positionsargumente schreiben. tasksrv import --verbose alte.xml funktioniert, tasksrv import alte.xml --verbose nicht: Der flag-Parser stoppt beim ersten Argument, das nicht mit - beginnt — --verbose landet ungeparst in fs.Args(), als wäre es eine Datei. Flags gehören vor die Positionsargumente; wer das nicht mag, prüft fs.Args() selbst oder greift für GNU-Stil-Parsing zu einer Bibliothek.

          Modul 10 im Rückblick

          Damit endet der Go-Kurs: Vom ersten fmt.Println in Modul 1 über Slices, Structs, Goroutines, Fehlerbehandlung und Tests bis zu einem Dienst, der produktionsreif startet, antwortet und herunterfährt. Modul 10 hat die letzte Lücke geschlossen — HTTP und CLI, beides mit der Standardbibliothek.

          Wochen-Check: Beherrschst du diese Punkte?

          1. Kannst du einen Router mit Methoden-Patterns und Wildcards aufsetzen und weißt, welches Pattern bei Überlappung gewinnt?
          2. Antworte auf die drei Fehlerklassen (kaputtes JSON, unzulässiger Inhalt, Server-Fehler) mit 400, 422 und 500 — aus dem Kopf?
          3. Weißt du, warum Recovery außen und Logging innen liegt — und was im Log fehlt, wenn du es verdrehst?
          4. Kannst du einen Server mit signal.NotifyContext sauber herunterfahren und http.ErrServerClosed korrekt behandeln?
          5. Kannst du ein Binary mit Subcommands bauen, in dem Flags Umgebungsvariablen schlagen?

          ✅ Wichtige Erkenntnisse

          Haken setzen, um deinen Lernfortschritt zu markieren:

            This site uses essential cookies for Stripe payments. No tracking cookies.