Projektstruktur und go.mod

Was ein Go-Projekt mindestens braucht

Das absolut kleinste lauffähige Go-Programm besteht aus einer einzigen Datei mit package main und einer Funktion main:

package main

import "fmt"

func main() {
    fmt.Println("Hallo")
}

Hallo

Aufruf mit go run hello.go — fertig. Kein go.mod, kein Layout, kein Build-System. Sobald du jedoch Dependencies brauchst, eigene Pakete in Unterordner legen willst oder das Projekt auschecken und woanders bauen sollst, kommt die Modul-Schicht ins Spiel.

Ein Projekt wird zum Modul, sobald in seiner Wurzel ein go.mod liegt. Das wird mit einem Befehl erzeugt:

go mod init github.com/mibeon/example

Damit hast du zwei Dateien — die .go-Quelle und ein go.mod — und kannst Dependencies hinzufügen, das Projekt versionieren und es überall reproduzierbar bauen. Das ist der Standardfall. Ein Projekt ohne go.mod ist heute nur noch für Throwaway-Skripte sinnvoll.

Das go.mod-File im Detail

go.mod ist die zentrale Konfiguration eines Moduls. Sie ist menschenlesbar, zeilenbasiert und wird normalerweise vom go-Tool gepflegt — Hand-Edits sind aber jederzeit erlaubt.

module github.com/mibeon/example

go 1.22

toolchain go1.23.0

require (
    github.com/google/uuid v1.6.0
    golang.org/x/text v0.16.0 // indirect
)

replace github.com/mibeon/internal-lib => ../internal-lib

exclude github.com/some/dep v1.4.0

retract v0.1.0 // versehentlich veröffentlicht

Die wichtigsten Direktiven im Überblick:

replace und exclude greifen nur, wenn das Modul selbst das Haupt-Modul ist — Konsumenten ignorieren diese Direktiven. Das ist eine bewusste Designentscheidung: Sicherheits-Workarounds eines Forks sollen sich nicht stillschweigend auf alle Nutzer ausbreiten.

go.sum — Integritäts-Hashes für Reproducible Builds

Neben go.mod legt das go-Tool eine zweite Datei an: go.sum. Sie enthält kryptografische Hashes aller Module, die direkt oder transitiv im Build vorkommen.

github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

Pro Modul-Version stehen typischerweise zwei Zeilen: ein Hash über den ZIP-Inhalt und ein Hash über die go.mod der Dependency. Beim nächsten Build prüft go diese Hashes gegen das, was aus dem Cache oder vom Proxy kommt — und bricht ab, wenn sich auch nur ein Byte geändert hat.

go.sum ist nicht optional und gehört in die Versionskontrolle. Verloren oder bewusst gelöscht? Dann erzeugt go mod tidy die Datei aus den aktuellen Modul-Inhalten neu — was beim ersten Mal eine Vertrauensentscheidung ist (was steht im Proxy?), danach aber bombenfest reproduziert.

Modul-Pfad und Import-Pfad

Der Modul-Pfad in der ersten Zeile von go.mod ist mehr als Metadaten — er ist das Präfix für alle Imports innerhalb des Moduls. Beispiel: module github.com/mibeon/example. Eine Datei in internal/auth/auth.go liegt dann unter dem Import-Pfad:

package main

import (
    "github.com/mibeon/example/internal/auth"
)

func main() {
    _ = auth.Token{}
}

Konvention: Der Modul-Pfad spiegelt den Repository-Pfad. Das ermöglicht go get github.com/mibeon/example ohne weitere Konfiguration — der go-Befehl klont das Repo dann selbstständig.

Pflicht ist das aber nicht: Solange dein Modul nicht extern published wird, darf der Modul-Pfad alles sein, was syntaktisch wie ein Pfad aussieht — example.com/foo, mycompany/internal/tool, sogar playground/test. Erst beim Veröffentlichen über go install oder go get wird ein echter, auflösbarer Pfad nötig.

Standard-Projektlayout

Go hat — anders als z. B. Java oder Rust — kein vom Tool erzwungenes Projektlayout. Die offizielle Layout-Doku und die Community haben sich aber auf eine Handvoll Patterns geeinigt:

Eine typische Server-Codebase mit Multi-Binary-Setup sieht so aus:

myservice/
├── go.mod
├── go.sum
├── cmd/
│   ├── api-server/
│   │   └── main.go
│   └── migrate/
│       └── main.go
├── internal/
│   ├── auth/
│   ├── store/
│   └── handlers/
├── api/
│   └── openapi.yaml
└── docs/
    └── architecture.md

Die Faustregel: klein anfangen, flach bleiben. Ein Single-Binary-Tool braucht weder cmd/ noch internal/ noch pkg/ — eine main.go plus ein paar Hilfs-Dateien im Root reicht. Erst wenn die Datei-Anzahl unübersichtlich wird oder ein zweites Binary dazukommt, lohnt sich der Layout-Aufwand.

Spezial-Ordner: internal/

Der internal/-Ordner ist die einzige Layout-Konvention, die der Go-Compiler selbst durchsetzt. Die Regel ist simpel und harmlos zu beschreiben — und ungeheuer wirksam:

Ein Paket unter .../internal/... ist nur importierbar von Code, der unter dem gleichen übergeordneten Verzeichnis liegt wie das internal/ selbst.

Konkret: Liegt internal/auth/ direkt unter github.com/mibeon/example/, darf nur Code innerhalb von github.com/mibeon/example/... dieses Paket importieren. Jeder andere Modul-Konsument bekommt einen Compile-Fehler:

go build ./...

package github.com/foo/other: use of internal package
github.com/mibeon/example/internal/auth not allowed

Damit kannst du bewusst öffentlichen API-Oberflächen definieren: Alles in internal/ darfst du jederzeit umbenennen, refactoren oder entfernen, ohne Konsumenten zu brechen — der Compiler garantiert, dass es niemand importieren kann. Das ist ein extrem wertvolles Werkzeug für API-Hygiene und in vielen Codebases der Default für alles, was nicht explizit als Library exportiert werden soll.

Vendor-Ordner: vendor/ und go mod vendor

Standardmäßig holt sich Go Dependencies aus dem Module-Cache ($GOPATH/pkg/mod) oder über einen Module-Proxy (proxy.golang.org). Der Befehl go mod vendor legt stattdessen einen lokalen Snapshot aller Dependencies in den Ordner vendor/ im Modul-Root:

go mod vendor

Sobald vendor/modules.txt existiert (und go ≥ 1.14 in go.mod steht), aktiviert Go automatisch Vendor-Modus: Dependencies werden direkt aus vendor/ gelesen, der Proxy wird nicht kontaktiert.

Wann sinnvoll:

• Air-gapped Build-Umgebungen — der Build läuft ohne Internet.
• Strikte Compliance/Audit-Anforderungen — alle Dependencies liegen direkt im Repo, vollständig reviewbar.
• Schutz gegen verschwundene Module — selbst wenn ein Upstream-Repo offline geht, baut dein Code weiter.

Wann eher nicht:

• Bei normalen Open-Source-Projekten — der Module-Proxy von Go ist hochverfügbar, und ein eingecheckter vendor/-Ordner bläht das Repo enorm auf.
• Bei privaten Modulen mit GOPRIVATE und gutem Cache — meist überflüssig.

Multi-Module-Projekte mit go.work

Seit Go 1.18 gibt es Workspaces über die Datei go.work. Ein Workspace gruppiert mehrere lokale Module so, dass sie sich gegenseitig sehen — ohne dass dafür replace-Direktiven in den einzelnen go.mod-Dateien nötig sind.

cd ~/code
go work init ./api ./shared ./worker

Erzeugt:

go 1.22

use (
    ./api
    ./shared
    ./worker
)

Der Effekt: Wenn api einen Import auf github.com/mibeon/shared enthält, nimmt der go-Befehl die lokale Version aus ./shared statt einer veröffentlichten Version aus dem Modul-Proxy.

Der entscheidende Vorteil gegenüber replace: go.work wird nicht eingecheckt. Es ist eine persönliche Entwickler-Konfiguration für dein lokales Setup — die produktive go.mod der Module bleibt sauber und versionsstabil. Klassischer Use-Case: Du arbeitest gleichzeitig an einer Library und an einem Service, der diese Library nutzt, willst aber keinen replace-Eintrag committen, der nur auf deiner Maschine funktioniert.

Beispielprojekt: realistische Struktur einer kleinen Web-App

Eine kleine Web-App mit API-Server und Hintergrund-Worker, sauber strukturiert mit cmd/ und internal/:

mibeon-shop/
├── go.mod
├── go.sum
├── README.md
├── cmd/
│   ├── shop-api/
│   │   └── main.go          # HTTP-Server-Eintrittspunkt
│   └── shop-worker/
│       └── main.go          # Background-Job-Eintrittspunkt
├── internal/
│   ├── config/
│   │   └── config.go        # Env-Vars, Defaults
│   ├── db/
│   │   ├── postgres.go
│   │   └── migrations/
│   ├── http/
│   │   ├── router.go
│   │   ├── middleware.go
│   │   └── handlers/
│   │       ├── checkout.go
│   │       └── catalog.go
│   ├── domain/
│   │   ├── product.go
│   │   └── order.go
│   └── worker/
│       └── jobs.go
├── api/
│   └── openapi.yaml
└── deploy/
    ├── Dockerfile.api
    └── Dockerfile.worker

Charakteristika:

• Zwei Binaries in cmd/ — shop-api und shop-worker teilen sich denselben Domain-Code.
• Geteilter Code unter internal/ — domain, db, config werden von beiden Binaries genutzt, sind aber für externe Module komplett unsichtbar.
• Subdomain-Pakete (internal/http/handlers/) — Handler-Logik kapselt sich pro Use-Case in eigenen Dateien.
• Keine pkg/-Ordner — diese Codebase exportiert keine Library-API, also gibt es keinen Grund dafür.
• Build-Artefakte außerhalb von Go: Dockerfiles liegen unter deploy/, ähnlich für api/ mit dem OpenAPI-Schema.

Gebaut wird mit go build ./cmd/shop-api, go test ./... läuft über alle Pakete des Moduls. So einfach.

Weiterführende Ressourcen

Externe Quellen

• Go Modules Reference
• Managing dependencies – Go Doku
• go.mod file reference
• Project layout (golang-standards)
• Workspaces – Go Blog

Verwandte Artikel

• Was ist Go?
• Setup und Installation
• Erstes Programm
• Pakete und Imports
• Module & Workspaces (Stub-Übersicht)