Panoramica

Questo è un layout di base per i progetti di applicazioni Go. Non è uno standard definito ufficialmente dal team di sviluppo principale di Go; è un layout di directory comunemente usato per i progetti della comunità Go.

Se stai imparando Go o stai costruendo una dimostrazione di concetto (PoC) o un semplice progetto personale, questo layout del progetto è troppo complicato. Invece, inizia con un layout veramente semplice (solo un file main.go e go.mod sono sufficienti). Man mano che il tuo progetto evolve, assicurati che la struttura del tuo codice sia buona, altrimenti finirai con un codice disordinato contenente un sacco di dipendenze nascoste e stato globale. Quando più persone sono coinvolte nel progetto, è necessario un modo più strutturato. In questo caso, è importante introdurre un modo comune per gestire pacchetti/librerie. Quando hai un progetto open-source o sai che altri progetti importano codice dal repository del tuo progetto, diventa importante avere pacchetti e codice privati (anche noti come internal). Clone il repository, tenga le parti di cui ha bisogno e elimini tutto il resto! Solo perché esiste, non significa che devi usarlo tutto. Nessuno di questi pattern è utilizzato in ogni progetto. Anche il pattern vendor non è universale.

Questo layout del progetto è intenzionalmente progettato per essere molto generale e non cerca di imporre una struttura specifica del pacchetto Go.

Specifica della Directory del Progetto Go

Di seguito è riportata la specifica della directory del progetto Go consigliata.

.
├── go.mod
├── api
├── assets
├── build
├── cmd
├── configs
├── deployments
├── docs
├── examples
├── githooks
├── go.mod
├── init
├── internal
├── pkg
├── scripts
├── test
├── third_party
├── tools
├── vendor
├── web
└── website

I significati di ciascuna directory sono introdotti di seguito.

/cmd

Le principali applicazioni per il progetto, ovvero il punto di ingresso dei programmi. I file Go in questa directory generano di solito file eseguibili. In un progetto semplice, un file come /test/main.go può fungere da punto di ingresso.

Il nome della directory per ogni applicazione dovrebbe corrispondere al nome del file eseguibile desiderato (ad esempio, /cmd/myapp).

Non inserire troppo codice nella directory dell'applicazione. Se pensi che il codice possa essere importato e utilizzato in altri progetti, inseriscilo nella directory /pkg. Se il codice non è riutilizzabile o non desideri che altri lo riutilizzino, inserisci il codice nella directory /internal. Sarai sorpreso dai comportamenti altrui, quindi esprimi chiaramente la tua intenzione!

Di solito c'è una piccola funzione main che importa e chiama il codice dalle directory /internal e /pkg, e nient'altro.

/internal

Codice dell'applicazione e delle librerie private. Questo è il codice che non desideri che altri importino nelle loro applicazioni o librerie. Nota che questo modello di layout è imposto dal compilatore Go stesso. Per informazioni più dettagliate, consultare le note sulla versione per Go 1.4. Tieni presente che non è limitato alla directory internal di primo livello. Puoi avere diverse directory internal a qualsiasi livello dell'albero del progetto.

Puoi scegliere di aggiungere una struttura aggiuntiva per i pacchetti interni per distinguere tra codice interno condiviso e non condiviso. Questo non è obbligatorio (specialmente per progetti più piccoli), ma dimostrare visivamente l'uso previsto dei pacchetti è una buona pratica. Il tuo effettivo codice dell'applicazione può essere posto nella directory /internal/app (ad esempio, /internal/app/myapp), e il codice condiviso per queste applicazioni può essere collocato nella directory /internal/pkg (ad esempio, /internal/pkg/myprivlib).

/pkg

Codice della libreria che può essere utilizzato da applicazioni esterne (ad esempio, /pkg/mypubliclib). Altri progetti importano queste librerie e si aspettano che funzionino correttamente, quindi pensaci attentamente prima di inserire contenuti qui :-) Nota che la directory internal è un modo migliore per garantire che i pacchetti privati non possano essere importati, poiché è imposto dal Go stesso. La directory /pkg è comunque un buon modo per comunicare esplicitamente che il codice in questa directory è sicuro per gli altri da usare.

Se il progetto della tua applicazione è molto piccolo e l'annidamento a più livelli non aggiunge molto valore, va bene anche non usarlo (a meno che tu non voglia davvero farlo :-)). Quando il progetto diventa abbastanza grande e la directory radice diventa molto occupata, considera di usarlo (specialmente se hai molti componenti dell'applicazione non-Go).

