Modul 11: Packages, Modules & Architektur
Go-Projekte bauen, die mitwachsen: go.mod, Versionsauswahl mit MVS, go.sum und Proxy, Packages sauber schneiden mit internal/, cmd/ und API-Design, Ports & Adapters als Architekturmuster, Dependency Injection von Hand bis Wire & Fx, und ein Projekt-Layout-Katalog vom Monolith bis zum Microservice.
go.mod & Versionsauswahl: MVS, go.sum & Proxy
Lektion 51 von 100
Wer entscheidet, welche Version läuft?
Der Task-Service aus Modul 10 wird ernst: Die Tests sollen nach github.com/stretchr/testify umziehen, die Migrationen auf die Postgres-DB übernimmt github.com/golang-migrate/migrate/v4. Kaum sind die ersten Abhängigkeiten da, stellen sich die Fragen, die in anderen Sprachen ganze Manifest-Formate hervorgebracht haben: Wer entscheidet, welche Version einer Bibliothek im finalen Build landet? Was passiert, wenn zwei Pakete verschiedene Versionen desselben Pakets brauchen? Und was steht eigentlich in dieser go.sum-Datei, die beim ersten go build mit ein paar Dutzend Zeilen erscheint?
Gos Antwort auf all das ist absichtlich langweilig — und genau das macht sie stark. Ein Modul wird in go.mod deklariert, Versionen wählt der Algorithmus Minimal Version Selection (MVS) aus, Integrität sichert go.sum ab, und die Downloads kommen standardmäßig seit Go 1.13 vom Modul-Proxy proxy.golang.org. Kein Lockfile-Gebetskreis, keine Auflösungs-Diamanten: dieselbe go.mod lief auf jedem Rechner desselben Teams dasselbe Ergebnis.
MVS wählt die höchste geforderte Version — nicht die neueste
Minimal Version Selection heißt nicht »nimm die älteste«, sondern: nimm von jeder Abhängigkeit die höchste Version, die irgendein Modul im Build-Graphen explizit verlangt — und schau nie, was sonst noch alles auf dem Proxy verfügbar wäre. Verlangt A x/text v0.14.0 und B x/text v0.19.0, baut Go mit v0.19.0, egal dass es v0.21.0 bereits gibt. Ergebnis: Upgrades passieren nur, wenn du sie anstößt — Builds bleiben reproduzierbar, weil die Auswahl nur von den go.mod-Dateien abhängt, nie von einem Zufallszeitpunkt im Netz.
Die Anatomie einer go.mod an der echten Datei des Projekts:
// go.mod — Herzstück des Moduls github.com/acme/taskd
module github.com/acme/taskd
// Seit Go 1.21 steuert diese Zeile auch die Toolchain:
// passt sie nicht zur installierten Go-Version, lädt Go die
// passende automatisch nach (Stichwort toolchain-Direktive).
go 1.25
require (
github.com/golang-migrate/migrate/v4 v4.18.1
github.com/stretchr/testify v1.10.0
)
require (
// indirekte Abhängigkeiten: Diese Liste pflegt `go mod tidy`,
// seit Go 1.17 ist sie aufgeschlüsselt (Module-Graph-Pruning).
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
)
// Terminal: eine Abhängigkeit hinzufügen
// $ go get github.com/stretchr/testify@v1.10.0 && go mod tidy
// → go: added github.com/stretchr/testify v1.10.0
//
// Terminal: was ist im Build-Graphen? (gefiltert)
// $ go list -m all | head -3
// → github.com/acme/taskd
// → github.com/davecgh/go-spew v1.1.1
// → github.com/golang-migrate/migrate/v4 v4.18.1
go get aktualisiert Versionen, go mod tidy hält require und die tatsächlich importierten Packages synchron — es entfernt, was niemand mehr importiert, und ergänzt, was importiert, aber nicht eingetragen ist. Der Suffix /v4 in migrate ist keine Dekoration: Module mit Major-Version größer als 1 tragen die Nummer im Pfad, sodass v4 und (hypothetisches) v5 parallel existieren können, ohne sich zu beißen.
go.sum ist ein Siegel, keine Sperrdatei
Die häufigste Fehlannahme rund um Module betrifft go.sum. Die Datei sieht aus wie ein Lockfile — ist aber keins. Sie enthält Checksummen (h1:-Hashes) für Modulinhalte und go.mod-Dateien und wird bei jedem Download gegen die Prüfsummen-Datenbank sum.golang.org verifiziert. Welche Version gebaut wird, entscheidet ausschließlich MVS anhand der go.mod-Dateien.
// go.sum — zwei Zeilen pro Abhängigkeit: Modulinhalt und go.mod-Datei
// github.com/stretchr/testify v1.10.0 h1:eiSyrtoKnKsA+...
// github.com/stretchr/testify v1.10.0/go.mod h1:UcvrxSs7...
//
// Was go.sum NICHT tut: Versionen festnageln. Wer die Version
// ändern will, ändert go.mod (via go get) — nicht go.sum.
//
// Terminal: was passiert bei manipulierter go.sum?
// $ go build ./... # go.sum-Zeile von testify verändert
// → verifying github.com/stretchr/testify@v1.10.0: checksum mismatch
// → SECURITY ERROR
// → This download does not match an earlier download recorded in the go.sum log.
//
// Terminal: das ist auch der Grund, warum Löschen nichts fixt:
// $ rm go.sum && go mod tidy && go build ./...
// → go: downloading github.com/stretchr/testify v1.10.0
// → (neue go.sum wird erzeugt, Build läuft durch)
Der Proxy selbst — GOPROXY=https://proxy.golang.org,direct ist der Default — macht Downloads schnell und auditierbar: Einmal publizierte Modulversionen sind dort unveränderlich, und GOPRIVATE=corp.example.com signalisiert Go seit Go 1.13, dass interne Module den Proxy und die Prüfsummen-DB umgehen und direkt aus dem firmeneigenen Git kommen.
⚠ Häufiger Fehler:
go.sumals Lockfile im npm-Sinn zu behandeln und von Hand zu editieren — Versionen hochzudrücken, Zeilen zu löschen, um ein »streikendes« Paket zu reparieren. Der Handgriff verschwindet beim nächstengo mod tidywieder (die Datei wird neu generiert), und die halbe Stunde Fehlersuche war umsonst. Versionen ändert man ausschließlich übergo get pkg@v1.2.3odergo get -u pkgingo.mod; istgo.sumselbst korrupt, gehört die komplette Datei gelöscht und mitgo mod tidyfrisch erzeugt — niemals einzelnen Zeilen chirurgisch »geheilt«.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Packages richtig schneiden: internal/, cmd/ & API-Design
Lektion 52 von 100
Der Moment, in dem ein Ordner zur Vertragsverhandlung wird
Der Task-Service funktioniert — aber alles liegt in einem Package: Store, HTTP-Handler, Mail-Versand, Konfiguration, jede Typdefinition. Jetzt will das Reporting-Team aus einer anderen Abteilung genau eine Sache wiederverwenden: den Store. Zur gleichen Zeit stolpert jemand beim Refactoring in die Meldung import cycle not allowed, und aus der Not heraus kursiert im Team der Vorschlag, einfach alles in ein gemeinsames models-Package zu ziehen.
Genau hier entscheidet sich, ob das Projekt in einem Jahr angenehm oder schmerzhaft ist. In Go ist das Package die einzige echte Kapselungsgrenze: Kein private pro Feld, kein friend-Mechanismus — sichtbar ist, was großgeschrieben ist, und zwar für alle, die das Package importieren dürfen. Ein Package zu schneiden bedeutet also, eine öffentliche API zu definieren. Das Interface-Segregation-Prinzip aus der Solid-Principles-Reihe gilt auf Package-Ebene wortwörtlich: kleine Oberflächen, wenige Exporte, kein »hier ist alles, sucht euch raus«.
Ein Package ist eine API, kein Ordner
Der Package-Name steht an jeder Aufrufstelle (store.Add, nicht taskd_internal_store.Add) — er ist Teil der Lesbarkeit jedes Imports. Faustregeln: Ein Package bekommt einen Substantiv-Namen im Singular und eine raison d'être in einem Satz. Was zwei Sätze mit »und« braucht, sind meist zwei Packages. Und der Export ist eine Zusage: Alles Große geschriebene musst du kompatibel halten — exportiere deshalb nur, was Außenstehende wirklich brauchen.
Das klassische Layout für Go-Apps hat sich um genau diese Grenzen herum etabliert: cmd/ für die Startpunkte der Binaries, internal/ für alles, was vor fremden Imports geschützt werden soll.
// taskd/ — das Layout, das dieses Modul weiter ausbaut
// taskd/
// ├── cmd/
// │ ├── taskd/main.go // Binary 1: der HTTP-Server
// │ └── taskctl/main.go // Binary 2: das CLI-Werkzeug
// ├── internal/
// │ ├── store/store.go // package store
// │ ├── api/handlers.go // package api
// │ └── mailer/mailer.go // package mailer
// ├── go.mod
// └── go.sum
//
// package store — internal/store/store.go
package store
// Task ist exportiert: für cmd/ und alle internal/-Packages sichtbar.
type Task struct {
ID int
Title string
Done bool
}
// next ist unexportiert: Implementation, kein Teil der API.
var next = 0
func New() *Store { return &Store{tasks: map[int]Task{}} }
Das Besondere an internal/: Die Sichtbarkeitsregel liegt nicht in der Disziplin, sondern im Toolchain. Code unter internal/ kann nur von Code importiert werden, der im Verzeichnisbaum über dem internal-Ordner liegt — im obigen Fall also vom Modul github.com/acme/taskd selbst. Ein fremdes Modul bekommt eine harte Compiler-Meldung, keinen Styleguide-Hinweis:
// Terminal: ein FREMDES Modul versucht den Import
// $ cd ~/git/reporting && go get github.com/acme/taskd && go build ./...
// → package github.com/acme/taskd/internal/store is not in std
// → use of internal package github.com/acme/taskd/internal/store not allowed
//
// Terminal: innerhalb des eigenen Moduls ist alles erlaubt
// $ cd ~/git/taskd && go build ./...
// → (keine Ausgabe — cmd/taskd darf internal/store importieren)
Für die API-Design-Frage des Reporting-Teams lautet die Antwort deshalb: Entweder du exportierst bewusst ein kleines, stabiles Paket außerhalb von internal/ (etwa pkg/… oder ein eigenes Modul — dazu in Lektion 55), oder das Reporting-Team bekommt eine Schnittstelle, die es selbst definiert.
Interfaces gehören zum Consumer
Der zweite Baustein des API-Designs ist eine Go-Eigenheit, die Neulinge aus Java und C# häufig irritiert: Interfaces werden nicht beim Anbieter definiert, sondern beim Consumer — dort, wo die Funktionalität gebraucht wird. Die API braucht zum Anlegen neuer Tasks eine Benachrichtigung, und genau das, nicht mehr, steht in ihrem Interface. Der Mailer erfüllt es später implizit, ohne etwas davon zu wissen.
// internal/api/handlers.go
package api
import "github.com/acme/taskd/internal/store"
// Notifier definiert der Consumer: genau die Methode, die die
// API braucht — nicht die vollständige Oberfläche des Mailers.
type Notifier interface {
TaskCreated(t store.Task) error
}
// Handler bekommt das Interface injiziert (Lektion 54 vertieft das).
type Handler struct {
store *store.Store
notifier Notifier
}
func NewHandler(s *store.Store, n Notifier) *Handler {
return &Handler{store: s, notifier: n}
}
// internal/mailer/mailer.go
package mailer
// Mailer kennt api NICHT — und muss es auch nicht:
// TaskCreated erfüllt api.Notifier automatisch.
type Mailer struct{ smtpAddr string }
func New(smtpAddr string) *Mailer { return &Mailer{smtpAddr: smtpAddr} }
func (m *Mailer) TaskCreated(t store.Task) error {
return m.send(t.Title + " — angelegt")
}
// cmd/taskd/main.go — die Klammer, die beide Seiten kennt
// var _ api.Notifier = (*mailer.Mailer)(nil) // Compile-Zeit-Check
Diese Richtung — Interface beim Consumer, Implementation beim Anbieter, verbunden erst in main — ist die entscheidende Vorübung für die Architektur der nächsten Lektion. Sie bricht auch den Import-Zyklus sauber: api importiert store, mailer importiert store, und niemand importiert api.
⚠ Häufiger Fehler: Auf einen Import-Zyklus mit dem Reflex »ich ziehe alle Typen in ein gemeinsames
models- odercommon-Package« zu reagieren. Das löst den Zyklus zwar mechanisch, aber das God-Package importiert bald alles und wird von allem importiert — jede Änderung an irgendeinem Typ berührt das ganze Projekt, und die ursprünglichen Package-Grenzen sind Papier. Der saubere Weg: den Zyklus an der Stelle brechen, wo er entsteht — die Typen, die zwei Seiten wirklich teilen, in das eine Package legen, das die Domäne beschreibt (hierstore), und beidseitige Abhängigkeiten über ein Consumer-Interface umlenken.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Clean/Hexagonal Architecture: Ports & Adapters
Lektion 53 von 100
Der Store soll wechseln können
Der Vorstand will die Tasks in Postgres statt im Speicher — und fragt nebenbei, ob sich die Geschäftsregel »wird ein Task erledigt, informiert das System das Team« testen ließe, ohne jedes Mal eine Datenbank zu starten. Beides ist dieselbe Frage: Wie sehr hängt die Geschäftslogik an ihrer Umgebung? Genau das adressiert die Hexagonale Architektur (Ports & Adapters), wie sie die Architekturstile-Reihe im Detail durchleuchtet: Die Domäne steht im Zentrum und definiert Ports — Schnittstellen für alles, was sie von außen braucht. Die Außenwelt wird als Adapter angedockt, der einen Port implementiert. Die Abhängigkeitsrichtung zeigt dabei immer nach innen: HTTP kennt die Domäne, die Domäne kennt kein HTTP.
Go macht dieses Muster unverhältnismäßig billig — dank impliziter Interface-Erfüllung und Consumer-Interfaces aus Lektion 52 ist ein Port einfach ein Interface im Domänen-Paket. Kein DI-Container, keine Framework-Konventionen, nur gewöhnliche Go-Typen.
Port = Interface in der Domäne, Adapter = Typ daneben
Der Port beschreibt, was die Domäne braucht — in ihrer Sprache, mit ihren Typen und ihren Fehlern (etwa task.ErrNotFound). Der Adapter übersetzt: Er kennt die Domäne und mappt sql.ErrNoRows auf task.ErrNotFound. Genauso umgekehrt am Treiber-Port: Der HTTP-Adapter ruft den Service auf. Die Domäne selbst importiert weder net/http noch database/sql — und genau dieser Mangel macht sie in Millisekunden testbar.
Zuerst die Domäne mit ihren Ports:
// internal/task/domain.go
package task
import (
"context"
"errors"
"time"
)
var ErrNotFound = errors.New("task nicht gefunden")
// Store ist der Port zur Persistenz — definiert von der Domäne,
// in der Sprache der Domäne. Er sagt nichts über SQL oder Dateien.
type Store interface {
Save(ctx context.Context, t Task) error
ByID(ctx context.Context, id int) (Task, error)
}
// Notifier ist der Port zur Außenwelt (E-Mail, Chat, was auch immer).
type Notifier interface {
TaskCompleted(t Task) error
}
// Service enthält die Geschäftsregeln und kennt nur Ports.
type Service struct {
store Store
notifier Notifier
}
func NewService(store Store, notifier Notifier) *Service {
return &Service{store: store, notifier: notifier}
}
func (s *Service) Complete(ctx context.Context, id int) error {
t, err := s.store.ByID(ctx, id)
if err != nil {
return err
}
t.Done = true
t.CompletedAt = time.Now()
if err := s.store.Save(ctx, t); err != nil {
return err
}
return s.notifier.TaskCompleted(t)
}
Und ein Adapter, der diesen Port erfüllt, ohne dass die Domäne davon erfährt:
// internal/adapters/postgres/store.go
package postgres
import (
"context"
"database/sql"
"errors"
"github.com/acme/taskd/internal/task"
)
// Store implementiert task.Store implizit. Er importiert die Domäne —
// nie umgekehrt. Genau das IST die Abhängigkeitsrichtung nach innen.
type Store struct{ db *sql.DB }
func NewStore(db *sql.DB) *Store { return &Store{db: db} }
func (s *Store) ByID(ctx context.Context, id int) (task.Task, error) {
row := s.db.QueryRowContext(ctx,
"SELECT id, title, done FROM tasks WHERE id = $1", id)
var t task.Task
if err := row.Scan(&t.ID, &t.Title, &t.Done); err != nil {
if errors.Is(err, sql.ErrNoRows) {
return task.Task{}, task.ErrNotFound // übersetzt für die Domäne
}
return task.Task{}, err
}
return t, nil
}
func (s *Store) Save(ctx context.Context, t task.Task) error {
_, err := s.db.ExecContext(ctx,
"UPDATE tasks SET title = $1, done = $2 WHERE id = $3",
t.Title, t.Done, t.ID)
return err
}
Der Lohn für diese Trennung zeigt sich im Test: Die Geschäftsregel läuft gegen einen In-Memory-Adapter, der denselben Port erfüllt — ohne Datenbank, ohne Netz, in Mikrosekunden:
// internal/task/service_test.go
package task_test
import (
"context"
"testing"
"github.com/acme/taskd/internal/task"
)
type memStore struct{ tasks map[int]task.Task }
func (m *memStore) Save(_ context.Context, t task.Task) error {
m.tasks[t.ID] = t
return nil
}
func (m *memStore) ByID(_ context.Context, id int) (task.Task, error) {
t, ok := m.tasks[id]
if !ok {
return task.Task{}, task.ErrNotFound
}
return t, nil
}
type recordingNotifier struct{ called int }
func (r *recordingNotifier) TaskCompleted(task.Task) error { r.called++; return nil }
func TestCompleteNotifiesTeam(t *testing.T) {
store := &memStore{tasks: map[int]task.Task{1: {ID: 1, Title: "On-Call prüfen"}}}
notify := &recordingNotifier{}
svc := task.NewService(store, notify)
if err := svc.Complete(context.Background(), 1); err != nil {
t.Fatalf("Complete: %v", err)
}
if notify.called != 1 {
t.Fatalf("Notifier %d-mal aufgerufen, erwartet 1", notify.called)
}
}
// Terminal: go test ./internal/task/ -run Complete -v
// → === RUN TestCompleteNotifiesTeam
// → --- PASS: TestCompleteNotifiesTeam (0.00s)
// → PASS
Ein ehrlicher Rahmen: Ports & Adapters zahlt sich dort ein, wo Geschäftsregeln existieren, die vom Speichermedium unabhängig sind. Für pure CRUD-Endpunkte ohne Regelwerk ist ein dünner Handler über database/sql legitimer Alltag — jede Architektur, die dort Interfaces erzwingt, erzeugt Schreibarbeit ohne Ertrag. Das Muster dann einsetzen, wenn der zweite Adapter (Tests zählen!) oder der zweite Treiber absehbar ist.
⚠ Häufiger Fehler: Das Interface beim Adapter statt beim Consumer zu definieren — also
type Store interfaceinspostgres-Paket zu legen und die Domäne das importieren zu lassen. Damit dreht sich die Abhängigkeitsrichtung um: Die Domäne hängt am Datenbank-Paket, Postgres-Typen sickern in die Geschäftslogik, und der Unit-Test braucht plötzlich einen DB-Treiber, nur um den Service zu bauen. Interfaces gehören zu dem Code, der sie aufruft — in der Domäne, mit Domänen-Typen und Domänen-Fehlern. Der Adapter importiert die Domäne, niemals umgekehrt.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Dependency Injection: Constructor-Injection, Wire & Fx
Lektion 54 von 100
Ein Objektgraph von Hand — und wann er zu lang wird
Nach Lektion 53 kennt der Service nur Ports. Aber irgendjemand muss den realen Objektgraphen bauen: Der Service braucht den Postgres-Store und den Mailer, der Store braucht die sql.DB, der Handler braucht den Service, der Server braucht den Handler. In Go ist die Antwort auf »wie injiziert man das?« zuerst enttäuschend unspektakulär: als Konstruktor-Parameter, zusammengebaut in main. Diese Constructor-Injection ist das dominierende Muster im Go-Ökosystem — und für die allermeisten Projekte die einzige, die je gebraucht wird.
Warum das so ist: Der Objektgraph steht genau an einem Ort, ist gewöhnlicher Go-Code, prüft sich zur Compile-Zeit und lässt sich im Test Zeile für Zeile mit Fakes nachbauen. Frameworks wie github.com/google/wire (Compile-Zeit-Codegenerierung) oder go.uber.org/fx (Laufzeit-DI mit Lifecycle) kaufen Komfort für große Graphen — beide mit ehrlichen Vor- und Nachteilen, die wir gleich gegenprüfen.
DI ist ein Muster, kein Framework
Die Regel lautet: Abhängigkeiten wandern als Parameter in den Konstruktor; niemand reicht sie intern weiter über globale Variablen. main kennt alles, niemand sonst kennt main. Genau diese Einbahnstraße macht die Abhängigkeiten sichtbar: Siehst du im Konstruktor von Service einen *sql.DB stehen, weißt du sofort, dass Geschäftslogik und Datenbank gekoppelt sind — Lektion 53 wartet mit dem Gegenmittel.
Das Hand-Wiring für den Task-Service — übersichtlich, testbar, ohne eine Zeile Magie:
// cmd/taskd/main.go
package main
import (
"database/sql"
"log"
"net/http"
"time"
"github.com/acme/taskd/internal/adapters/mailer"
"github.com/acme/taskd/internal/adapters/postgres"
"github.com/acme/taskd/internal/api"
"github.com/acme/taskd/internal/task"
)
func main() {
db, err := sql.Open("postgres", mustEnv("DATABASE_URL"))
if err != nil {
log.Fatalf("db: %v", err)
}
defer db.Close()
// Der Objektgraph: Adapter erfüllen Ports (Lektion 53),
// jeder Konstruktor nimmt nur das, was er wirklich braucht.
store := postgres.NewStore(db)
notifier := mailer.New(mustEnv("SMTP_ADDR"))
svc := task.NewService(store, notifier)
srv := &http.Server{
Addr: ":8080",
Handler: api.NewHandler(svc),
ReadHeaderTimeout: 5 * time.Second, // Slowloris-Schutz (Modul 10)
}
log.Fatal(srv.ListenAndServe())
}
// Terminal: go run ./cmd/taskd
// → 2026/11/05 21:40:01 taskd lauscht auf :8080
//
// Und im Test wird derselbe Graph mit Fakes gebaut —
// Zeile für Zeile, ohne Container:
// svc := task.NewService(&fakeStore{}, &fakeNotifier{})
// → (Service läuft komplett ohne Datenbank)
Der Punkt ist nicht die Eleganz, sondern die Kanten: Jeder Pfeil im Graphen ist eine Zeile lesbarer Go-Code, die der Compiler prüft.
Wire: Codegenerierung zur Compile-Zeit (in Wartung)
Wenn der Graph auf zwei Dutzend Komponenten wächst, wird Hand-Wiring mühsam und ändert sich bei jedem Refactoring an fünf Stellen. Genau dafür wurde github.com/google/wire gebaut: Man beschreibt Provider-Sets, und das wire-CLI generiert den wire_gen.go-Quelltext — also exakt den Code, den man sonst von Hand geschrieben hätte. Wichtig und versionsehrlich: Google hat das Projekt im August 2025 archiviert (letzte Version v0.7.0), es wird nicht weiter entwickelt. Der generierte Code ist gewöhnliches Go und läuft unbegrenzt weiter — aber für ein neues Projekt sollte man wissen, dass es das Werkzeug nicht mehr tut.
//go:build wireinject
// +build wireinject
// wire.go — wird nur vom wire-Tool gelesen, nie vom Compiler gebaut
package main
import (
"github.com/google/wire"
"github.com/acme/taskd/internal/adapters/mailer"
"github.com/acme/taskd/internal/adapters/postgres"
"github.com/acme/taskd/internal/api"
"github.com/acme/taskd/internal/task"
)
var providers = wire.NewSet(
postgres.NewStore,
mailer.New,
task.NewService,
api.NewHandler,
)
func initHandler() (*api.Handler, error) {
wire.Build(providers)
return nil, nil // Platzhalter — wire ersetzt die Funktion komplett
}
// Terminal: wire
// → wire: github.com/acme/taskd/cmd/taskd: wrote /path/to/wire_gen.go
// → (wire_gen.go enthält das Hand-Wiring von oben, als normaler Go-Code)
Der Ausweg »wenn Wire eingestellt ist, lösche ich einfach wire.go und behalte wire_gen.go« ist real — viele Teams haben genau das getan.
Fx: Laufzeit-DI mit Lifecycle
Der konträre Ansatz ist go.uber.org/fx: ein aktives, gepflegtes Framework (auf Ubers eigenem dig-Container basierend), das Abhängigkeiten zur Laufzeit per Reflektion auflöst und Prozesse in modulare Anbieter zerlegt, inklusive Lifecycle-Hooks (OnStart, OnStop) für ordentliches An- und Abmelden von Hintergrundarbeit. Der Preis: Indirektion zur Laufzeit und Fehler, die der Container erst beim Start meldet, wo Hand-Code sie der Compiler sofort sieht.
// cmd/taskd-fx/main.go — dieselbe Anwendung als fx-App
package main
import (
"go.uber.org/fx"
"github.com/acme/taskd/internal/adapters/mailer"
"github.com/acme/taskd/internal/adapters/postgres"
"github.com/acme/taskd/internal/api"
)
func main() {
fx.New(
fx.Provide(
mustDB,
postgres.NewStore,
mailer.New,
task.NewService,
api.NewHandler,
),
fx.Invoke(api.Serve),
).Run()
}
// Terminal: go run ./cmd/taskd-fx
// → [Fx] PROVIDE *sql.DB := main.mustDB()
// → [Fx] PROVIDE *postgres.Store := postgres.NewStore()
// → [Fx] INVOKE api.Serve()
// → [Fx] RUNNING
Die Faustregel, mit der beide Frameworks fair bewertet sind: Erst Hand-Wiring — es verschwindet selten als Problem, bevor das Projekt groß ist. Wire lohnt sich für große, stabile Graphen, deren Code man gern eingecheckt sähe (trotz Archivierung bleibt die Datei gültig). Fx lohnt sich, wenn ohnehin modulare Prozesse mit Lifecycle-Verwaltung das Ziel sind — etwa in Mikroservice-Plattformen, die sowieso auf Ubers Werkzeugkasten setzen. Ein DI-Framework als Default-Startpunkt ist in Go kein allgemein akzeptierter Stil, sondern eine Kosten-Nutzen-Entscheidung.
⚠ Häufiger Fehler: DI über Paket-globale Singletons zu faken — ein
package storemitvar Default *Storeplusstore.Init(dsn)inmain, danach ruft jedes beliebige Packagestore.Defaultauf. Das sieht nach Bequemlichkeit aus und zahlt mit Testbarkeit: Die Abhängigkeiten sind aus den Signaturen verschwunden (nichts verrät mehr, wer den Store nutzt), Tests brauchen die globale Init in exakt richtiger Reihenfolge, und zwei Testfälle im selben Lauf konkurrieren um denselben globalen Zustand. Constructor-Injection ist die ganze Zeit die bessere Antwort: Abhängigkeit als Parameter, Zustand pro Test instanziiert, keine verdeckten Kanten im Graphen.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Projekt-Layout-Katalog: von Monolith bis Microservice
Lektion 55 von 100
Welches Layout für das nächste Repo?
Das Team startet das nächste Projekt, und die erste Pull-Request-Diskussion dreht sich nicht um Code, sondern um Ordner: Brauchen wir pkg/? Sind das jetzt schon Microservices? Sollte man von Anfang an mehrmodulig bauen? Statt einer dieser Glaubensfragen zu überlassen, dieser Katalog von klein nach groß — mit dem ehrlichen Hinweis, wo die Stufen enden.
Stufe 1 — das Ein-Package-Werkzeug: Ein CLI-Skript ist package main in einem Ordner. Fertig. cmd/-Struktur für zwei Dateien ist Zeremonie, kein Design.
Stufe 2 — der flache Standard (die Antwort auf die meisten Fragen): Ein Modul, cmd/ mit einem Ordner pro Binary, internal/ für den Rest, Packages entlang der Domäne geschnitten (Lektion 52), Ports und Adapter wo Geschäftsregeln es verdienen (Lektion 53). Diese Anatomie trägt Dienste mit sechs-stelligen Zeilenzahlen.
Bounded Contexts sind Package-Grenzen
Die Domänen-Frage aus der Domain-Driven-Design-Reihe — wo endet ein Bounded Context? — beantwortet sich in Go praktisch als Package-Frage: internal/task und internal/reporting sind getrennte Kontexte, wenn task nichts aus reporting importiert (und umgekehrt). Der Compiler kennt keine Bounded Contexts, aber er kennt Imports — erzwingt die Trennung also, wenn man sie als Import-Verbot mit einer kleinen Architektur-Definition vereinbart.
Stufe 3 — der modulare Monolith in voller Ausprägung:
// taskd/ — ein Binary, domänen-geschnittene Packages
// taskd/
// ├── cmd/taskd/main.go // der eine Startpunkt
// ├── internal/
// │ ├── task/ // Kontext »Aufgaben«: Domäne + Ports
// │ │ ├── domain.go
// │ │ └── service_test.go
// │ ├── reporting/ // Kontext »Berichte«
// │ │ └── service.go
// │ ├── adapters/
// │ │ ├── postgres/ // erfüllen die Ports aus internal/task
// │ │ └── mailer/
// │ └── api/ // HTTP-Adapter (Modul 10)
// ├── go.mod
// └── go.sum
// Terminal: go list ./... — die Package-Struktur sichtbar machen
// $ go list ./...
// → github.com/acme/taskd/cmd/taskd
// → github.com/acme/taskd/internal/adapters/mailer
// → github.com/acme/taskd/internal/adapters/postgres
// → github.com/acme/taskd/internal/api
// → github.com/acme/taskd/internal/reporting
// → github.com/acme/taskd/internal/task
Stufe 4 — der Multi-Modul-Monorepo: Wenn Teile des Codes eigenständige Versionszyklen oder eigene Consumer bekommen (etwa eine von anderen Teams importierte Client-Bibliothek), bekommt er eine eigene go.mod. Der Workspace verbindet sie lokal:
// repo/ — zwei Module, ein go.work (Workspace seit Go 1.18)
// repo/
// ├── go.work
// ├── taskd/ // go.mod: module github.com/acme/taskd
// └── taskctl/ // go.mod: module github.com/acme/taskctl
// go.work
go 1.25
use (
./taskd
./taskctl
)
// Terminal: im Workspace-Root bauen — taskctl nutzt taskd lokal
// aus dem Checkout, ganz ohne replace-Zeilen in der go.mod
// $ cd repo && go build ./...
// → (keine Ausgabe — beide Module bauen aus lokalem Quellstand)
Stufe 5 — Microservices: Getrennte Deployments, getrennte Repos oder Module, Kommunikation übers Netz. Diese Stufe ist ein Organisations- und Betriebsentscheid, kein Architekturverdienst: Sie zahlt auf Teamgrenzen (wer deployet was, wann, unabhängig), nicht auf Zeilenzahl. Der Preis ist real — Netzwerkfehler werden Alltag, Verträge müssen versioniert werden, verteiltes Tracing gehört zur Grundausstattung (Modul 13). Und die Split-Richtung nach Bounded Contexts vertikal (Aufgaben/Berichte), niemals horizontal nach Layern (»ein Service nur für die Datenbank«), sonst entsteht ein verteilter Monolith: die Kopplung von vorher, jetzt übers Netz.
Woher kommt eigentlich die oft kopierte Repo-Struktur mit pkg/, apis/, deployments/? Sie geht auf das verbreitete golang-standards/project-layout-Repo zurück — eine Community-Sammlung, keine offizielle Go-Empfehlung. pkg/ ist nur sinnvoll, wenn tatsächlich fremde Projekte Code aus diesem Pfad importieren sollen; leere Verzeichnisse aus Glaubensgründen erzeugen nur Navigationslärm.
⚠ Häufiger Fehler: Ein neues Projekt gleich als Mikroservice-Föderation aufzusetzen, weil »skalieren« im Raum steht — drei Dienste, ein Gateway, eine Message-Queue, und alle drei Deployment-Pipelines fahren gegen dieselbe Postgres-Instanz. Das Ergebnis ist der verteilte Monolith: die Kopplung eines Monolithen plus Netzwerklatenz, Verteiltes-Tracing-Pflicht und Versionierungs-Overhead obendrauf, ohne einen der Benefits. Der souveräne Weg ist Stufe 3: ein modulärer Monolith mit sauber geschnittenen Kontexten — wenn später ein echter Grund für eine Abspaltung entsteht (eigene Skalierung, eigenes Team, eigener Release-Zyklus), löst man genau diesen Kontext heraus, und die Package-Grenzen der Lektionen 52 und 53 sind bereits die Service-Grenzen.
Modul 11 im Rückblick
Damit steht das Fundament: Projekte, die mit dem Team mitwachsen, statt an ihrem Ordner-Skelett zu scheitern. Modul 12 baut darauf die Framework-Welt auf — jetzt weißt du, warum die Standardbibliothek-Route aus Modul 10 so attraktiv bleibt und wo ein Framework wirklich Grenzen sprengt.
Wochen-Check: Beherrschst du diese Punkte?
- Kannst du erklären, welche Version MVS wählt — und warum
go.sumkeine Sperrdatei ist? - Schneidest du Packages nach Domäne statt nach Layer, mit
internal/als Compiler-erzwungener Grenze? - Definierst du Ports in der Domäne und Adapter daneben — mit Abhängigkeiten, die nach innen zeigen?
- Weißt du, wann Hand-Wiring reicht und was Wire (archiviert) und Fx (aktiv) jeweils kaufen?
- Kannst du für ein neues Projekt die richtige Layout-Stufe wählen — und den verteilten Monolithen an seinem Duft erkennen?
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: