Modul 15: Capstone: Produktionsreife Services
Das Capstone: Aus der Bookstore-API wird ein produktionsreifer Service. Architektur-Entscheidungen mit ADRs und Schichtenplan, ein Service-Skelett aus hexagonaler Architektur mit Gin, sqlc und Postgres, Observability mit slog, Prometheus und OpenTelemetry, Robustheit durch Timeouts, Circuit-Breaker und Rate-Limits — und am Ende das Deployment mit Docker, Version-Embedding und einer Release-Checkliste.
Architektur-Entscheidungen: ADR & Schichtenplan
Lektion 71 von 100
Vom Prototyp zum System, das jemand anderes weiterbaut
Die Bookstore-API aus Modul 12 läuft — auf dem Laptop von Lena. Jetzt will »Kant & Kurve« richtig gehen live: drei Entwickler, ein Betriebsteam, Releases alle zwei Wochen. Genau in dieser Phase sterben Projekte nicht an fehlenden Features, sondern an Entscheidungen, die jemand vor Monaten getroffen hat und die niemand mehr begründen kann. Warum Gin und nicht chi? Warum sqlc und nicht GORM? Wer das nur im Kopf oder im Slack-Verlauf findet, verliert Wochen.
Das Werkzeug dafür ist schlicht: ADRs (Architecture Decision Records) — nummerierte Markdown-Dateien im Repo, jede genau eine Seite, mit Kontext, Entscheidung und Konsequenzen. Und der zweite Teil der Lektion: ein Schichtenplan, der sagt, welches Go-Paket wen importieren darf. Beides zusammen ist der Unterschied zwischen »hexagonal klingt gut« und hexagonal, das auch in zwei Jahren noch stimmt — die Architektur-Stile im Detail behandelt Modul 3 des Architektur-Kurses.
Eine ADR ist ein Vertrag mit dem zukünftigen Ich
ADRs sind bewusst langweilig: kurzer Kontext (welches Problem drängte?), eine klare Entscheidung im Indikativ (»Wir nehmen Gin für die API-Schicht«) und die ehrlichen Konsequenzen inklusive Nachteilen. ADRs werden nie geändert, nur ergänzt: hältst du eine Entscheidung für falsch, schreibst du eine neue ADR, die die alte superseded. So bleibt die Entscheidungsgeschichte lesbar — wie git log für Architektur.
Erst der Schichtenplan — ein Standard-Layout für Go-Services, das du in fast dieser Form überall wiedererkennen wirst:
bookstore/
├── cmd/bookstore/main.go # Kompositionswurzel: hier wird verdrahtet, nirgends sonst
├── internal/
│ ├── catalog/ # Domäne: Entities, Ports (Interfaces) — importiert KEIN Framework
│ ├── api/ # Adapter: Gin-Handler, Middleware, JSON
│ ├── store/ # Adapter: sqlc-generierte Queries, pgx-Pool
│ └── obs/ # Logging, Metriken, Tracing (Lektion 73)
└── docs/adr/ # 0001-adr-prozess.md, 0007-router-ist-gin.md, …
Und eine ADR aus dem echten Projektalltag der Buchhandlung — Nummer 7, weil die ersten sechs Entscheidungen (Postgres, Go, CI, Migrationen mit github.com/golang-migrate/migrate/v4, Deployment, Monitoring) schon getroffen waren:
# ADR 0007: Gin als HTTP-Router für die API-Schicht
## Kontext
Rund dreißig Routen, Admin-Gruppe mit Auth, JSON-Bindung. net/http kann
Methoden-Patterns und Wildcards seit Go 1.22 selbst (Lektion 46) — der
reine Routen-Match ist kein Argument für ein Framework.
## Entscheidung
Wir nutzen github.com/gin-gonic/gin für die API-Schicht. Die Domäne
(internal/catalog) bleibt routerfrei.
## Konsequenzen
+ Bindung, Validierungs-Middleware und Gruppen sparen bei 30 Routen Zeit.
+ Das größte Middleware-Ökosystem der Kandidaten.
− Eigene Handler-Signatur (*gin.Context): ein späterer Router-Wechsel
berührt jede Handler-Zeile — akzeptiert, weil unwahrscheinlich.
Der Plan gilt aber nur, wenn er nicht weggebetet werden kann. In Go gibt es keinen Classpath-Zauber — aber es gibt einen Trick, den viele Teams nicht kennen: die Abhängigkeitsregel als Test. Ein normaler go test, der per go list die Imports eines Packages prüft und rot wird, sobald die Domäne doch ein Framework importiert:
// internal/arch/arch_test.go — die Schichtenregel als ausführbarer Test
package arch
import (
"os/exec"
"strings"
"testing"
)
func TestCatalogImportsKeinFramework(t *testing.T) {
out, err := exec.Command("go", "list",
"-deps", "bookstore/internal/catalog").CombinedOutput()
if err != nil {
t.Fatal(err)
}
for _, imp := range strings.Fields(string(out)) {
switch {
case strings.HasPrefix(imp, "github.com/gin-gonic/gin"),
strings.HasPrefix(imp, "github.com/jackc/pgx"),
strings.HasPrefix(imp, "github.com/spf13/cobra"):
t.Errorf("Domäne importiert Infrastruktur: %s", imp)
}
}
}
// Terminal: go test ./internal/arch/
// → ok bookstore/internal/arch 0.412s
//
// Terminal: nach einem "schnellen Fix", der gin.Context in die Domäne holt
// → --- FAIL: TestCatalogImportsKeinFramework
// → arch_test.go:20: Domäne importiert Infrastruktur: github.com/gin-gonic/gin
Und die andere Richtung der Regel — die Domäne definiert ihre Ports selbst, als ganz normale Go-Interfaces. Das ist der Kern der hexagonalen Idee in Go: kein implements, keine Fabriken, nur die Tatsache, dass Implementierungen Interfaces implizit erfüllen:
// internal/catalog/ports.go — die Domäne beschreibt das WAS, der Adapter liefert das WIE
package catalog
import "context"
type Book struct {
ISBN, Title, Author string
PriceCents int64
}
// Repository ist ein Port: benannt aus Sicht der Domäne, nicht der Datenbank.
type Repository interface {
ByISBN(ctx context.Context, isbn string) (Book, error)
Store(ctx context.Context, b Book) error
}
// Terminal: go build ./internal/catalog
// → (keine Ausgabe — die Domäne kompiliert ohne ein einziges Framework)
⚠ Häufiger Fehler: Die Schichtenregel lebt nur in einem Wiki — oder als Kommentar über der Paketstruktur. Drei Monate später steht der erste »schnelle Fix« mit
*gin.Contextin der Domäne, und niemand merkt es, weil alles weiter kompiliert. Ein Regel, die kein CI erzwingt, ist keine Regel, sondern ein Wunsch. Dergo list-Test oben kostet zwanzig Zeilen und läuft mit jedemgo test ./...— es gibt keinen Grund, ihn wegzulassen.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Service-Skelett: Hexagonal + Gin + sqlc + Postgres
Lektion 72 von 100
Das Skelett, an dem alles andere wächst
Der Plan steht (Lektion 71), jetzt wird er Beton: ein Service-Skelett, das vom ersten Tag an alle Eigenschaften eines Produktionssystems hat — auch wenn die Domäne noch klein ist. Hexagonal bedeutet dabei keine Ordner-Religion, sondern eine einzige Aussage: Der Kern kennt nur seine Ports, und alles Technische ist ein Adapter, den man austauschen kann, ohne den Kern anzufassen. Das zahlt sich sofort aus: der Service-Test in Modul 13 lief gegen eine In-Memory-Implementierung, ohne dass ein Docker-Container laufen musste.
Die Reihenfolge beim Aufbau ist wichtig: erst Domäne und Ports, dann die Adapter, ganz am Schluss main. Wer mit main.go und dem Router anfängt, zieht Framework-Typen durch alles, was danach kommt.
Der Kern — reines Go, testbar in Nanosekunden:
// internal/catalog/service.go — die Domäne: kein gin, kein pgx, nur Logik
package catalog
import (
"context"
"fmt"
)
type Service struct {
repo Repository // Port aus ports.go — wer auch immer ihn füllt
}
func NewService(repo Repository) *Service { return &Service{repo: repo} }
var ErrNotFound = fmt.Errorf("catalog: Buch nicht gefunden")
func (s *Service) Book(ctx context.Context, isbn string) (Book, error) {
b, err := s.repo.ByISBN(ctx, isbn)
if err != nil {
return Book{}, fmt.Errorf("isbn %s: %w", isbn, err)
}
return b, nil
}
// Terminal: go test ./internal/catalog -run TestBook
// → ok bookstore/internal/catalog 0.003s (0,003 s — kein Netz, keine DB)
Der HTTP-Adapter — Gin am Rand, dünne Handler, Fehler-Mapping an genau einer Stelle. Welche Statuscodes zu welchen Fehlern gehören, ist eine API-Design-Entscheidung, keine Go-Entscheidung; Modul 5 des Architektur-Kurses hat die Tabelle dafür geliefert:
// internal/api/books.go — der Adapter: parsen, Domäne aufrufen, antworten
package api
import (
"errors"
"net/http"
"github.com/gin-gonic/gin"
"bookstore/internal/catalog"
)
func Book(svc *catalog.Service) gin.HandlerFunc {
return func(c *gin.Context) {
b, err := svc.Book(c.Request.Context(), c.Param("isbn"))
switch {
case err == nil:
c.JSON(http.StatusOK, b)
case errors.Is(err, catalog.ErrNotFound):
c.JSON(http.StatusNotFound, gin.H{"error": "Buch nicht gefunden"})
default:
c.JSON(http.StatusInternalServerError, gin.H{"error": "interner Fehler"})
// Details nur ins Log (Lektion 73) — nie in die Antwort
}
}
}
// Terminal: curl -s -i localhost:8080/api/v1/books/000-0-0000-0000-0
// → HTTP/1.1 404 Not Found
// → {"error":"Buch nicht gefunden"}
Der Speicher-Adapter — sqlc generiert die Typen, der Adapter implementiert nur den Port. Die Queries liegen in internal/store/queries/books.sql (Lektion 58), die sqlc.yaml sagt sql_package: "pgx/v5":
// internal/store/catalog.go — sqlc-Ausgabe hinter dem Port verstecken
package store
import (
"context"
"errors"
"github.com/jackc/pgx/v5"
"bookstore/internal/catalog"
)
type Repository struct{ q *Queries } // Queries: von sqlc generiert
func NewRepository(q *Queries) *Repository { return &Repository{q: q} }
func (r *Repository) ByISBN(ctx context.Context, isbn string) (catalog.Book, error) {
row, err := r.q.GetBookByISBN(ctx, isbn)
switch {
case errors.Is(err, pgx.ErrNoRows):
return catalog.Book{}, catalog.ErrNotFound // Adapter übersetzt, Domäne bleibt DB-frei
case err != nil:
return catalog.Book{}, err
}
return catalog.Book{ISBN: row.Isbn, Title: row.Title,
Author: row.Author, PriceCents: row.PriceCents}, nil
}
// Terminal: go vet ./...
// → (keine Ausgabe — sauber)
Und die Kompositionswurzel — die einzige Datei, die alle Schichten sieht. Migrationen laufen mit github.com/golang-migrate/migrate/v4 hoch, bevor der erste Request ankommt:
// cmd/bookstore/main.go — verdrahten, nicht denken
package main
import (
"context"
"log/slog"
"net/http"
"os"
"time"
"github.com/gin-gonic/gin"
"github.com/jackc/pgx/v5/pgxpool"
"bookstore/internal/api"
"bookstore/internal/catalog"
"bookstore/internal/store"
)
func main() {
ctx := context.Background()
pool, err := pgxpool.New(ctx, os.Getenv("DATABASE_URL"))
if err != nil {
slog.Error("pool", "err", err)
os.Exit(1)
}
defer pool.Close() // Pool EINMAL pro Prozess — Lektion 60
if err := migrateDB(ctx, os.Getenv("DATABASE_URL")); err != nil { // golang-migrate/v4, Dateien in db/migrations
slog.Error("migration", "err", err)
os.Exit(1)
}
svc := catalog.NewService(store.NewRepository(pool)) // Ports treffen Adapter — genau hier
r := gin.Default()
r.GET("/api/v1/books/:isbn", api.Book(svc))
srv := &http.Server{
Addr: ":8080",
Handler: r,
ReadHeaderTimeout: 5 * time.Second, // Slowloris-Schutz, Lektion 49
WriteTimeout: 15 * time.Second,
}
slog.Info("lausche auf :8080")
if err := srv.ListenAndServe(); err != nil {
slog.Error("server", "err", err)
}
}
// Terminal: DATABASE_URL=postgres://book@localhost/kurve go run ./cmd/bookstore
// → {"time":"2026-11-05T20:11:48+01:00","level":"INFO","msg":"lausche auf :8080"}
Dünne Handler sind keine Geschmacksfrage
Ein Handler hat genau drei Jobs: Anfrage parsen, Domäne aufrufen, Antwort schreiben. Alles, was mehr ist — Geschäftsregeln, SQL, Branchenlogik — wandert in den Kern und wird damit testbar ohne HTTP, Router und Netzwerk. Der Lackmustest: Könnte die Domäne als CLI-Programm laufen, ohne dass eine Zeile in internal/catalog sich ändert? Wenn ja, ist das Skelett hexagonal. Wenn nein, ist der Handler zu dick.
⚠ Häufiger Fehler: Der erste Handler bekommt
*gin.Contextals Parameter in die Service-Methode — »spart das doppelte Context-Gereimse«. Ab diesem Moment ist die Domäne an Gin gekoppelt: Tests brauchen einen Gin-Engine-Stub, und weil der Context nach dem Request ungültig wird, entstehen memleak-artige Bugs, wenn die Domäne ihn in einer Goroutine weiterverwendet. Der einzige Context, der die Domäne betritt, istcontext.Context— im Handler ist dasc.Request.Context(), odercontext.Background()in Tests und CLIs.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Observability eingebaut: Logs, Metriken, Traces
Lektion 73 von 100
Freitag, 16:12 Uhr — und niemand weiß, wo die Zeit bleibt
Das Szenario, das jede/r kennt: Die Latenz der Buchhandlung schießt hoch, die Ticket-Queue füllt sich, und im Chat stehen drei Hypothesen und null Daten. Ist es die Datenbank? Der Empfehlungsdienst aus Modul 14? Die Pod auf dem falschen Knoten? Ohne Observability raten sieben Leute; mit ihr liest eine Person drei Kurven und weiß es. Die drei Werkzeuge decken unterschiedliche Fragen ab: Logs beantworten »was ist genau passiert?«, Metriken beantworten »wie viele und wie schnell?«, Traces beantworten »wo ging die Zeit hin?«.
Für alle drei gilt: nicht nachträglich drangebaut, sondern von Anfang an eingebaute Middleware. Und die kopierte Arbeit ist klein, weil Go mit log/slog (seit Go 1.21 in der Standardbibliothek) strukturiertes Logging mitbringt und Prometheus und OpenTelemetry fertige Bibliotheken haben.
Die Trace-ID ist das Scharnier zwischen den drei Welten
Logs, Metriken und Traces getrennt zu betreiben ist halbfertig. Der Trick ist Korrelation: Jeder Request bekommt eine Trace-ID, jeder Log-Eintrag trägt sie mit, jeder Span gehört zu ihr. Dann springst du von der Prometheus-Kurve (»P99 auf 800 ms hochgesprungen um 16:12«) in einen Trace dieser Minute (»800 ms im pg-Span«) und von dort in das Log mit derselben trace_id (»Lock-Timeout auf books«). Drei Systeme, ein Faden.
Stufe eins: strukturierte Logs mit slog — plus die Brücke zu OpenTelemetry, die automatisch Trace- und Span-ID in jeden Eintrag schreibt, wenn ein Span aktiv ist:
// internal/obs/logging.go — slog-JSON plus Trace-Korrelation, einmal gebaut, überall genutzt
package obs
import (
"context"
"log/slog"
"os"
"go.opentelemetry.io/otel/trace"
)
// TraceHandler verpackt einen beliebigen slog.Handler und ergänzt Trace-/Span-ID.
type TraceHandler struct{ slog.Handler }
func (h TraceHandler) Handle(ctx context.Context, r slog.Record) error {
if sc := trace.SpanContextFromContext(ctx); sc.IsValid() {
r.AddAttrs(slog.String("trace_id", sc.TraceID().String()),
slog.String("span_id", sc.SpanID().String()))
}
return h.Handler.Handle(ctx, r)
}
func NewLogger() *slog.Logger {
return slog.New(TraceHandler{slog.NewJSONHandler(os.Stdout, nil)})
}
// Terminal: curl -s localhost:8080/api/v1/books/978-3-423-2089-8
// → {"time":"2026-11-05T21:14:02+01:00","level":"INFO","msg":"Buch ausgeliefert","isbn":"978-3-423-2089-8","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7"}
Stufe zwei: Metriken. Für einen HTTP-Service reicht das RED-Set — Rate, Errors, Duration — als Histogramm mit den zwei entscheidenden Labels: Route und Statuscode. github.com/prometheus/client_golang liefert alles, promhttp.Handler() exposiert /metrics:
// internal/obs/metrics.go — RED-Metriken als Gin-Middleware
package obs
import (
"strconv"
"time"
"github.com/gin-gonic/gin"
"github.com/prometheus/client_golang/prometheus"
)
var httpDur = prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "Dauer der HTTP-Requests nach Route und Statuscode.",
Buckets: []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5},
}, []string{"route", "code"})
func init() { prometheus.MustRegister(httpDur) }
// Metrics nutzt c.FullPath() — die ROUTE, nicht den konkreten Pfad (siehe Fehler unten).
func Metrics() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next()
httpDur.WithLabelValues(c.FullPath(), strconv.Itoa(c.Writer.Status())).
Observe(time.Since(start).Seconds())
}
}
// Terminal: curl -s localhost:8080/metrics | grep http_request_duration_seconds_bucket
// → http_request_duration_seconds_bucket{code="200",route="/api/v1/books/:isbn",le="0.01"} 14
Stufe drei: Traces mit OpenTelemetry. Provider einmal in main bauen, Exporter per OTLP/HTTP schicken, und beim Shutdown das Batch-Flush abwarten — sonst verliert jeder Deploy die letzten Spans:
// cmd/bookstore/otel.go — OpenTelemetry: Provider, Exporter, sauberes Shutdown
package main
import (
"context"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
"go.opentelemetry.io/otel/sdk/resource"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)
func newTracerProvider(ctx context.Context, otlpURL string) (*sdktrace.TracerProvider, error) {
exp, err := otlptracehttp.New(ctx, otlptracehttp.WithEndpointURL(otlpURL))
if err != nil {
return nil, err
}
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp), // sammelt Spans, schickt sie gebündelt
sdktrace.WithResource(resource.NewWithAttributes(
semconv.SchemaURL, semconv.ServiceName("bookstore"))),
)
otel.SetTracerProvider(tp) // Bibliotheks-Instrumentierung hängt sich hier ein
return tp, nil
}
// in runServe: tp holen, defer tp.Shutdown(graceCtx) NACH httpSrv.Shutdown —
// erst keine neuen Requests, dann die letzten Spans flushen.
//
// Terminal: der Request von oben im Trace-View (Jaeger/Tempo)
// → bookstore GET /api/v1/books/:isbn 41 ms
// → bookstore SELECT books WHERE isbn = $1 12 ms (db.system: postgresql)
Der Lastfall von 16:12 sieht damit so aus: die Kurve zeigt P99-Sprung auf 800 ms um 16:12, der Span zeigt 780 ms Wartezeit auf dem Lock, das Log zeigt die Lock-Timeouts mit denselben Trace-IDs. Diagnose fertig, bevor der Kaffee kalt ist — und die Störung war diesmal eine vergessene Migration aus Lektion 72, die in der Release-Checkliste von Lektion 75 jetzt ihren eigenen Haken bekommt.
⚠ Häufiger Fehler: Als Route-Label den konkreten Pfad verwenden —
c.Request.URL.Pathstattc.FullPath(). Prometheus-Labels sind eine Zeitreihe pro Wertekombination:/api/v1/books/978-3-423-2089-8,/api/v1/books/978-3-453-2007-3, zehntausend ISBNs später hat der Server zehntausend Serien für dieselbe Route, der Speicher des Prometheus wächst, und die Abfragen werden unbrauchbar (Kardinalitäts-Explosion).FullPath()liefert das registrierte Muster (/api/v1/books/:isbn) — endlich viele Serien, egal wie viele Bücher der Laden führt.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Robustheit: Timeouts, Circuit-Breaker, Rate-Limits
Lektion 74 von 100
Wenn der Nachbar stirbt, stirbt der Service mit
Der Empfehlungsdienst aus Modul 14 — pgvector-Embeddings, alles gut — antwortet plötzlich nach acht Sekunden statt nach vierzig Millisekunden. Ohne Schutz eskaliert das vorhersagbar: Jeder Buch-Request wartet auf Empfehlungen, die Goroutinen stapeln sich, der pgx-Pool ist von wartenden Requests blockiert, und nach fünf Minuten ist die ganze Buchhandlung down — wegen eines Dienstes, der nur nett-zu-haben war. Ein produktionsreifer Service geht damit um wie ein Stromnetz: jede Leitung hat eine Sicherung. Wie Timeouts, Circuit-Breaker und Bulkheads als Muster wirken, behandelt der Architektur-Kurs in Modul 8: Resilience — hier baust du sie in Go.
Die Sicherungen stapeln sich von außen nach innen, und jede hat eine andere Aufgabe:
| Sicherung | Werkzeug | Aufgabe |
|---|---|---|
| Timeout pro Aufruf | context.WithTimeout | kein Request wartet länger als sein Budget |
| Client-Deckel | http.Client{Timeout: …} | Notreserve für den Fall, dass der Context vergessen wurde |
| Circuit-Breaker | github.com/sony/gobreaker/v2 | nach wiederholten Fehlern gar nicht erst anfragen |
| Rate-Limit | golang.org/x/time/rate | ein Client kann den Service nicht fluten |
| Server-Timeouts | http.Server-Felder | Slowloris und Schreibhänger (Lektion 49) |
Stufe eins: das Budget. Der Aufrufer weiß, wie viel Zeit er dem Dienst geben will — hier 1,5 Sekunden —, und der http.Client bekommt einen harten Deckel obendrauf:
// internal/recommend/client.go — Budgets: erst Context, dann Client-Deckel
package recommend
import (
"context"
"encoding/json"
"fmt"
"net/http"
"time"
)
type Client struct {
svc string
http *http.Client
}
func New(svc string) *Client {
return &Client{svc: svc,
http: &http.Client{Timeout: 2 * time.Second}} // Deckel für ALLE Aufrufe
}
func (c *Client) For(ctx context.Context, userID string) ([]string, error) {
ctx, cancel := context.WithTimeout(ctx, 1500*time.Millisecond) // Budget des Aufrufers
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet,
c.svc+"/v1/recommend?user="+userID, nil)
if err != nil {
return nil, err
}
resp, err := c.http.Do(req)
if err != nil {
return nil, fmt.Errorf("recommend: %w", err) // context.DeadlineExceeded bleibt sichtbar
}
defer resp.Body.Close()
var recs []string
return recs, json.NewDecoder(resp.Body).Decode(&recs)
}
// Terminal: der Dienst braucht heute 8 s — der Request trotzdem nicht
// → 2026/11/05 21:30:00 GET /api/v1/books 200 in 1.501 ms (Timeout, Fallback aktiv)
Stufe zwei: der Circuit-Breaker. github.com/sony/gobreaker/v2 zählt Fehler pro Zustand: nach fünf Fehlern in Folge springt der Circuit auf, und die nächsten Aufrufe scheitern in Mikrosekunden — ohne den toten Dienst auch nur zu tippen. Nach dreißig Sekunden lässt er Probe-Requests durch (Half-Open):
// internal/recommend/breaker.go — gobreaker/v2 mit Fallback statt Fehler
package recommend
import (
"context"
"time"
"github.com/sony/gobreaker/v2"
)
var cb = gobreaker.NewCircuitBreaker[[]string](gobreaker.Settings{
Name: "recommend",
MaxRequests: 3, // Half-Open: genau 3 Probe-Requests erlauben
Timeout: 30 * time.Second, // so lange bleibt der Circuit offen
ReadyToTrip: func(c gobreaker.Counts) bool {
return c.ConsecutiveFailures >= 5 // aufreißen nach 5 Fehlern in Folge
},
})
func SafeFor(c *Client) func(ctx context.Context, uid string) ([]string, error) {
return func(ctx context.Context, uid string) ([]string, error) {
recs, err := cb.Execute(func() ([]string, error) {
return c.For(ctx, uid)
})
if err != nil {
return []string{"978-3-423-2089-8"}, nil // Fallback: die Bestseller-Liste
}
return recs, nil
}
}
// Terminal: Logzeilen im Sekundentakt, während der Empfehlungsdienst hängt
// → 21:30:05 recommend err=context deadline exceeded (cb consecutive_failures=4)
// → 21:30:06 recommend err=context deadline exceeded (cb consecutive_failures=5)
// → 21:30:07 recommend err=exec refused request (circuit open — 0,04 ms statt 1.500 ms)
Stufe drei: Rate-Limits. Nicht, weil die Nutzer böse sind — sondern weil ein fehlerhafter Client oder ein Skript es sein kann. golang.org/x/time/rate (das erweiterte Standardbibliothek-Paket, golang.org/x — nicht std) vergibt pro Client-IP einen Token-Bucket — die Middleware sieht damit auch den primitivsten Angreifer in Schach:
// internal/api/ratelimit.go — pro Client-IP ein rate.Limiter
package api
import (
"net"
"sync"
"github.com/gin-gonic/gin"
"golang.org/x/time/rate"
)
var (
mu sync.Mutex
limiters = make(map[string]*rate.Limiter)
)
func limiterFor(ip string) *rate.Limiter {
mu.Lock()
defer mu.Unlock()
lim, ok := limiters[ip]
if !ok {
lim = rate.NewLimiter(5, 10) // 5 Requests/s pro IP, Burst bis 10
limiters[ip] = lim
}
return lim
}
func RateLimit() gin.HandlerFunc {
return func(c *gin.Context) {
host, _, err := net.SplitHostPort(c.Request.RemoteAddr)
if err != nil {
host = c.Request.RemoteAddr
}
if !limiterFor(host).Allow() {
c.AbortWithStatus(429) // Too Many Requests — ohne Body, Angreifern muss man nichts erklären
return
}
c.Next()
}
}
// Terminal: elf Requests in einer Sekunde von derselben IP
// → HTTP/1.1 200 OK (x10)
// → HTTP/1.1 429 Too Many Requests
Sicherungen stapeln — jede für eine andere Fehlerart
Timeouts beenden einzelne wartende Aufrufe, sind aber teuer: selbst ein abgebrochener Request hat den downstream schon belastet. Der Breaker verhindert die Anfrage komplett und gibt dem kranken Dienst Luft zum Atmen. Rate-Limits schützen vor dem anderen Extrem: zu viel Erfolg oder zu viel Feind. Keins ersetzt die anderen — wer nur Timeouts setzt, hämmert weiter auf einen toten Dienst; wer nur einen Breaker setzt, stirbt am ersten langsamen Request, bevor der Breaker überhaupt zählt.
⚠ Häufiger Fehler: Auf Timeout einfach dreimal denselben Request wiederholen — »dann klappt es ja vielleicht«. Wenn der Dienst überlastet ist, verdreifacht die Retry-Logik exakt die Last, die ihn umgebracht hat, und der Ausfall wird selbstverstärkend (Retry-Storm). Wenn überhaupt, dann mit exponentiellem Backoff plus Jitter, nur bei idempotenten Operationen und mit einem Gesamt-Budget, das die Retries mitzählt — der Circuit-Breaker ist fast immer die bessere erste Antwort.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Ship it: Docker, Version-Embedding & Release-Checkliste
Lektion 75 von 100
Der Moment, in dem »läuft bei mir« zählt
Release-Tag. Der Build läuft, das Image wandert in die Registry, der Pod startet — und der Erste, den das Betriebsteam fragt, lautet: »Welche Version läuft da — und wie rollbacken wir?« Wenn die einzige ehrliche Antwort »das latest-Tag von vorhin« ist, hast du den Auftrag dieses Moduls verpasst. Die letzte Lektion verdrahtet alles zu einem wiederholbaren Prozess: eine Binary, die ihre Version kennt, ein Image, das nichts Unnötiges enthält, und eine Checkliste, die niemand aus dem Kopf abrufen muss.
Stufe eins: Version-Embedding. Go hat dafür einen uralten, zuverlässigen Mechanismus: der Linker setzt Package-Variablen beim Bauen — -ldflags "-X main.version=1.4.0". Und seit Go 1.18 liefert debug.ReadBuildInfo() beim Bauen im Git-Repo sogar die Commit-Revision mit, ohne ein Flag:
// cmd/bookstore/version.go — Version zur Build-Zeit einbetten
package main
import (
"fmt"
"runtime/debug"
)
// -ldflags "-X main.version=1.4.0" setzt genau diese Variable beim Linken.
var version = "dev"
func buildVersion() string {
if version != "dev" {
return version
}
if bi, ok := debug.ReadBuildInfo(); ok { // go build im Git-Repo: vcs-Infos seit Go 1.18
if rev, ok := bi.Settings["vcs.revision"]; ok && len(rev.Value) >= 7 {
return fmt.Sprintf("dev-%s", rev.Value[:7])
}
}
return "dev"
}
// Terminal: go run ./cmd/bookstore version
// → bookstore dev-8f3c2ab
Dazu zwei Endpunkte, die der Betrieb wirklich braucht — /healthz (lebt der Prozess?) und /readyz (kann er arbeiten, also: erreicht er die Datenbank?):
// internal/api/health.go — Liveness und Readiness sind verschiedene Fragen
package api
import (
"context"
"net/http"
"time"
"github.com/gin-gonic/gin"
"github.com/jackc/pgx/v5/pgxpool"
)
func Healthz() gin.HandlerFunc {
return func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"ok": true}) }
}
func Readyz(pool *pgxpool.Pool) gin.HandlerFunc {
return func(c *gin.Context) {
ctx, cancel := context.WithTimeout(c.Request.Context(), 500*time.Millisecond)
defer cancel()
if err := pool.Ping(ctx); err != nil {
c.JSON(http.StatusServiceUnavailable, gin.H{"ready": false, "db": err.Error()})
return
}
c.JSON(http.StatusOK, gin.H{"ready": true, "version": buildVersion()})
}
}
// Terminal: curl -s localhost:8080/readyz
// → {"ready":true,"version":"1.4.0"}
//
// Terminal: während die Datenbank neu startet
// → {"ready":false,"db":"failed to connect"}
Stufe zwei: das Image. Multi-Stage-Build — der Compiler ist nur im ersten Stadium vorhanden, im zweiten liegt eine statische Binary in einem Distroless-Image ohne Shell, ohne Paketmanager, ohne Angriffsfläche:
# Dockerfile — Multi-Stage: bauen, dann nur die Binary mitnehmen
FROM golang:1.25 AS build
ARG VERSION=dev
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download # eigener Layer: Code-Änderungen laden keine Abhängigkeiten neu
COPY . .
RUN CGO_ENABLED=0 go build -trimpath \
-ldflags "-s -w -X main.version=${VERSION}" \
-o /out/bookstore ./cmd/bookstore
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/bookstore /bookstore
USER nonroot
ENTRYPOINT ["/bookstore"]
# Terminal: bauen, starten, schieben — mit fester Version als Tag
# → docker build -t registry.kurve.de/bookstore:1.4.0 --build-arg VERSION=1.4.0 .
# → docker run --rm -p 8080:8080 registry.kurve.de/bookstore:1.4.0
# → {"time":"2026-11-05T21:52:03+01:00","level":"INFO","msg":"lausche auf :8080","version":"1.4.0"}
Stufe drei: die Checkliste. Sie ist bewusst kurz — jede Zeile ein Haken, und der Deploy ohne vollen Haken-Satz bleibt liegen:
- Changelog komplett — jede Nutzer-sichtbare Änderung hat einen Eintrag.
go test ./... -racegrün — inklusive der Architektur-Tests aus Lektion 71.go vetundstaticcheck(honnef.co/go/tools) still — statische Analyse ohne Befund.- Migrationen lokal gegen Produktionsdaten probiert —
golang-migratehoch UND wieder runter (Lektion 72). - Image mit fester Version getaggt und in die Registry geschoben — nie
latest(siehe Fehler unten). /healthzund/readyzder neuen Version geprüft — inklusive derversionin der Antwort.- Rollback geprobt — das vorherige Image-Tag startet und besteht
/readyz. - Dashboards offen — die Kurven aus Lektion 73 sind sichtbar, während der Traffic umzieht.
Produktionsreife ist eine Eigenschaft des Prozesses, nicht des Codes
Keine Zeile in diesem Modul ist schwer. Produktionsreife entsteht daraus, dass die Dinge immer gleich passieren: Version kommt aus dem Build, nie aus dem Gedächtnis; der Deploy folgt der Checkliste, nie dem Tagesgefühl; der Rollback ist eine geübte Bewegung, kein Abenteuer. Das Capstone deiner Go-Reise ist deshalb kein Framework, sondern diese Disziplin — der Code aus den Modulen 11 bis 14 steckt schon drin.
⚠ Häufiger Fehler: Nach
:latestdeployen — und als Krönung noch vergessen,-X main.versionmitzugeben. Im laufenden Betrieb zeigt/readyzdanndev-irgendwas, drei Pods späterdev-wasanderes, und bei der Störung um 23 Uhr weiß niemand, welcher Code dort eigentlich läuft. Der Rollback ist ebenfallslatest— also Hoffen. Unveränderliche Versionstags sind die billigste Versicherung der Welt: einmal bauen, ein Tag, überall dasselbe Binary.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: