Go-Module: go.mod, go.sum und das Hauptversions-Suffix

Worum es geht

Die Go Modules Reference definiert ein Modul als eine Sammlung gemeinsam veröffentlichter Pakete, mit einer go.mod-Datei an der Wurzel, die den Modulpfad benennt, die go-Direktive (die Mindest-Go-Version, seit Go 1.21 durchgesetzt statt nur empfohlen), require-Zeilen sowie optionale replace-, exclude-, retract- und toolchain-Direktiven. Versionen folgen Semantic Versioning 2.0.0 mit einem v-Präfix. Die Referenz beschreibt Minimal Version Selection: Der go-Befehl durchläuft den Anforderungsgraphen und baut mit der höchsten Version, in der jedes Modul verlangt wird; er wählt nie eine neuere Version nur, weil sie existiert, weshalb sich die Build-Liste allein aus go.mod reproduzieren lässt. go.sum hält kryptografische Hashes jedes verwendeten Moduls fest, geprüft beim Download und standardmässig gegen die öffentliche Prüfsummendatenbank sum.golang.org.

Die Regel, über die Neulinge stolpern, ist das Hauptversions-Suffix. Die Referenz nennt die Import-Kompatibilitätsregel (haben ein altes und ein neues Paket denselben Importpfad, muss das neue Paket abwärtskompatibel zum alten sein) und verlangt deshalb, dass Hauptversion 2 und höher das Suffix im Modulpfad tragen: example.com/lib/v2. Die Versionen v0 und v1 tragen kein Suffix; v0 gibt kein Kompatibilitätsversprechen. Tags ab v2 ohne go.mod-Datei erscheinen mit +incompatible.

Warum es wichtig ist

pip und npm bevorzugen die neueste erlaubte Version und brauchen für Reproduzierbarkeit eine Lock- oder Pin-Datei; Go löst auf die niedrigste Version auf, die alle Anforderungen erfüllt, und berechnet bei jedem Befehl dieselbe Liste neu. Da lib und lib/v2 unterschiedliche Importpfade sind, können beide im selben Build koexistieren, und ein Upgrade einer Hauptversion ist ein Suchen-und-Ersetzen von Imports statt eines Resolver-Konflikts.

So wird es angewendet

• Nach dem Ändern von Imports go mod tidy ausführen; es fügt fehlende Anforderungen hinzu, entfernt ungenutzte und aktualisiert go.sum; beide Dateien committen.
• Eine Abhängigkeit mit go get example.com/lib@v1.4.0 aktualisieren; zu einer neuen Hauptversion wechseln, indem der Pfad mit Suffix importiert wird.
• Beim Veröffentlichen von v2 des eigenen Moduls die module-Zeile vor dem Taggen auf /v2 enden lassen; der Blogbeitrag zu v2-Modulen empfiehlt ein Hauptversions-Unterverzeichnis (v2/go.mod) gegenüber getrennten Branches.
• replace nur im Hauptmodul für die lokale Entwicklung verwenden; die Referenz besagt, dass es in den go.mod-Dateien anderer Module ignoriert wird.
• retract dem Löschen eines fehlerhaften Tags vorziehen; der Tag bleibt in der Prüfsummendatenbank bestehen.

Stolpersteine

Wird v2.0.0 an ein Modul getaggt, dessen Pfad das Suffix nicht trägt, weist der go-Befehl die Version zurück. Die go-Direktive ist seit Go 1.21 eine harte Anforderung: Eine ältere als die deklarierte Toolchain wechselt zu einer neueren oder verweigert den Build, statt nur zu warnen. go.sum ist keine Lock-Datei: Es verifiziert, was Minimal Version Selection ausgewählt hat.