Skip to content

Modul 12: Web-Frameworks & Datenzugriff

Die Go-Webwelt sicher navigieren: Router-Vergleich von net/http 1.22 über chi bis Gin, Echo und Fiber, Middleware-Ketten für Logging, Auth und Recovery, Datenzugriff mit GORM, sqlc, sqlx und pgx, CLI & Konfiguration mit Cobra und Viper — und als Praxisprojekt eine Bookstore-API mit Gin und sqlc.

Fortschritt0/5 Lektionen
56

Router & Frameworks: net/http 1.22, chi, Gin, Echo, Fiber

Lektion 56 von 100

Die Buchhandlung braucht einen Shop — und eine Router-Entscheidung

Die Buchhandlung »Kant & Kurve« will ihren Lagerbestand online stellen. Der Plan umfasst rund dreißig Routen, einen öffentlichen Bereich unter /api/v1, einen Admin-Bereich und später eine OpenAPI-Beschreibung. Im Team steht die erste Architektur-Frage an: Welches Framework nehmen wir? Die ehrliche Go-Antwort beginnt mit einem Dämpfer: net/http kann Methoden-Patterns und Wildcards seit Go 1.22 ganz ohne Zusatz-Paket (Lektion 46) — für die reine Routen-Auflösung braucht es kein Framework. Frameworks verkaufen Ergonomie: Routen-Gruppen, eingebaute Middleware, Bindung von JSON an Structs, generierte Hilfe und ein Ökosystem aus fertigen Bausteinen.

Die Kandidaten mit ihren exakten Import-Pfaden: chi (github.com/go-chi/chi/v5) bleibt zu 100 % mit net/http kompatibel — Handler, Middleware und http.Server bleiben unverändert. Gin (github.com/gin-gonic/gin) bringt das größte Ökosystem mit und eine eigene Handler-Signatur (*gin.Context). Echo (github.com/labstack/echo/v4) nimmt eine Mittelstellung ein: eigene, schlanke Handler mit Fehler-Rückgabe, aber net/http darunter. Fiber (github.com/gofiber/fiber/v2) verspricht Express-Feeling und Durchsatz — baut aber auf fasthttp, nicht auf net/http, und tauscht damit die Fundamente unter den Füßen aus.

Egal wie die Entscheidung ausfällt: Die REST-Konventionen — Ressourcen als Substantive, saubere Statuscodes, Versionierung über den Pfad — kommen nicht aus dem Router, sondern aus dem API-Design. Der Architektur-Kurs behandelt sie in Modul 5: API-Design; Gin und Echo setzen diese Regeln später nur um. Wer sie am Router »erfindet«, zahlt mit Inkonsistenzen, die Clients teuer zu spüren bekommen.

Der Router ist austauschbar — die Domäne ist es nicht

Alle vier Kandidaten lösen dasselbe Problem: einen Pfad plus Methode auf eine Funktion zu mappen. Deine Handler-Kerne — Katalog, Warenkorb, Preise — kennen den Router nicht. Halte die Handler deshalb dünn: parsen, Domäne aufrufen, antworten. Dann ist der Router eine Entscheidung für ein Quartal, nicht für die Ewigkeit, und ein Wechsel berührt nur die Rand-Schicht.

Derselbe Endpoint zweimal — zuerst chi, vollständig im net/http-Stil:

// internal/router/router.go — chi: Gruppen und Middleware, bleibt net/http
package router

import (
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
)

func New(list ListBooks, byISBN BookByISBN) http.Handler {
	r := chi.NewRouter()
	r.Use(middleware.RequestID) // X-Request-Id erzeugen, falls der Client keine schickt
	r.Use(middleware.Recoverer) // Panics werden zu sauberen 500ern
	r.Use(middleware.Logger)    // Access-Log ohne eigene Arbeit

	r.Route("/api/v1", func(api chi.Router) {
		api.Get("/books", func(w http.ResponseWriter, r *http.Request) {
			writeJSON(w, http.StatusOK, list(r.Context()))
		})
		api.Get("/books/{isbn}", func(w http.ResponseWriter, r *http.Request) {
			b, err := byISBN(r.Context(), chi.URLParam(r, "isbn"))
			if err != nil {
				http.NotFound(w, r)
				return
			}
			writeJSON(w, http.StatusOK, b)
		})
	})
	return r
}

// Terminal: curl -s localhost:8080/api/v1/books/978-3-423-2089-8
// → {"isbn":"978-3-423-2089-8","title":"Der Alchimist","author":"Paulo Coelho","price_cents":1295,"stock":3}

Jetzt Gin — dieselben zwei Routen, kürzere Handler, eigenes Context-Objekt:

// cmd/server/main.go — Gin: Gruppen, Bindung und Middleware-Kette inklusive
package main

import (
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default() // = gin.New() + Logger + Recovery, fertig verdrahtet

	v1 := r.Group("/api/v1")
	{
		v1.GET("/books/:isbn", func(c *gin.Context) {
			b, err := fetchBook(c.Request.Context(), c.Param("isbn"))
			if err != nil {
				c.JSON(http.StatusNotFound, gin.H{"error": "Buch nicht gefunden"})
				return
			}
			c.JSON(http.StatusOK, b)
		})
	}

	log.Fatal(r.Run(":8080"))
}

// Terminal: curl -s localhost:8080/api/v1/books/978-3-423-2089-8
// → {"isbn":"978-3-423-2089-8","title":"Der Alchimist","author":"Paulo Coelho","price_cents":1295,"stock":3}

Echo und Fiber im Direktvergleich — gleicher Pfad, unterschiedliche Handler-Verträge:

// Vergleich: derselbe Endpoint in Echo und Fiber
func echoRoutes(e *echo.Echo) {
	e.GET("/api/v1/books/:isbn", func(c echo.Context) error {
		return c.JSON(http.StatusOK, fetchBook(c.Request.Context(), c.Param("isbn")))
	})
}

func fiberRoutes(app *fiber.App) {
	app.Get("/api/v1/books/:isbn", func(c *fiber.Ctx) error {
		return c.Status(http.StatusOK).JSON(fetchBook(c.Request.Context(), c.Params("isbn")))
	})
}

// Terminal: curl -s localhost:8080/api/v1/books/978-3-423-2089-8
// → {"isbn":"978-3-423-2089-8", ...} — Echo und Fiber, identischer Pfad, identische Antwort

Der eigentliche Unterschied liegt nicht in der Syntax, sondern im Fundament:

RouterPaketBasisMiddleware-Typ
net/httpStandardbibliotheknet/httpfunc(http.Handler) http.Handler
chigithub.com/go-chi/chi/v5net/httpidentisch zur Standardbibliothek
Gingithub.com/gin-gonic/gineigenes Routingfunc(*gin.Context)
Echogithub.com/labstack/echo/v4eigener Handler-Vertragecho.MiddlewareFunc
Fibergithub.com/gofiber/fiber/v2fasthttpfunc(*fiber.Ctx) error

Für die Buchhandlung fällt die Entscheidung so: Das Team kennt net/http aus Modul 10 gründlich — chi wäre der risikoärmste Zuwachs. Das Gin-Ökosystem (Bindung, Validierung, fertige Middleware) spart aber bei dreißig Routen spürbar Zeit. Gewählt wird Gin für die API-Schicht; die Domäne bleibt routerfrei. Genau diese Trennung zahlt sich in Lektion 60 aus.

⚠ Häufiger Fehler: Routen 1:1 von net/http nach Gin portieren und sich über die Panic beim Start wundern. Der ServeMux löst GET /books/new neben GET /books/{isbn} still auf — das wörtliche Segment gewinnt (Lektion 46). Gins httprouter-Baum erlaubt an derselben Position nur ein Wildcard-Muster und stirbt beim Registrieren mit einem Konflikt wie conflicts with existing wildcard. Jeder Router hat eigene Präzedenz-Regeln: Nach einem Router-Wechsel einmal die komplette Routen-Tabelle durchtesten, bevor irgendetwas in Produktion geht.

✅ Wichtige Erkenntnisse

