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.
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:
| Router | Paket | Basis | Middleware-Typ |
|---|---|---|---|
net/http | Standardbibliothek | net/http | func(http.Handler) http.Handler |
| chi | github.com/go-chi/chi/v5 | net/http | identisch zur Standardbibliothek |
| Gin | github.com/gin-gonic/gin | eigenes Routing | func(*gin.Context) |
| Echo | github.com/labstack/echo/v4 | eigener Handler-Vertrag | echo.MiddlewareFunc |
| Fiber | github.com/gofiber/fiber/v2 | fasthttp | func(*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/httpnach Gin portieren und sich über die Panic beim Start wundern. DerServeMuxlöstGET /books/newnebenGET /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 wieconflicts 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:
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 — ohnereturn. 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 loggtsuperfluous response.WriteHeader. Nach jedem Abort gehört einreturn— die Middleware oben führt das explizit vor.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
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
| Werkzeug | Ansatz | Stärke | Preis |
|---|---|---|---|
pgx/v5 | Treiber + Pool | Geschwindigkeit, volle SQL-Kontrolle | jede Abfrage von Hand |
sqlx | Reflexion über database/sql | StructScan, NamedExec | keine Prüfung zur Compile-Zeit |
sqlc | Codegenerierung aus SQL | typsicher beim Generieren | SQL zuerst denken, CLI im Build |
| GORM | ORM | Assoziationen, AutoMigrate, Hooks | Abstraktion 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, ...)einerrors.Is(err, gorm.ErrRecordNotFound)setzen und sich wundern, warum die Fehlerbehandlung nie greift.Findliefert bei leerem Ergebnis KEINEN Fehler, sondern einen leeren Slice —ErrRecordNotFoundgibt es nur beiFirst/Take/Last. Wer »nicht gefunden« überFinderkennen will, musslen(books) == 0prüfen; die Fehler-Prüfung suggeriert Sicherheit, die nie eintritt.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
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 dannUnmarshal(&cfg)erwarten. Unmarshal iteriert nur über Schlüssel, die Viper kennt — existiertlog_levelnur als UmgebungsvariableBOOKSTORE_LOG_LEVEL, taucht der Schlüssel im Struct schlicht nicht auf und bleibt leer. Ohne Fehlermeldung, ohne Logzeile. Gegenmittel: jeden Schlüssel perSetDefaultregistrieren (wie oben) oder explizitBindEnvaufrufen — dann findet Unmarshal ihn garantiert.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
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 diemax_connectionsvon PostgreSQL in Sekunden, und jeder weitere Request stirbt am Db-Fehler, obwohl die Datenbank selbst kerngesund ist. Der Pool ist ein Singleton pro Prozess: inrunServeöffnen, über den Server-Struct an die Handler reichen, einmal perdeferschließen.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: