Go Modules e Gestione Dipendenze — Versioning Semantico, Vendor e CI/CD per Codice che Non Si Rompe

Hai mai speso ore a capire perché il tuo progetto Go non compila su un altro ambiente? O peggio, in produzione? Succede quando le dipendenze vivono per conto loro, il go.mod si allarga e il versioning diventa un terno al lotto. Noi di Meteora Web ci siamo passati — e abbiamo costruito la nostra guida su Go modules partendo dal problema reale: gestire le dipendenze in modo deterministico, senza sorprese.

Come funziona il versioning semantico nei Go modules e perché ti salva la produzione?

Un Go module è un insieme di package con un file go.mod alla radice. Quel file dichiara il modulo stesso e le sue dipendenze esterne, ciascuna con una versione. Go adotta il semantic versioning (semver): vMAJOR.MINOR.PATCH. Se rompi la retrocompatibilità, devi aumentare la major. Se aggiungi funzionalità in modo compatibile, aumenti la minor. Se correggi bug, aumenti il patch.

Perché è importante? Perché Go usa il semver per risolvere i conflitti. Quando due dipendenze richiedono versioni diverse dello stesso modulo, Go cerca la versione minima compatibile (Minimal Version Selection). Questo significa che non ti ritrovi mai con due copie della stessa libreria — a differenza di Node.js o Python. Ed è una manna dal cielo quando gestisci decine di microservizi.

Esempio pratico: aggiungere una dipendenza

go get github.com/gorilla/mux@v1.8.0

Questo aggiorna il go.mod e scarica il modulo. Il file go.sum registra gli hash per garantire l'integrità. Se qualcuno modifica il repository remoto, il build fallisce — esattamente come dovrebbe.

Errore comune: usare go get -u senza specificare una versione. L'ultima versione potrebbe rompere il tuo codice. Noi lo abbiamo visto nei progetti che ereditiamo: dipendenze aggiornate automaticamente che mandano in crash l’API. Il consiglio: specifica sempre la versione minima di cui hai bisogno, poi testa prima di aggiornare.

Azione immediata: controlla il tuo go.mod. Ogni dipendenza ha una versione esatta? Se vedi v0.0.0-20210101... (pseudo-versione) significa che stai puntando a un commit senza tag — rischioso. Programma un go get con una versione stabile.

Quali sono le differenze tra go mod vendor e go mod download e quando usarli in CI/CD?

Due strategie per rendere il build deterministico: vendor e download. Con go mod vendor copi il codice sorgente di tutte le dipendenze dentro la cartella vendor del tuo progetto. Con go mod download le scarichi nella cache globale di Go.

Noi, di Meteora Web, usiamo vendor nei progetti che devono compilare in ambienti offline o con restrizioni di rete. Ma attenzione: il vendor pesa e va in git. Per microservizi in CI/CD su server cloud, preferiamo go mod download e teniamo la cache come layer di build per velocizzare i deploy. In Docker, copriamo prima il go.sum e go.mod, eseguiamo go mod download, poi copiamo il resto del codice. Così la cache delle dipendenze viene ricostruita solo quando cambia go.sum.

Dockerfile efficiente

FROM golang:1.22 AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o main .

Checklist per la scelta:

• Ambiente offline o con firewall? Usa vendor e committa la cartella.
• CI/CD con cache layer? Usa download e sfrutta il caching di Docker.
• Team distribuito e vuoi garantire build identici su ogni macchina? Vendor è più sicuro ma ingrossa il repository.

Noi vediamo spesso aziende che committano vendor e poi lo ignorano: lo escludono dal .gitignore ma non aggiornano mai. Se lo usi, tienilo allineato con go mod tidy e go mod vendor a ogni modifica.

Come gestire dipendenze indirette e conflitti di versione nei Go modules?

Le dipendenze indirette sono quelle che non importi direttamente, ma che servono alle tue dipendenze dirette. Go le aggiunge automaticamente al go.mod quando esegui go mod tidy. Ma qui possono nascere conflitti: una dipendenza A richiede la versione 1.0 del modulo X, la dipendenza B richiede 2.0. Go applica la Minimal Version Selection (MVS): sceglie la versione più alta tra quelle richieste che soddisfi tutti i vincoli semver. Attenzione: se la major è diversa, Go tratta v1 e v2 come moduli diversi (grazie al suffisso /v2 nel path). Quindi non c'è conflitto reale — ma se entrambi i moduli sono compatibili, puoi finire con una versione che non esiste. In pratica succede raramente.

Il problema vero è quando hai un overwrite forzato con replace nel go.mod. Usalo solo per sviluppo locale o per patch temporanee. Non committare replace in produzione se non sei sicuro.

replace github.com/old/pkg => github.com/forked/pkg v1.0.0

Se devi escludere una versione specifica, usa exclude. Ma la soluzione migliore è aggiornare le dipendenze dirette a versioni che condividono lo stesso modulo.

Azione immediata: esegui go mod graph per vedere l'albero delle dipendenze. Identifica i rami con versioni diverse dello stesso modulo. Quindi valuta se fare un upgrade delle tue dipendenze dirette.

Go modules in CI/CD e container: errori che costano tempo (e soldi)

Il build in CI deve essere riproducibile. Una volta che il go.mod e go.sum sono in repository, ogni checkout dovrebbe produrre lo stesso binario. Ma se la CI non ha accesso a internet (per policy di sicurezza), devi usare vendor. Se invece ha accesso, usa download ma attento alla cache: noi abbiamo visto pipeline che ogni volta scaricavano tutto perché il layer non era ottimizzato. Risultato: build da 5 minuti invece di 30 secondi.

Un altro errore: non bloccare le versioni delle dipendenze con go mod tidy dopo ogni modifica. Il comando pulisce le dipendenze inutilizzate e aggiorna il go.sum. Fallo sempre prima di committare.

Comando salvavita

go mod tidy -v

Il flag -v mostra cosa viene rimosso o aggiunto. Tecnicamente lo eseguiamo in una fase di pre-commit hook o nella pipeline CI.

Checklist per CI/CD robusto:

• Usa un'immagine base di Go con tag esatto (es. golang:1.22-bookworm), non latest.
• Aggiungi go mod verify nella pipeline per controllare l'integrità dei moduli.
• Se usi vendor, esegui go mod vendor e committa le modifiche insieme al codice.
• Evita go get -u in automatico — gestisci gli aggiornamenti manualmente con test.

Cosa fare adesso per non avere più sorprese con le dipendenze Go

1. Controlla il tuo go.mod oggi. Ogni dipendenza ha una versione semver? Se ci sono pseudo-versioni, pianifica un aggiornamento a un tag stabile.
2. Decidi la strategia: vendor o download. In base al tuo ambiente (offline, CI, Docker), scegli e automatizza.
3. Introduci go mod tidy && go mod verify nella tua pre-commit hook o CI. Non far passare codice con dipendenze sporche.
4. Ottimizza il Dockerfile. Separa il download delle dipendenze dal build del codice come nell'esempio sopra.
5. Leggi la documentazione ufficiale. Il Managing dependencies di Go è la fonte primaria che citiamo sempre nei nostri progetti.

Noi di Meteora Web usiamo Go in produzione per microservizi, API REST e strumenti interni. Gestiamo le dipendenze con la stessa disciplina che applichiamo ai bilanci dei clienti: ogni versione è tracciata, ogni aggiornamento è testato. Se vuoi approfondire come integriamo Go in architetture reali, dai un’occhiata alla nostra pagina principale su Go per backend.