Haken setzen, um deinen Lernfortschritt zu markieren:

    57

    Middleware-Engineering: Logging, Auth & Recovery als Chains

    Lektion 57 von 100

    Der Admin-Bereich darf nicht offen sein

    Der Shop wächst, und mit ihm die Anforderungen: POST /api/v1/admin/books darf nur Mitarbeiter mit gültigem Token aufrufen, jede Antwort soll im Log mit Request-ID auffindbar sein, und ein panicender Handler darf die Verbindung nicht abreißen lassen. In Modul 10 (Lektion 48) hast du diese Zwiebel von Hand gebaut — func(http.Handler) http.Handler, Recovery außen, Logging innen. Jetzt industrialisieren wir das: Frameworks liefern die Kette fertig, aber die Engineering-Fragen bleiben dieselben: In welcher Reihenfolge? Wie kommen Werte wie der eingeloggte User in den Handler? Und was passiert bei einem Abbruch mittendrin?

    Die Kernidee für Werte: Request-bezogene Daten reisen im Kontext, nie in globalen Variablen. Gin parkt sie mit c.Set/c.MustGet im gin.Context, chi und net/http nutzen context.WithValue mit einem privaten Key-Typ — Goroutine-frei, Race-frei, automatisch am Ende des Requests weg.

    Die Reihenfolge der Kette ist Sicherheits-Entscheidung

    Gestapelt gilt weiterhin die Zwiebel aus Lektion 48: Ganz außen Recovery (sie fängt Panics aus ALLEM darunterliegenden), danach Request-ID und Logging, erst dann Auth, dann der Handler. Liegt Auth außen und Logging innen, fehlen abgewiesene Requests im Log — und du wunderst dich über 401er, die offiziell nie passiert sind. Logging VOR Auth heißt dagegen: Auch Angriffsversuche landen strukturiert im Log.

    Die Auth-Middleware in Gin — Bearer-Token parsen, User nachschlagen, im Kontext ablegen:

    // internal/api/middleware.go
    package api
    
    import (
    	"net/http"
    	"strings"
    
    	"github.com/gin-gonic/gin"
    )
    
    // RequireUser prüft den Bearer-Token und legt den User in den Request-Kontext.
    func RequireUser(users UserLookup) gin.HandlerFunc {
    	return func(c *gin.Context) {
    		token, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
    		if !ok {
    			c.AbortWithStatusJSON(http.StatusUnauthorized,
    				gin.H{"error": "Bearer-Token erforderlich"})
    			return // Pflicht! Abort stoppt die Kette, NICHT diese Funktion
    		}
    		u, err := users.ByToken(c.Request.Context(), token)
    		if err != nil {
    			c.AbortWithStatusJSON(http.StatusUnauthorized,
    				gin.H{"error": "Token ungültig oder abgelaufen"})
    			return
    		}
    		c.Set("user", u)
    		c.Next()
    	}
    }
    
    // Verdrahtung: Admin-Gruppe schützt alles darunter in einem Rutsch
    admin := r.Group("/api/v1/admin")
    admin.Use(RequireUser(users))
    {
    	admin.POST("/books", addBook)
    }
    
    func addBook(c *gin.Context) {
    	u := c.MustGet("user").(User) // aus der Middleware, typsicher per Assertion
    	c.JSON(http.StatusCreated, gin.H{"angelegt von": u.Name})
    }
    
    // Terminal: curl -s -X POST localhost:8080/api/v1/admin/books
    // → {"error":"Bearer-Token erforderlich"}      (HTTP 401)
    //
    // Terminal: curl -s -X POST localhost:8080/api/v1/admin/books -H "Authorization: Bearer $TOKEN"
    // → {"angelegt von":"Lena"}                    (HTTP 201)
    

    Für die chi-/net/http-Welt dasselbe Muster mit strukturiertem Logging — log/slog gibt es seit Go 1.21 in der Standardbibliothek:

    // internal/api/slogmw.go — Request-ID und strukturiertes Logging mit slog
    package api
    
    import (
    	"context"
    	"fmt"
    	"log/slog"
    	"net/http"
    	"time"
    )
    
    type ctxKey int
    
    const requestIDKey ctxKey = 1
    
    func WithRequestID(next http.Handler) http.Handler {
    	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    		id := r.Header.Get("X-Request-Id")
    		if id == "" {
    			id = fmt.Sprintf("req-%d", time.Now().UnixNano())
    		}
    		w.Header().Set("X-Request-Id", id)
    		next.ServeHTTP(w, r.WithContext(
    			context.WithValue(r.Context(), requestIDKey, id)))
    	})
    }
    
    func WithSlog(logger *slog.Logger) func(http.Handler) http.Handler {
    	return func(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} // aus Lektion 48
    			next.ServeHTTP(rec, r)
    			logger.Info("request",
    				"request_id", r.Context().Value(requestIDKey),
    				"method", r.Method,
    				"path", r.URL.Path,
    				"status", rec.status,
    				"dur_ms", time.Since(start).Milliseconds(),
    			)
    		})
    	}
    }
    
    // Terminal: curl -s localhost:8080/api/v1/books
    // → {"time":"2026-11-05T21:40:12+01:00","level":"INFO","msg":"request",
    // →  "request_id":"req-1790943612345678901","method":"GET","path":"/api/v1/books","status":200,"dur_ms":3}
    

    Das Log ist jetzt maschinell auswertbar — jedes Feld einzeln abfragbar statt per Regex aus einer Textzeile gefischt. Später im Betrieb wirst du Spans von OpenTelemetry (go.opentelemetry.io/otel) genau an dieser Stelle einhängen; Modul 13 zeigt wie. Die Kette wird dabei nur um ein weiteres Glied länger, die Zwiebel-Logik bleibt.

    ⚠ Häufiger Fehler: c.AbortWithStatusJSON(401, ...) aufrufen und danach munter weiterarbeiten — ohne return. Abort setzt nur ein Flag, das die RESTLICHE Kette ausbremst; der eigene Funktionsrumpf läuft weiter. Typische Folge: nach dem Abort wird nochmal geschrieben oder umgeleitet, und die Antwort enthält Müll oder Gin loggt superfluous response.WriteHeader. Nach jedem Abort gehört ein return — die Middleware oben führt das explizit vor.

    ✅ Wichtige Erkenntnisse

    Haken setzen, um deinen Lernfortschritt zu markieren:

      58

      Datenzugriff: GORM vs sqlc vs sqlx vs pgx

      Lektion 58 von 100

      Der Lagerbestand zieht in die Datenbank — mit welchem Werkzeug?

      Bisher wohnen die Bücher im Speicher; beim ersten Neustart wären sie weg. Der Umzug in PostgreSQL steht an, und im Team tobt die klassische Grundsatzdiskussion: ORM für Geschwindigkeit in der Entwicklung oder SQL für Geschwindigkeit im Betrieb? Das ist keine Go-Sonderheit, sondern eine Datenarchitektur-Entscheidung — Modul 6: Datenarchitektur behandelt ORM vs. Codegen als Muster mit langen Folgen. Hier die vier Go-Kandidaten, ehrlich sortiert:

      github.com/jackc/pgx/v5 ist der PostgreSQL-Treiber mit Verbindungspool (pgxpool) — sehr schnell, volles SQL, aber jede Abfrage von Hand. github.com/jmoiron/sqlx legt sich als dünne Schicht über database/sql und scannt Zeilen direkt in Structs (StructScan) — bequem, aber der Spaltencast passiert erst zur Laufzeit. GORM (gorm.io/gorm mit gorm.io/driver/postgres) ist das vollwertige ORM: Assoziationen, Hooks, AutoMigrate — und eine Abstraktion, die bei komplexen Joins und Bulk-Operationen leckt. sqlc (github.com/sqlc-dev/sqlc, als CLI installiert) dreht den Ansatz um: Du schreibst das SQL, sqlc generiert daraus typsicheren Go-Code — der Fehlerzeitpunkt wandert von der Laufzeit zur Codegenerierung.

      sqlc: SQL ist der Vertrag — der Compiler prüft ihn mit

      Bei sqlc steht das SQL in einer Query-Datei, annotiert mit -- name: GetBookByISBN :one. sqlc generate erzeugt daraus eine Go-Funktion mit passender Signatur und einem Struct pro Spaltentupel. Ein Tippfehler im Spaltennamen, ein falscher Parametertyp — beides fällt beim Generieren auf, nicht um 3 Uhr nachts im Betrieb. Geschrieben wird immer noch echtes SQL; gewonnen wird Typsicherheit über dem, was die Datenbank wirklich kann.

      Der sqlc-Weg — zuerst die Query-Datei (Handarbeit), dann der generierte Aufrufer:

      -- db/query/books.sql — SQL zuerst, Annotationen steuern die Generierung
      
      -- name: GetBookByISBN :one
      SELECT isbn, title, author, price_cents, stock FROM books WHERE isbn = $1;
      
      -- name: ListBooks :many
      SELECT isbn, title, author, price_cents, stock FROM books ORDER BY title LIMIT $1;
      
      -- name: DecrementStock :exec
      UPDATE books SET stock = stock - 1 WHERE isbn = $1 AND stock > 0;
      
      // db/sqlc/books.sql.go — von `sqlc generate` erzeugt, nie handgeschrieben
      func (q *Queries) GetBookByISBN(ctx context.Context, isbn string) (Book, error) {
      	row := q.db.QueryRow(ctx,
      		`SELECT isbn, title, author, price_cents, stock FROM books WHERE isbn = $1`, isbn)
      	var i Book
      	err := row.Scan(&i.Isbn, &i.Title, &i.Author, &i.PriceCents, &i.Stock)
      	return i, err
      }
      
      // internal/catalog/service.go — Aufruf: typsicher, ohne Schnittstellen-Umwandlung
      b, err := q.GetBookByISBN(ctx, "978-3-423-2089-8")
      if errors.Is(err, pgx.ErrNoRows) {
      	return ErrNotFound // das Mapping auf HTTP-Statuscodes folgt in Lektion 60
      }
      
      // Terminal: go build ./...
      // → (kompiliert — SQL und Go-Typen passen zusammen, garantiert vom Generator)
      

      Zum Vergleich GORM — weniger SQL, mehr Verhandlung mit der Abstraktion:

      // internal/catalog/gorm_repo.go — dasselbe Ergebnis mit GORM
      db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
      if err != nil {
      	log.Fatal(err)
      }
      if err := db.AutoMigrate(&Book{}); err != nil { // Schema aus dem Struct
      	log.Fatal(err)
      }
      
      var b Book
      err = db.Where("isbn = ?", "978-3-423-2089-8").First(&b).Error
      // First liefert bei leerem Ergebnis gorm.ErrRecordNotFound —
      // Find liefert stattdessen einen leeren Slice mit nil-Fehler. Nie mischen!
      
      // Terminal: go test ./internal/catalog/
      // → ok  	bookstore/internal/catalog	0.412s
      

      Und sqlx als dünnste Zwischenstufe — Structs ohne Generator, geprüft erst zur Laufzeit:

      // sqlx: database/sql mit StructScan — pragmatisch, aber untypisiert bis zur Laufzeit
      rows, err := dbx.QueryxContext(ctx,
      	`SELECT isbn, title, price_cents FROM books WHERE stock > $1 ORDER BY title`, 0)
      if err != nil {
      	return nil, err
      }
      defer rows.Close()
      
      var found []Book
      for rows.Next() {
      	var b Book
      	if err := rows.StructScan(&b); err != nil {
      		return nil, err
      	}
      	found = append(found, b)
      }
      
      // → 2 Bücher mit Lagerbestand gescannt — ein Spalten-Tippfehler fiele hier erst zur Laufzeit auf
      
      WerkzeugAnsatzStärkePreis
      pgx/v5Treiber + PoolGeschwindigkeit, volle SQL-Kontrollejede Abfrage von Hand
      sqlxReflexion über database/sqlStructScan, NamedExeckeine Prüfung zur Compile-Zeit
      sqlcCodegenerierung aus SQLtypsicher beim GenerierenSQL zuerst denken, CLI im Build
      GORMORMAssoziationen, AutoMigrate, HooksAbstraktion leckt bei komplexen Joins

      Für die Buchhandlung: Das Team kann SQL, die Abfragen sind überwiegend klar strukturiert, und der Bestand ist kritisch (doppelte Verkäufe sind teurer als eine Minute mehr Implementierung). Die Wahl fällt auf sqlc mit pgx — GORM bliebe die Antwort, wenn Rapid-Prototyping und viele CRUD-Tabellen dominierten. In Lektion 60 zahlt diese Entscheidung Dividende, wenn die API wirklich gebaut wird.

      ⚠ Häufiger Fehler: Auf db.Find(&books, ...) ein errors.Is(err, gorm.ErrRecordNotFound) setzen und sich wundern, warum die Fehlerbehandlung nie greift. Find liefert bei leerem Ergebnis KEINEN Fehler, sondern einen leeren Slice — ErrRecordNotFound gibt es nur bei First/Take/Last. Wer »nicht gefunden« über Find erkennen will, muss len(books) == 0 prüfen; die Fehler-Prüfung suggeriert Sicherheit, die nie eintritt.

      ✅ Wichtige Erkenntnisse

      Haken setzen, um deinen Lernfortschritt zu markieren:

        59

        CLI & Config: Cobra, Viper & Environment-Layering

        Lektion 59 von 100

        Ein Binary namens bookstore — serve, migrate, seed

        In Produktion deployt die Buchhandlung genau ein Binary, das drei Gesichter haben muss: bookstore serve startet die API, bookstore migrate spielt Schema-Migrationen ein (dazu später github.com/golang-migrate/migrate/v4), bookstore seed füllt den Laden mit Testdaten. In Modul 10 (Lektion 50) hast du Subcommands mit flag.NewFlagSet gebaut — bei drei Befehlen und wachsender Flag-Liste wird das Tippen mühsam: Hilfe-Texte von Hand, keine Vervollständigung, keine knappe Konfigurations-Logik. Genau hier setzen Cobra (github.com/spf13/cobra) und Viper (github.com/spf13/viper) an — das etablierte Duo für Go-CLIs, von kubectl bis hugo.

        Cobra liefert die Struktur: jedes Kommando ist ein Wert vom Typ *cobra.Command mit Use, Short und RunE — daraus entstehen automatisch --help, Usage-Fehler und Shell-Completion. Und weil RunE einen Fehler zurückgibt, bleibt die Hauptfunktion sauber: ein Execute, ein Exit-Code.

        // cmd/bookstore/main.go — Cobra: Root-Command plus Subcommands
        package main
        
        import (
        	"fmt"
        	"os"
        
        	"github.com/spf13/cobra"
        )
        
        func main() {
        	root := &cobra.Command{
        		Use:   "bookstore",
        		Short: "Die Bookstore-API verwalten",
        	}
        
        	serve := &cobra.Command{
        		Use:   "serve",
        		Short: "HTTP-API starten",
        		RunE:  runServe, // verdrahtet in Lektion 60
        	}
        	serve.Flags().String("addr", ":8080", "Listen-Adresse")
        
        	migrate := &cobra.Command{
        		Use:   "migrate",
        		Short: "Schema-Migrationen ausführen",
        		RunE:  runMigrate,
        	}
        
        	root.AddCommand(serve, migrate)
        	if err := root.Execute(); err != nil {
        		fmt.Fprintln(os.Stderr, "Fehler:", err)
        		os.Exit(1)
        	}
        }
        
        // Terminal: bookstore serve --help
        // → HTTP-API starten
        // →
        // → Usage:
        // →   bookstore serve [flags]
        // →
        // → Flags:
        // →   -h, --help          help for serve
        // →       --addr string   Listen-Adresse (default ":8080")
        //
        // Terminal: bookstore stock
        // → Error: unknown command "stock" for "bookstore"
        // → Run 'bookstore --help' for usage.
        

        Die Konfiguration dazu kommt aus vier Quellen, und die Reihenfolge ist der heimliche Star: Default schlägt nichts, Datei schlägt Default, Env schlägt Datei, Flag schlägt alles. Dieselbe Rangfolge wie in Modul 10 von Hand gebaut — jetzt maschinell und konsistent. Viper nennt das Layering; BindPFlag verdrahtet Cobra-Flags so, dass ein Flag nur gewinnt, wenn es explizit gesetzt wurde.

        // internal/config/config.go — Layering: Default unter Datei unter Env unter Flag
        package config
        
        import (
        	"github.com/spf13/viper"
        )
        
        type Config struct {
        	Addr     string `mapstructure:"addr"`     // Achtung: mapstructure, nicht json
        	DbURL    string `mapstructure:"db_url"`
        	LogLevel string `mapstructure:"log_level"`
        }
        
        func Load() (Config, error) {
        	v := viper.New()
        
        	// 1. Defaults — registrieren zugleich, welche Schlüssel existieren
        	v.SetDefault("addr", ":8080")
        	v.SetDefault("db_url", "postgres://localhost:5432/bookstore")
        	v.SetDefault("log_level", "info")
        
        	// 2. Konfigurationsdatei (optional), z. B. ./bookstore.yaml
        	v.SetConfigName("bookstore")
        	v.SetConfigType("yaml")
        	v.AddConfigPath(".")
        	if err := v.ReadInConfig(); err != nil {
        		if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
        			return Config{}, err // Datei da, aber unlesbar: das ist ein harter Fehler
        		}
        	}
        
        	// 3. Umgebungsvariablen: BOOKSTORE_ADDR, BOOKSTORE_DB_URL, ...
        	v.SetEnvPrefix("bookstore")
        	v.AutomaticEnv()
        
        	// 4. Flags hängt main per v.BindPFlag("addr", serve.Flags().Lookup("addr")) an
        
        	var cfg Config
        	if err := v.Unmarshal(&cfg); err != nil {
        		return Config{}, err
        	}
        	return cfg, nil
        }
        
        // Terminal: bookstore serve
        // → lausche auf :8080                     (Default gewinnt, nichts gesetzt)
        //
        // Terminal: BOOKSTORE_ADDR=:9443 bookstore serve
        // → lausche auf :9443                     (Env schlägt Default)
        //
        // Terminal: BOOKSTORE_ADDR=:9443 bookstore serve --addr :7070
        // → lausche auf :7070                     (Flag schlägt Env)
        

        Beachte das mapstructure-Tag: Unmarshal läuft über github.com/mitchellh/mapstructure — json-Tags werden ignoriert. Wer beide Tag-Familien verwechselt, erhält ein Struct voller Nullwerte ohne jede Fehlermeldung.

        ⚠ Häufiger Fehler: AutomaticEnv() aktivieren, KEINE Defaults setzen und dann Unmarshal(&cfg) erwarten. Unmarshal iteriert nur über Schlüssel, die Viper kennt — existiert log_level nur als Umgebungsvariable BOOKSTORE_LOG_LEVEL, taucht der Schlüssel im Struct schlicht nicht auf und bleibt leer. Ohne Fehlermeldung, ohne Logzeile. Gegenmittel: jeden Schlüssel per SetDefault registrieren (wie oben) oder explizit BindEnv aufrufen — dann findet Unmarshal ihn garantiert.

        ✅ Wichtige Erkenntnisse

        Haken setzen, um deinen Lernfortschritt zu markieren:

          60

          Praxis: Bookstore-API mit Gin + sqlc

          Lektion 60 von 100

          Alles zusammenbauen — der Shop geht live

          Nun fällt die Buchhandlung aus dem Prototyp-Modus: Gin für die Ränder (Lektion 56), die Middleware-Kette für Auth und Logging (Lektion 57), sqlc auf pgx für die Daten (Lektion 58), Cobra und Viper für Start und Konfiguration (Lektion 59). Die Bausteine liegen bereit — jetzt gilt es, sie so zu verdrahten, dass jedes Teil einzeln austauschbar bleibt. Das Projekt wächst auf dieses Gerüst:

          bookstore/
          ├── cmd/bookstore/main.go      // Cobra: serve, migrate, seed
          ├── db/
          │   ├── migrations/            // SQL-Schema für golang-migrate UND sqlc
          │   ├── query/books.sql        // sqlc-Queries (Handarbeit)
          │   └── sqlc/                  // generiert: books.sql.go, models.go
          ├── internal/
          │   ├── api/                   // Gin-Router, Middleware, Handler
          │   ├── catalog/               // Domänenlogik: Bücher, Preise, Bestand
          │   └── config/                // Viper-Layering
          └── sqlc.yaml
          

          Die sqlc-Konfiguration bindet Queries, Schema und Generator zusammen — sql_package: pgx/v5 erzeugt Code direkt für den pgx-Pool:

          # sqlc.yaml
          version: "2"
          sql:
            - engine: "postgresql"
              queries: "db/query"
              schema: "db/migrations"
              gen:
                go:
                  package: "sqlc"
                  out: "db/sqlc"
                  sql_package: "pgx/v5"
          

          Im Handler passiert die entscheidende Übersetzung: Domänen-Fehler werden zu HTTP-Statuscodes — und Datenbank-Fehler werden zu Domänen-Fehlern. Ein pgx.ErrNoRows ist ein 404, keine Schande; eine Unique-Verletzung (pgconn.PgError mit Code 23505) ist ein 409, kein interner Brand:

          // internal/api/books.go — Fehler-Mapping an der API-Grenze
          package api
          
          import (
          	"errors"
          	"net/http"
          
          	"github.com/gin-gonic/gin"
          	"github.com/jackc/pgx/v5"
          	"github.com/jackc/pgx/v5/pgconn"
          
          	"bookstore/db/sqlc"
          )
          
          func (s *Server) handleGetBook(c *gin.Context) {
          	b, err := s.queries.GetBookByISBN(c.Request.Context(), c.Param("isbn"))
          	switch {
          	case errors.Is(err, pgx.ErrNoRows):
          		c.JSON(http.StatusNotFound, gin.H{"error": "Buch nicht gefunden"})
          	case err != nil:
          		s.logger.Error("db", "err", err) // details nur ins Server-Log
          		c.JSON(http.StatusInternalServerError, gin.H{"error": "interner Fehler"})
          	default:
          		c.JSON(http.StatusOK, b)
          	}
          }
          
          func (s *Server) handleCreateBook(c *gin.Context) {
          	var req struct {
          		ISBN  string `json:"isbn" binding:"required"`
          		Title string `json:"title" binding:"required"`
          	}
          	if err := c.ShouldBindJSON(&req); err != nil {
          		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
          		return
          	}
          
          	err := s.queries.CreateBook(c.Request.Context(), sqlc.CreateBookParams{
          		Isbn: req.ISBN, Title: req.Title})
          	var pgErr *pgconn.PgError
          	switch {
          	case errors.As(err, &pgErr) && pgErr.Code == "23505":
          		c.JSON(http.StatusConflict, gin.H{"error": "ISBN existiert bereits"})
          	case err != nil:
          		s.logger.Error("db", "err", err)
          		c.JSON(http.StatusInternalServerError, gin.H{"error": "interner Fehler"})
          	default:
          		c.JSON(http.StatusCreated, gin.H{"isbn": req.ISBN})
          	}
          }
          
          // Terminal: curl -s localhost:8080/api/v1/books/978-3-423-2089-8
          // → {"isbn":"978-3-423-2089-8","title":"Der Alchimist","author":"Paulo Coelho","price_cents":1295,"stock":3}
          //
          // Terminal: curl -s -o /dev/null -w "%{http_code}" localhost:8080/api/v1/books/000-0-000-00000-0
          // → 404
          

          Und das serve-Kommando, das alles verdrahtet — Pool einmal, Queries einmal, Kette einmal, Server mit den Pflicht-Timeouts aus Modul 10:

          // cmd/bookstore/main.go — serve: Pool, Queries, Router, Server
          func runServe(cmd *cobra.Command, args []string) error {
          	cfg, err := config.Load()
          	if err != nil {
          		return err
          	}
          
          	// Pool EINMAL pro Prozess — handler teilen ihn über den Server
          	pool, err := pgxpool.New(cmd.Context(), cfg.DbURL)
          	if err != nil {
          		return err
          	}
          	defer pool.Close()
          
          	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
          	srv := api.New(sqlc.New(pool), logger) // Router + Middleware aus Lektion 57
          
          	httpSrv := &http.Server{
          		Addr:              cfg.Addr,
          		Handler:           srv,
          		ReadHeaderTimeout: 5 * time.Second, // Slowloris-Schutz, Lektion 49
          		WriteTimeout:      15 * time.Second,
          	}
          	logger.Info("lausche auf " + cfg.Addr)
          	// Graceful Shutdown exakt wie in Modul 10, Lektion 49
          	return httpSrv.ListenAndServe()
          }
          
          // Terminal: die fertige API im Härtetest
          // → $ bookstore serve
          // → {"time":"2026-11-05T22:02:11+01:00","level":"INFO","msg":"lausche auf :8080"}
          //
          // → $ curl -s -i -X POST localhost:8080/api/v1/books -d '{"isbn":"978-3-423-2089-8","title":"Duplikat"}'
          // → HTTP/1.1 409 Conflict
          // → {"error":"ISBN existiert bereits"}
          //
          // → $ curl -s localhost:8080/api/v1/books/978-3-423-2089-8
          // → {"isbn":"978-3-423-2089-8","title":"Der Alchimist","author":"Paulo Coelho","price_cents":1295,"stock":3}
          

          Damit ist der Laden live: Router, Middleware, Datenzugriff, CLI und Konfiguration aus einem Guss — und jedes Einzelteil bleibt ersetzbar, weil die Domäne (internal/catalog) von keinem der Frameworks weiß. Ob die API das auch unter Last und mit echten Nutzern hält, ist die Frage von Modul 13: Testing & Observability, von github.com/stretchr/testify bis zu OpenTelemetry-Traces.

          ⚠ Häufiger Fehler: pgxpool.New(...) im Handler aufrufen — ein frischer Pool pro Request. Jeder Pool öffnet eigene Verbindungen und hält sie offen; unter Last reißt das die max_connections von PostgreSQL in Sekunden, und jeder weitere Request stirbt am Db-Fehler, obwohl die Datenbank selbst kerngesund ist. Der Pool ist ein Singleton pro Prozess: in runServe öffnen, über den Server-Struct an die Handler reichen, einmal per defer schließen.

          ✅ Wichtige Erkenntnisse

          Haken setzen, um deinen Lernfortschritt zu markieren:

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