/vendor

Dipendenze dell'applicazione (gestite manualmente o utilizzando il tuo strumento di gestione delle dipendenze preferito, come la funzionalità integrata Go Modules). Il comando go mod vendor creerà per te la directory /vendor. Nota che se non stai utilizzando la versione predefinita abilitata di Go 1.14, potresti dover aggiungere il flag -mod=vendor al comando go build.

Se stai costruendo una libreria, per favore non includere le dipendenze dell'applicazione nel commit.

Directory dell'Applicazione di Servizio

/api

Specifiche OpenAPI/Swagger, file di schema JSON, file di definizione del protocollo e directory del protocollo API.

Directory dell'Applicazione Web

/web

Componenti specifici per applicazioni web: risorse statiche del sito web, modelli lato server e applicazioni single-page (SPA).

Directory Generiche dell'Applicazione

/configs

Modelli di file di configurazione o configurazioni predefinite.

Posiziona i file di modello confd o consul-template qui.

/init

Inizializzazione di sistema (systemd, upstart, sysv) e configurazioni del gestore dei processi/demoni (runit, supervisord).

/scripts

Script per varie operazioni di build, installazione, analisi e altro.

/build

Confezionamento e integrazione continua.

Posiziona le configurazioni e gli script per confezionare il pacchetto cloud (AMI), il contenitore (Docker), il sistema operativo (deb, rpm, pkg) nella directory /build/package.

Posiziona le configurazioni e gli script per l'integrazione continua (travis, circle, drone) nella directory /build/ci. Si prega di notare che alcuni strumenti di integrazione continua (come Travis CI) sono molto specifici sulla posizione dei loro file di configurazione. Cerca di posizionare i file di configurazione nella directory /build/ci e utilizza dei collegamenti per connetterli alla posizione prevista dagli strumenti di integrazione continua (se possibile).

/deployments

Configurazioni di distribuzione e modelli per IaaS, PaaS, sistemi e orchestrazione di contenitori (docker-compose, kubernetes/helm, terraform). Si prega di notare che in alcuni repository (specialmente per le applicazioni distribuite utilizzando Kubernetes), questa directory è chiamata /deploy.

/test

Altre applicazioni di test esterne e dati di test. Organizza liberamente la directory /test in modo che sia adatto alle tue esigenze. Per progetti più grandi, ha senso organizzare i dati in sottodirectory. Ad esempio, puoi creare le directory /test/data o /test/testdata all'interno di /test per far ignorare il contenuto a Go. Si prega di notare che Go ignora anche directory o file che iniziano con "." o "_", offrendo maggiore flessibilità nella denominazione delle directory dei dati di test.

Altre Directory

/docs

Documenti di progettazione e documentazione utente (diversi dai documenti godoc generati).

/tools

Strumenti di supporto per questo progetto. Si noti che questi strumenti possono importare codice dalle directory /pkg e /internal.

/examples

Esempi per applicazioni e/o librerie pubbliche.

/third_party

Strumenti ausiliari esterni, codice biforcato e altri strumenti di utilità di terze parti (ad es., Swagger UI).

/githooks

Ganci Git.

/assets

Risorse aggiuntive (immagini, loghi, ecc.) fornite con il repository.

/website

Posizione per memorizzare i dati del sito web del progetto se non si utilizza GitHub Pages.

/src

Alcuni progetti Go possono avere una cartella src, ma questo è tipicamente dovuto ai programmatori provenienti dal mondo Java, dove è un modello comune. Se possibile, cerca di evitare di adottare questo modello simile a Java. Non vuoi davvero che il tuo codice Go o il tuo progetto assomigli a Java :-)

Non confondere la directory /src a livello di progetto con la directory /src utilizzata per lo spazio di lavoro Go, descritto in Come Scrivere il Codice Go. La variabile di ambiente $GOPATH punta al tuo spazio di lavoro (attuale) (per impostazione predefinita, nei sistemi non Windows punta alla directory $HOME/go). Questo spazio di lavoro include le directory di primo livello /pkg, /bin, e /src. Il tuo progetto effettivo sarà una sottodirectory sotto la directory /src, quindi se il tuo progetto ha una directory /src, il percorso del progetto sarà simile a questo: /some/path/to/workspace/src/your_project/src/your_code.go. Si prega di notare che a partire da Go 1.11, il tuo progetto può essere situato al di fuori del GOPATH, ma ciò non significa che utilizzare questo modello di layout sia una buona idea.