Moduli in Go

I moduli (modules) sono il sistema di gestione delle dipendenze di Go, introdotto in Go 1.11 e diventato lo standard a partire da Go 1.16. Un modulo e una collezione di pacchetti Go che vengono rilasciati, versionati e distribuiti insieme.

Il File go.mod

Il file go.mod e il cuore di un modulo Go. Definisce il percorso del modulo, la versione di Go e le dipendenze:

module github.com/miouser/mioprogetto

go 1.23

require (
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/sync v0.6.0
)

Le direttive principali del file go.mod sono:

• module: il percorso del modulo (identifica univocamente il modulo)
• go: la versione minima di Go richiesta
• require: le dipendenze con le loro versioni
• replace: sostituisce un modulo con un altro (utile per sviluppo locale)
• exclude: esclude versioni specifiche di un modulo

Inizializzare un Modulo

Per creare un nuovo modulo si usa il comando go mod init:

mkdir mioprogetto
cd mioprogetto
go mod init github.com/miouser/mioprogetto

Questo genera un file go.mod con il percorso del modulo e la versione di Go corrente.

Per un progetto locale senza repository remoto:

go mod init mioprogetto

Aggiungere Dipendenze

Le dipendenze vengono aggiunte automaticamente quando si importa un pacchetto e si esegue un comando Go:

package main

import (
    "fmt"
    "github.com/fatih/color" // dipendenza esterna
)

func main() {
    color.Green("Ciao in verde!")
    fmt.Println("Go modules!")
}

Eseguendo go mod tidy o go build, Go scarica la dipendenza e aggiorna go.mod:

go mod tidy

Per aggiungere una dipendenza specifica manualmente:

go get github.com/fatih/color@v1.16.0

Il File go.sum

Il file go.sum contiene gli hash crittografici di tutte le dipendenze, garantendo l’integrita e la riproducibilita della build:

github.com/fatih/color v1.16.0 h1:zmkK9Ao92su...
github.com/fatih/color v1.16.0/go.mod h1:4FelS...

Non modificare mai manualmente il file go.sum. Viene gestito automaticamente da Go. Entrambi i file go.mod e go.sum devono essere inclusi nel controllo di versione (git).

Versionamento Semantico

Go utilizza il versionamento semantico (semver) per le dipendenze, nel formato vMAJOR.MINOR.PATCH:

• MAJOR: cambiamenti incompatibili con le versioni precedenti
• MINOR: nuove funzionalita retrocompatibili
• PATCH: correzioni di bug retrocompatibili

go get github.com/pacchetto@v1.2.3   # versione specifica
go get github.com/pacchetto@latest    # ultima versione
go get github.com/pacchetto@v1       # ultima v1.x.x

Versioni Major >= 2

Per le versioni major >= 2, il percorso del modulo deve includere il suffisso della versione major:

import "github.com/esempio/pacchetto/v2" // versione major 2
import "github.com/esempio/pacchetto/v3" // versione major 3

Questo permette di usare piu versioni major nello stesso progetto.

go mod tidy

Il comando go mod tidy e uno degli strumenti piu utili. Aggiunge le dipendenze mancanti e rimuove quelle non utilizzate:

go mod tidy

E buona pratica eseguire go mod tidy regolarmente, specialmente prima di un commit.

go mod vendor

Il comando go mod vendor copia tutte le dipendenze nella directory vendor/ del progetto:

go mod vendor

Questo crea una copia locale di tutte le dipendenze, utile per:

• Build riproducibili senza accesso a internet
• Ambienti CI/CD con restrizioni di rete
• Controllo completo sulle dipendenze

Per usare la directory vendor durante la build:

go build -mod=vendor ./...

Sostituzione di Moduli

La direttiva replace nel file go.mod permette di sostituire un modulo con un altro percorso:

module mioprogetto

go 1.23

require github.com/miouser/libreria v1.0.0

// Usa la versione locale durante lo sviluppo
replace github.com/miouser/libreria => ../libreria

Questo e particolarmente utile durante lo sviluppo locale di piu moduli correlati.

Moduli Privati

Per usare moduli da repository privati, e necessario configurare la variabile d’ambiente GOPRIVATE:

# Configura i pattern dei moduli privati
go env -w GOPRIVATE=github.com/miaorganizzazione/*

# Oppure tramite variabile d'ambiente
export GOPRIVATE=github.com/miaorganizzazione/*

Per l’autenticazione con repository privati, Go utilizza il file .netrc o le credenziali Git configurate.

Workspace Mode (go.work)

A partire da Go 1.18, la modalita workspace permette di lavorare contemporaneamente su piu moduli correlati senza usare replace:

# Crea un file go.work nella directory radice
go work init ./modulo1 ./modulo2

Questo genera un file go.work:

go 1.23

use (
    ./modulo1
    ./modulo2
)

Esempio Pratico

Struttura del progetto:

workspace/
    go.work
    api/
        go.mod
        main.go
    libreria/
        go.mod
        utils.go

cd workspace
go work init ./api ./libreria

Ora api puo importare libreria direttamente, e le modifiche a libreria si riflettono immediatamente in api senza bisogno di pubblicare una nuova versione.

Comandi utili per la gestione del workspace:

go work use ./nuovo-modulo  # aggiunge un modulo al workspace
go work sync                # sincronizza le dipendenze

Nota importante: il file go.work e pensato per lo sviluppo locale e generalmente non deve essere incluso nel controllo di versione.

Comandi Utili

Ecco un riepilogo dei comandi piu usati per la gestione dei moduli:

go mod init nome/modulo  # inizializza un nuovo modulo
go mod tidy              # pulisce le dipendenze
go mod vendor            # crea la directory vendor
go mod download          # scarica le dipendenze nella cache
go mod verify            # verifica l'integrita delle dipendenze
go mod graph             # mostra il grafo delle dipendenze
go list -m all           # elenca tutti i moduli
go get -u ./...          # aggiorna tutte le dipendenze

Conclusione

Il sistema di moduli di Go fornisce un modo robusto e standardizzato per gestire le dipendenze. Il versionamento semantico, il file go.sum per l’integrita, e la modalita workspace per lo sviluppo multi-modulo rendono la gestione delle dipendenze in Go semplice e affidabile. Comprendere questi strumenti e fondamentale per ogni sviluppatore Go.