Modul 16: gRPC & Microservices
Der Buchhandlung wächst ein Mikroservice-Netz: Protobuf-Verträge mit Codegen, Streaming-RPCs in drei Geschmacksrichtungen, Interceptors, Deadline-Propagation und mTLS für den Betriebsalltag, Messaging mit NATS JetStream und Kafka (franz-go) samt Consumer-Patterns — und verteilte Konsistenz mit Saga und Outbox-Pattern.
Protobuf & gRPC-Grundlagen: Services, Messages, Codegen
Lektion 76 von 100
Die Buchhandlung bekommt Schwesterdienste
Nach dem Umbau aus Modul 15 läuft die Bookstore-API als solider Monolith — und genau der wird jetzt zum Opfer seines eigenen Erfolgs: Das Zahlungs-Team will unabhängig deployen, der Katalog braucht eigene Skalierung für die Preissuche, und jeder Release der Warenwirtschaft blockiert die anderen. Der Plan: drei Services — catalog, orders, shipping — die intern miteinander sprechen. Für diese interne Kommunikation wählen die Teams gRPC: Verträge in Protobuf, Binär-Transport über HTTP/2, Codegen für Go — kein JSON-Verhandeln, kein Handgeschriebener Client.
Der Kern ist der Vertrag: Eine .proto-Datei definiert Messages (Datenstrukturen mit nummerierten Feldern) und Services (RPC-Methoden). Aus ihr generiert protoc mit den offiziellen Plugins protoc-gen-go (google.golang.org/protobuf) und protoc-gen-go-grpc (google.golang.org/grpc) Server-Interfaces und Client-Stubs — beide Dienste kompilieren gegen dieselben Typen, und ein Vertragbruch fällt beim Build auf, nicht im Betrieb.
// api/proto/bookstore/v1/catalog.proto — der Vertrag kommt zuerst, der Code folgt
syntax = "proto3";
package bookstore.v1;
option go_package = "bookstore/gen/catalog/v1;catalogv1";
message Book {
string isbn = 1; // Feld-Nummern sind der Wire-Vertrag — Namen sind nur Deko
string title = 2;
string author = 3;
int32 price_cents = 4; // Cent als int32, wie in der Datenbank (Modul 12)
int32 stock = 5;
}
message GetBookRequest {
string isbn = 1;
}
service CatalogService {
rpc GetBook(GetBookRequest) returns (Book);
}
Die Codegen-Zeile ist prozedural, aber sie gehört ins Build (Makefile oder go:generate) — nie werden generierte Dateien versioniert und per Hand »gepflegt«:
# Codegen: protoc + die beiden offiziellen Go-Plugins
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
protoc --proto_path=api/proto \
--go_out=gen --go_opt=module=bookstore \
--go-grpc_out=gen --go-grpc_opt=module=bookstore \
api/proto/bookstore/v1/catalog.proto
# → gen/catalog/v1/catalog.pb.go (Messages: Book, GetBookRequest)
# → gen/catalog/v1/catalog_grpc.pb.go (Server-Interface + Client-Stub)
Der Katalog-Server implementiert das generierte Interface — die Einbettung von UnimplementedCatalogServiceServer ist Absicht und kein Boilerplate-Fluch: Neue RPCs im Vertrag brechen den Build alter Server nicht, bis jemand die Methode wirklich implementiert.
// internal/catalog/grpc.go — Server: der generierte Vertrag wird erfüllt
package catalog
import (
"context"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
catalogv1 "bookstore/gen/catalog/v1"
)
type Server struct {
catalogv1.UnimplementedCatalogServiceServer
store BookStore // Domänen-Schnittstelle aus Modul 15 — der Vertrag kennt keine SQL
}
func (s *Server) GetBook(ctx context.Context, req *catalogv1.GetBookRequest) (*catalogv1.Book, error) {
b, err := s.store.ByISBN(ctx, req.GetIsbn())
if err != nil {
return nil, status.Errorf(codes.NotFound, "isbn %q unbekannt", req.GetIsbn())
}
return &catalogv1.Book{
Isbn: b.Isbn,
Title: b.Title,
PriceCents: int32(b.PriceCents),
Stock: int32(b.Stock),
}, nil
}
// cmd/catalog/main.go — Anschluss: Listener, Registrierung, Serve
func main() {
lis, err := net.Listen("tcp", ":9090")
if err != nil {
log.Fatal(err)
}
srv := grpc.NewServer()
catalogv1.RegisterCatalogServiceServer(srv, catalog.NewServer(queries))
log.Println("gRPC lauscht auf", lis.Addr())
log.Fatal(srv.Serve(lis))
}
// Terminal: grpcurl -plaintext -d '{"isbn":"978-3-423-2089-8"}' localhost:9090 bookstore.v1.CatalogService/GetBook
// → {"author":"Paulo Coelho","isbn":"978-3-423-2089-8","priceCents":1295,"stock":3,"title":"Der Alchimist"}
Die Bestell-Seite ruft den Katalog mit dem generierten Stub auf — seit grpc-go v1.63 ist grpc.NewClient die richtige Konstruktion, grpc.Dial ist als veraltet markiert:
// internal/orders/catalogclient.go — Client: Stub über Verbindung, Deadline inklusive
func NewCatalogClient(addr string) (catalogv1.CatalogServiceClient, func(), error) {
conn, err := grpc.NewClient(addr,
grpc.WithTransportCredentials(insecure.NewCredentials())) // nur hinter dem Netz-Perimeter — Lektion 78
if err != nil {
return nil, nil, err
}
return catalogv1.NewCatalogServiceClient(conn), func() { _ = conn.Close() }, nil
}
func (s *Service) PriceFor(ctx context.Context, isbn string) (int32, error) {
ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
defer cancel()
b, err := s.catalog.GetBook(ctx, &catalogv1.GetBookRequest{Isbn: isbn})
if err != nil {
return 0, err // codes.DeadlineExceeded, codes.NotFound, codes.Unavailable — Lektion 78
}
return b.PriceCents, nil
}
// Terminal: Preisabfrage bei gesundem Katalog
// → err == nil, priceCents == 1295 — der RPC beantwortet in wenigen Millisekunden
//
// Terminal: Katalog-Instanz abgestürzt
// → err: rpc error: code = Unavailable ... — grpc retryt connection-los transparent (Wait-for-Ready separat)
Feld-Nummern sind der Vertrag — Feld-Namen nicht
Protobuf serialisiert nicht die Namen, sondern die Nummern: Auf der Leitung steht »Feld 4 hat den Wert 1295«, nicht »price_cents«. Eine Umbenennung ist deshalb nachträglich harmlos (alle Seiten übersetzen dieselbe Nummer in ihren eigenen Namen), während das Neuverwenden einer Nummer für einen anderen Typ stille Datenkorruption erzeugt. Deshalb steht in jedem guten .proto-File am Ende ein Kommentar: Nummern nie wiederverwenden, entfernte Felder mit reserved abschotten.
⚠ Häufiger Fehler: Ein Feld im Protobuf entfernen und seine Nummer später für etwas Neues wiederverwenden. Alte Clients, die noch den alten Vertrag kompiliert haben, dekodieren die neuen Bytes stumm in den alten Typ: Aus
stock int32 = 5wird plötzlichdiscount_percent int32 = 5, ohne Fehler, ohne Log — der Bestandsservice reserviert Ware mit »Rabatt 3« als Stückzahl. Entfernte Felder gehören inreserved 5; reserved "stock";, damit der Compiler jede Wiederverwendung zur Compile-Zeit verweigert.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Streaming-RPCs: Server-, Client- & Bidirectional Streams
Lektion 77 von 100
Ein Call, viele Nachrichten — der Bestand wird live
Der Katalog-Dienst liefert Einzelpreise gut und schön — aber das Lagerregal der »Kant & Kurve« lebt: Der Bestand ändert sich sekündlich, das Frontend will Live-Aktualisierungen, und der Import von 40.000 Titeln aus dem Distributor-CSV will nicht als ein 60-MB-Request durch die Leitung. Genau für diese drei Formen hat gRPC Streaming: Server-Streaming (eine Frage, viele Antworten), Client-Streaming (viele Nachrichten rein, eine Zusammenfassung raus) und Bidirektional (beide Seiten senden, wann sie wollen). Unter der Haube bleibt es HTTP/2 — ein Call, ein Stream, Frames in beide Richtungen.
Streaming ist kein Kanal-Wechsel, sondern ein Vertrag mit Ende-Signal
Jede Streaming-Richtung bedeutet im generierten Code ein anderes Interface — und jede Seite braucht ein definiertes Ende. Server-Streams enden, wenn der Handler zurückkehrt; Clients erkennen das an io.EOF von Recv. Client-Streams enden mit CloseSend plus Recv der Einzigen Antwort. Wer das Ende-Signal behandelt, hat keine hängenden Goroutines; wer es als Fehler behandelt, baut eine Retry-Schleife um ein normales Ende.
Erst der Vertrag — drei Methoden, drei Richtungen:
// api/proto/bookstore/v1/inventory.proto — Streaming im Vertrag
syntax = "proto3";
package bookstore.v1;
option go_package = "bookstore/gen/inventory/v1;inventoryv1";
import "google/protobuf/timestamp.proto";
message StockUpdate {
string isbn = 1;
int32 stock = 2;
google.protobuf.Timestamp as_of = 3;
}
message NewBook {
string isbn = 1;
string title = 2;
int32 price_cents = 3;
}
message ImportSummary {
int32 imported = 1;
int32 rejected = 2;
}
message GetBookRequest {
string isbn = 1;
}
service InventoryService {
rpc WatchStock(GetBookRequest) returns (stream StockUpdate); // Server-Streaming
rpc BulkImport(stream NewBook) returns (ImportSummary); // Client-Streaming
rpc LiveInventory(stream GetBookRequest) returns (stream Book); // Bidirektional
}
Server-Streaming — der Handler hält den Call offen und sendet, bis die Subscription endet oder der Client weg ist:
// internal/inventory/grpc.go — Server-Streaming: Send in einer Schleife, Ende per return
func (s *Server) WatchStock(req *catalogv1.GetBookRequest, stream inventoryv1.InventoryService_WatchStockServer) error {
events := s.stock.Subscribe(req.GetIsbn()) // Kanal aus dem Bestands-Pub/Sub
defer s.stock.Unsubscribe(events)
for u := range events {
if err := stream.Send(&inventoryv1.StockUpdate{
Isbn: u.Isbn,
Stock: int32(u.Stock),
AsOf: timestamppb.New(u.At),
}); err != nil {
return err // Client weg (Kontext abgebrochen) — Send meldet das als Fehler
}
}
return nil // Subscription zu: Stream endet sauber, der Client sieht io.EOF
}
// Terminal: Bestand ändert sich zweimal, dann Lagerabschluss
// → {"isbn":"978-3-423-2089-8","stock":4,"asOf":"2026-11-07T14:02:11Z"}
// → {"isbn":"978-3-423-2089-8","stock":3,"asOf":"2026-11-07T14:02:44Z"}
// → (Stream-Ende)
Auf der Client-Seite ist die Schleife das Muster — und das Ende-Signal ist die Stolperfalle:
// internal/dashboard/stockwatch.go — Client: Recv-Schleife mit io.EOF als normalem Ende
func WatchISBN(ctx context.Context, inv inventoryv1.InventoryServiceClient, isbn string) error {
stream, err := inv.WatchStock(ctx, &inventoryv1.GetBookRequest{Isbn: isbn})
if err != nil {
return err
}
for {
u, err := stream.Recv()
switch {
case errors.Is(err, io.EOF):
return nil // sauberes Stream-Ende — KEIN Fehler, keine Retry
case err != nil:
return err // Verbindungs- oder Server-Fehler — hier gehört Retry/Hin
}
apply(u) // UI oder Cache aktualisieren
}
}
// Terminal: 2 Updates empfangen, dann endet der Server den Stream
// → Bestand aktualisiert: 4
// → Bestand aktualisiert: 3
// → WatchISBN beendet mit nil — die Schleife lief nicht ins Fehler-Handling
Bidirektional — Senden und Empfangen laufen parallel, jede Richtung mit eigenem Ende:
// internal/inventory/live.go — Bidi: Send in einer Goroutine, CloseSend schließt die eine Richtung
func (c *Client) LiveInventory(ctx context.Context, isbns []string) ([]*inventoryv1.Book, error) {
stream, err := c.stub.LiveInventory(ctx)
if err != nil {
return nil, err
}
go func() {
defer stream.CloseSend() // Hälfte zu: der Server weiß, dass keine ISBN mehr kommt
for _, isbn := range isbns {
if err := stream.Send(&inventoryv1.GetBookRequest{Isbn: isbn}); err != nil {
return
}
}
}()
var books []*inventoryv1.Book
for {
b, err := stream.Recv()
if errors.Is(err, io.EOF) {
return books, nil
}
if err != nil {
return nil, err
}
books = append(books, b)
}
}
// Terminal: 40.000 Import-Titel als Client-Streaming hochschieben
// → sent 40000 records, stream offen — Speicher flach, weil stückweise gesendet wird
// → summary: {"imported":39412,"rejected":588} — EINE Antwort am Ende
⚠ Häufiger Fehler:
io.EOFvonstream.Recv()als echten Fehler behandeln — also mit Retry-Schleife, Alarm-Log oder einem 500 an den Nutzer quittieren. EOF ist hier das vereinbarte Ende-Signal: Der Server hat den Stream ordnungsgemäß beendet (sein Handler hatreturn nilgeliefert). Die typische Folge der Verwechslung: ein Client, der nach jedem ordentlichen Stream-Ende einen »Fehler« alarmiert, oder schlimmer — ein Retry, der denselben Streaming-Call endlos neu startet. Erst EOF prüfen (errors.Is(err, io.EOF)), danach erst alle übrigen Fehler behandeln.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
gRPC in der Praxis: Interceptors, Deadline-Propagation, TLS/mTLS
Lektion 78 von 100
Der Katalog ist produktionsreif — oder hängt gerade?
Drei Services sprechen jetzt Protobuf miteinander. Was in der Demo funktioniert, stellt im Betrieb die richtigen Fragen: Jeder interne Call braucht Authentifizierung (nicht jeder Service darf Zahlungen auslösen), strukturiertes Logging mit Metadaten (welcher Call dauerte wie lange?), und vor allem ein Ende: Wenn der Katalog hängt, darf der Bestell-Service nicht ewig warten — und der Katalog selbst darf beim Aufruf der Datenbank nicht länger warten als der Client ihm Zeit geliehen hat. Genau hier kommen Interceptors, Deadline-Propagation und (m)TLS ins Spiel.
Die Deadline ist dabei kein Go-Detail, sondern Architektur: Timeouts, die vom Client über jeden Hop mitwandern, sind die Voraussetzung für Retry-Budgets und Circuit-Breaking — das Resilienz-Modul des Architektur-Kurses behandelt die Kette Deadline, Retry mit Jitter und Bulkhead als System. Hier bauen wir die Go-Seite davon.
Interceptors sind die Middleware des RPC — die Zwiebel gilt weiter
Ein Interceptor ist genau eine Funktion um jeden RPC-Handler: (ctx, req, info, handler) (any, error). Gestapelt mit ChainUnaryInterceptor entsteht dieselbe Zwiebel aus Modul 12: Recovery außen, dann Logging, dann Auth, dann der Handler. Der Unterschied zum HTTP-Middleware-Stack: Der Kontext trägt automatisch die Deadline des Aufrufers — wenn der Client 2 Sekunden reserviert hat, sieht der Server-Handler denselben Kontext mit denselben Rest-300-Millisekunden.
Der Logging-Interceptor — Struktur wie slog aus Modul 13, Methode und Dauer als Felder:
// internal/interceptors/logging.go — ein Interceptor = eine Funktion um jeden RPC
package interceptors
import (
"context"
"log/slog"
"time"
"google.golang.org/grpc"
)
func Logging(logger *slog.Logger) grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
handler grpc.UnaryHandler) (any, error) {
start := time.Now()
resp, err := handler(ctx, req) // die Kette darunter aufrufen
logger.Info("rpc",
"method", info.FullMethod,
"err", err,
"dur_ms", time.Since(start).Milliseconds(),
)
return resp, err
}
}
Auth aus den Metadaten — gRPC-Header heißen hier metadata und reisen im Kontext:
// internal/interceptors/auth.go — Token aus metadata prüfen, vor dem Handler
func Auth(valid TokenValidator) grpc.UnaryServerInterceptor {
return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
handler grpc.UnaryHandler) (any, error) {
md, ok := metadata.FromIncomingContext(ctx)
if !ok || len(md.Get("authorization")) == 0 {
return nil, status.Error(codes.Unauthenticated, "Bearer-Token erforderlich")
}
token := strings.TrimPrefix(md.Get("authorization")[0], "Bearer ")
claims, err := valid.Parse(ctx, token) // z. B. github.com/golang-jwt/jwt/v5
if err != nil {
return nil, status.Errorf(codes.Unauthenticated, "Token ungültig: %v", err)
}
return handler(context.WithValue(ctx, claimsKey{}, claims), req)
}
}
// Client-Seite: Metadaten mitschicken
ctx = metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer "+token)
// Terminal: Call ohne Token
// → rpc error: code = Unauthenticated desc = Bearer-Token erforderlich
//
// Terminal: gültiger Call
// → {"level":"INFO","msg":"rpc","method":"/bookstore.v1.CatalogService/GetBook","dur_ms":4}
Deadline-Propagation — der Client leiht dem gesamten Aufrufpfad ein Budget, und jeder Server erbt die Restzeit:
// internal/orders/service.go — Client reserviert 2 s für den ganzen Pfad
ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
book, err := s.catalog.GetBook(ctx, req) // grpc schickt die Deadline als grpc-timeout-Header mit
// internal/catalog/grpc.go — der Server erbt die Restzeit für seine Sub-Calls
func (s *Server) GetBook(ctx context.Context, req *catalogv1.GetBookRequest) (*catalogv1.Book, error) {
ctx, cancel := context.WithTimeout(ctx, 800*time.Millisecond) // Teilbudget vom geerbten Kontext
defer cancel()
b, err := s.store.ByISBN(ctx, req.GetIsbn()) // dieselbe Deadline erreicht die DB
...
}
// Terminal: Katalog-DB hängt, Client wartet mit 2 s Budget
// → Client: rpc error: code = DeadlineExceeded desc = context deadline exceeded (nach 2.0 s)
// → Server-Log: {"method":"/bookstore.v1.CatalogService/GetBook","err":"context deadline exceeded"}
Zum Transport: intern zwischen Diensten ist TLS Standard, nicht Kür — mit Client-Zertifikaten (mTLS) authentifizieren sich beide Seiten gegenseitig, was der Service-Mesh-gewohnte Betrieb ohnehin verlangt:
// internal/transport/mtls.go — mTLS: Server verlangt und verifiziert Client-Zertifikate
func ServerCreds() (credentials.TransportCredentials, error) {
cert, err := tls.LoadX509KeyPair("certs/catalog.crt", "certs/catalog.key")
if err != nil {
return nil, err
}
caPEM, err := os.ReadFile("certs/internal-ca.crt")
if err != nil {
return nil, err
}
ca := x509.NewCertPool()
if !ca.AppendCertsFromPEM(caPEM) {
return nil, errors.New("CA-Pool unlesbar")
}
return credentials.NewTLS(&tls.Config{
Certificates: []tls.Certificate{cert},
ClientCAs: ca,
ClientAuth: tls.RequireAndVerifyClientCert, // das M in mTLS
MinVersion: tls.VersionTLS13,
}), nil
}
// srv := grpc.NewServer(grpc.Creds(creds))
// Client: grpc.WithTransportCredentials(clientTLS) — mit eigenem Zertifikat des orders-Service
// Terminal: grpcurl -insecure localhost:9090 list (ohne Client-Zertifikat)
// → rpc error: code = Unavailable ... TLS handshake failed: bad certificate
⚠ Häufiger Fehler: Interne gRPC-Calls ganz ohne Deadline absetzen — weil »interne Netze sind schnell«. In Wahrheit wartet ein Call ohne Deadline unbegrenzt: Hängt die DB hinter dem Katalog, stapeln sich im Bestell-Service die hängenden Handler und ihre Goroutines, der Connection-Pool läuft voll, und aus einem langsamen Katalog wird ein kompletter Ausfall des Ladens. Der Client-Kontext ohne Timeout propagiert auch keine grpc-timeout an den Server — der kann gar nicht wissen, wie lange er sich Zeit leihen darf. Jeder outgoing Call bekommt ein Budget (
context.WithTimeout), und Server-Services portionieren es für ihre Sub-Calls weiter.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Messaging: NATS vs Kafka & Consumer-Patterns
Lektion 79 von 100
Bestellungen als Ereignisse — und die Frage nach dem Transport
gRPC ist synchronous: Der Bestell-Service fragt, der Katalog antwortet. Aber der Laden will auch, dass die Welt von Ereignissen erfährt, die gerade passiert sind: OrderPlaced, StockChanged, ShipmentDispatched. Mehrere Dienste sollen darauf reagieren — Rechnungsstellung, Analytics, der Versand — ohne dass der Besteller auf sie wartet. Das ist Messaging. Die zwei realen Go-Optionen mit ihren exakten Pfaden: NATS (github.com/nats-io/nats.go inkl. des jetstream-Sub-Pakets) und Kafka mit franz-go (github.com/twmb/franz-go) oder sarama (github.com/IBM/sarama).
Die Liefergarantie entscheidet, nicht der Broker-Ruf
NATS Core ist at-most-once (feuer und vergessen), NATS JetStream macht at-least-once mit persistierten Streams und expliziten Acks; Kafka ist von Haus aus ein persistentes, partitioniertes Log mit Consumer-Groups und Offsets. Beide liefern im Fehlerfall mindestens einmal — und das zwingt jeden Consumer, idempotent zu sein, denn Duplikate sind normal, nicht Ausnahme. Der Broker-Kauf entscheidet nicht über Korrektheit; das Ack- und Retry-Verhalten des Consumers tut es.
Die Gegenüberstellung für die »Kant & Kurve«:
| NATS (+ JetStream) | Kafka (franz-go / sarama) | |
|---|---|---|
| Modell | Subjects (bookstore.orders.>), Streams | Topics, partitionierte Logs |
| Persistenz | Core: keine; JetStream: Datei/ Speicher | immer Log auf Disk |
| Garantie | Core: at-most-once; JetStream: at-least-once | at-least-once (Consumer-Offsets) |
| Reihenfolge | je Subject pro Consumer | pro Partition garantiert |
| Skalierung | Consumer-Queues, leichtgewichtig | Consumer-Groups, Partition-Grenze |
| Betrieb | ein kleines Binary | Broker-Cluster, ZooKeeper-frei aber Schwergewicht |
Für Ereignisse wie OrderPlaced genügt JetStream bequem; wer später Ereignis-Sourcing, lange Retention und massive Partition-Parallelität braucht, wechselt auf Kafka — die Consumer-Patterns sind dieselben.
NATS JetStream mit dem modernen jetstream-Sub-Paket (seit nats.go v1.34, die alte js.Subscribe-API bleibt bestehen):
// internal/bus/nats.go — Stream anlegen und als Work-Queue konsumieren
package bus
import (
"context"
"log"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
)
func Connect(ctx context.Context) (*jetstream.JetStream, func(), error) {
nc, err := nats.Connect("nats://nats.internal:4222")
if err != nil {
return nil, nil, err
}
js, err := jetstream.New(nc)
if err != nil {
nc.Close()
return nil, nil, err
}
return &js, nc.Close, nil
}
func ConsumeOrders(ctx context.Context, js jetstream.JetStream, handle func([]byte) error) error {
if _, err := js.CreateOrUpdateStream(ctx, jetstream.StreamConfig{
Name: "BOOKSTORE",
Subjects: []string{"bookstore.orders.>"},
}); err != nil {
return err
}
c, err := js.CreateOrUpdateConsumer(ctx, "BOOKSTORE", jetstream.ConsumerConfig{
Durable: "order-processor",
AckPolicy: jetstream.AckExplicitPolicy, // jede Message braucht ihr eigenes Ack
})
if err != nil {
return err
}
cc, err := c.Consume(func(msg jetstream.Msg) {
if err := handle(msg.Data()); err != nil {
_ = msg.Nak() // zurück in die Queue — später nochmal, mit Verzögerung
return
}
_ = msg.Ack() // bestätigen erst NACH erfolgreicher Verarbeitung
})
if err != nil {
return err
}
defer cc.Stop()
<-ctx.Done()
return nil
}
// Terminal: Broker startet neu, während 3 Bestellungen verarbeitet wurden
// → die 3 unbestätigten Messages werden redelivered — handle() läuft erneut (idempotent!)
Kafka mit franz-go — derselbe Vertrag, andere Mechanik: Offsets statt Acks, Commit nach der Verarbeitung:
// internal/bus/kafka.go — franz-go: Poll-Schleife mit manuellem Commit
package bus
import (
"context"
"log"
"github.com/twmb/franz-go/pkg/kgo"
)
func ConsumeOrders(ctx context.Context, handle func([]byte) error) error {
cl, err := kgo.NewClient(
kgo.SeedBrokers("kafka-1.internal:9092", "kafka-2.internal:9092"),
kgo.ConsumerGroup("order-processor"),
kgo.ConsumeTopics("bookstore.orders"),
kgo.DisableAutoCommit(), // Auto-Commit würde Offsets sichern, die niemand verarbeitet hat
)
if err != nil {
return err
}
defer cl.Close()
for {
fetches := cl.PollRecords(ctx, 100)
if fetches.IsClientClosed() {
return nil
}
fetches.EachError(func(_ string, _ int32, err error) {
log.Printf("fetch-Fehler: %v", err) // Partition-Probleme, Broker-Neustart — nicht fatal
})
fetches.EachRecord(func(r *kgo.Record) {
if err := handle(r.Value); err != nil {
log.Printf("verarbeitung fehlgeschlagen, offset bleibt: %v", err)
return // kein Commit für diesen Record — die Group holt ihn später erneut
}
})
cl.CommitRecords(ctx, fetches.Records()...) // nur verarbeitete Offsets sichern
}
}
// Terminal: group: bookstore.orders, Partition 2, 12 Records
// → verarbeitung ok für 12 Records, committed bis offset 4831
⚠ Häufiger Fehler: Die Message sofort bestätigen und erst danach verarbeiten —
msg.Ack()in der ersten Zeile des Handlers (beziehungsweise Auto-Commit aktiviert). Dann stirbt der Prozess mitten in der Verarbeitung: Der Broker hält die Nachricht für erledigt, die Bestellung ist weg — aus at-least-once wurde durch die Ack-Reihenfolge stilles at-most-once. Die umgekehrte Falle ist der Grund, warum Duplikate normal sind: Ack erst nach der Verarbeitung bedeutet, dass ein Crash zwischen Verarbeitung und Ack die Message redelivert. Beides zusammen ergibt die einzige richtige Kombination: spätes Ack plus idempotenter Handler (Bestell-ID als Schlüssel, Upsert statt Insert).
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Verteilte Transaktionen: Saga & Outbox-Pattern
Lektion 80 von 100
Die Bestellung, die Zahlung und das Leck dazwischen
Jetzt der letzte Act des Umbaus: Der orders-Service schreibt die Bestellung in seine PostgreSQL-Datenbank und will der Welt davon erzählen — Rechnungsstellung, Versand und Analytics sollen auf OrderPlaced reagieren. Genau an der Naht passiert der klassische Verteilungsfehler: Die Bestellung landet in der Datenbank, der Publish an NATS/Kafka schlägt fehl — und die Bestellung existiert, aber kein anderer Service weiß davon. Umgekehrt ist es genauso schlimm: Erst publizieren, dann speichern, und der Insert scheitert — die Welt reagiert auf eine Bestellung, die es nie gab. Das ist das Dual-Write-Problem, und seine Lösung — das Outbox-Pattern — ist bei Weitem kein Go-Geheimnis, sondern Architektur: Das Saga- und Outbox-Modul des Architektur-Kurses behandelt beide Muster und ihre Kompensations-Ketten systematisch. Hier die Go-Implementierung.
Outbox: das Ereignis wird Teil derselben Transaktion
Die Idee ist unspektakulär und wirksam: Statt den Broker direkt anzurufen, schreibt der Service das Ereignis als Zeile in eine outbox-Tabelle — in derselben Datenbank-Transaktion wie die Fachlichkeit. Commit schafft beide oder keinen. Ein separater Relay-Prozess (oder Debezium) liest die Outbox, publiziert an den Broker und markiert die Zeile. Schlägt der Publish fehl, bleibt die Zeile stehen und wird erneut versendet. Der Preis: Der Relay erzeugt at-least-once — auch hier gilt, dass Consumer idempotent sein müssen.
Der Write-Pfad — Bestellung und Ereignis in einem Commit:
// internal/orders/outbox.go — Bestellung und Event: eine Transaktion, ein Commit
package orders
import (
"context"
"encoding/json"
"github.com/jackc/pgx/v5/pgxpool"
)
func (s *Store) PlaceOrder(ctx context.Context, o Order) error {
tx, err := s.pool.Begin(ctx)
if err != nil {
return err
}
defer tx.Rollback(ctx) // nach Commit ein No-op — kein Fehlerfall mehr
if _, err := tx.Exec(ctx,
`INSERT INTO orders (id, isbn, qty, status) VALUES ($1, $2, $3, 'pending')`,
o.ID, o.ISBN, o.Qty); err != nil {
return err
}
payload, err := json.Marshal(OrderPlaced{ID: o.ID, ISBN: o.ISBN, Qty: o.Qty})
if err != nil {
return err
}
if _, err := tx.Exec(ctx,
`INSERT INTO outbox (topic, payload) VALUES ($1, $2)`,
"bookstore.orders.placed", payload); err != nil {
return err
}
return tx.Commit(ctx) // Bestellung + Event-Zeile: beides oder nichts
}
// Terminal: Commit ok
// → orders: 1 Zeile (status pending), outbox: 1 Zeile (sent_at NULL)
//
// Terminal: Broker-Ausfall stört den Commit NICHT — die Outbox ist ja nur eine Tabelle
// → Bestellung existiert, Event wartet auf den Relay
Der Relay — ein eigener Prozess, der die Outbox leert:
// internal/orders/relay.go — Outbox lesen, publizieren, markieren; im Fehlerfall bleibt die Zeile stehen
func (s *Relay) Run(ctx context.Context) error {
t := time.NewTicker(250 * time.Millisecond)
defer t.Stop()
for {
select {
case <-ctx.Done():
return ctx.Err()
case <-t.C:
rows, err := s.pool.Query(ctx,
`SELECT id, topic, payload FROM outbox WHERE sent_at IS NULL ORDER BY id LIMIT 50`)
if err != nil {
continue // DB kurz weg: nächster Tick probiert es wieder
}
for rows.Next() {
var id int64
var topic string
var payload []byte
if err := rows.Scan(&id, &topic, &payload); err != nil {
break
}
if err := s.bus.Publish(ctx, topic, payload); err != nil {
break // Broker down: nichts markieren, nächster Tick nochmal
}
if _, err := s.pool.Exec(ctx,
`UPDATE outbox SET sent_at = now() WHERE id = $1`, id); err != nil {
log.Printf("markieren fehlgeschlagen, Message wird dupliziert: %v", err)
}
}
rows.Close()
}
}
}
// Terminal: Relay-Tick nach Broker-Wiederkehr
// → published bookstore.orders.placed (order bb-1042), sent_at gesetzt
Die Saga: Mehrere Services beteiligen sich an einem Geschäftsvorgang, ohne eine gemeinsame Transaktion. Statt Rollback — das über Dienstgrenzen nicht existiert — läuft jede phase mit einer vorbereiteten Kompensation:
// internal/orders/saga.go — Orchestrierung: Schritte vorwärts, Kompensation rückwärts
type step struct {
name string
do func(ctx context.Context, orderID string) error
undo func(ctx context.Context, orderID string) error
}
func (s *Saga) Run(ctx context.Context, orderID string) error {
steps := []step{
{"reserve", s.reserveStock, s.releaseStock},
{"charge", s.chargeCard, s.refund},
{"ship", s.createShipment, s.cancelShipment},
}
var done []step
for _, st := range steps {
if err := st.do(ctx, orderID); err != nil {
for i := len(done) - 1; i >= 0; i-- { // rückwärts auflösen
if uerr := done[i].undo(ctx, orderID); uerr != nil {
s.log.Error("kompensation fehlgeschlagen",
"step", done[i].name, "order", orderID, "err", uerr)
// nicht abbrechen: alle restlichen Kompensationen müssen trotzdem laufen
}
}
return fmt.Errorf("schritt %q fehlgeschlagen: %w", st.name, err)
}
done = append(done, st)
}
return nil
}
// Terminal: Zahlung bei Schritt "charge" abgelehnt
// → kompensation: releaseStock(bb-1042) ok — Lager wieder frei
// → err: schritt "charge" fehlgeschlagen: card declined (insufficient_funds)
// → orders: status 'failed', Kunde sieht "Zahlung abgelehnt", keine halben Zustände
⚠ Häufiger Fehler: Den Dual-Write mit »publish, dann speichern« oder »speichern, dann publish« reparieren wollen — beide Reihenfolgen haben ein Loch genau dazwischen, weil Datenbank und Broker keine gemeinsame Transaktion kennen. Es gibt keinen Commit, der beide atomar macht, und Retry-Bibliotheken ändern das nicht. Die einzige lösbare Variante ist das Outbox-Pattern: Das Ereignis wird in dieselbe lokale Transaktion geschrieben wie der Fachlichkeits-Satz, und ein Relay überbrückt die Lücke zum Broker mit at-least-once plus idempotenten Consumern. Wer nur »meistens konsistent« braucht, zahlt später die Rechnung in Form von Bestellungen ohne Rechnung — oder Rechnungen ohne Bestellung.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: