golang-standard / project-layout

Traduzioni:

  • 한국어 문서
  • 中中文
  • ?中文 – ???
  • Français
  • 日本語
  • Portuguese
  • Español

Panoramica

Questo è un layout di base per i progetti di applicazioni Go. Non è uno standard ufficiale definito dal core Go dev team; tuttavia, è un insieme di modelli di layout di progetto storici ed emergenti comuni nell’ecosistema Go. Alcuni di questi modelli sono più popolari di altri. Ha anche una serie di piccoli miglioramenti insieme a diverse directory di supporto comuni a qualsiasi applicazione del mondo reale abbastanza grande.

Se stai cercando di imparare Go o se stai costruendo un PoC o un progetto giocattolo per te stesso, questo layout del progetto è eccessivo. Inizia con qualcosa di veramente semplice (un singolo file main.go è più che sufficiente). Man mano che il tuo progetto cresce, tieni presente che sarà importante assicurarti che il tuo codice sia ben strutturato altrimenti finirai con un codice disordinato con molte dipendenze nascoste e stato globale. Quando hai più persone che lavorano al progetto avrai bisogno di ancora più struttura. Questo è quando è importante introdurre un modo comune per gestire pacchetti / librerie. Quando si dispone di un progetto open source o quando si conoscono altri progetti, importare il codice dal repository del progetto, è importante disporre di pacchetti e codice privati (ovvero internal). Clona il repository, mantieni ciò di cui hai bisogno ed elimina tutto il resto! Solo perché è lì non significa che devi usare tutto. Nessuno di questi modelli viene utilizzato in ogni singolo progetto. Anche il modellovendor non è universale.

Con Go 1.14Go Modules sono finalmente pronti per la produzione. Usa Go Modules a meno che tu non abbia un motivo specifico per non usarli e se lo fai, non devi preoccuparti di GOP GOPATH e dove metti il tuo progetto. Il file go.mod di base nel repository presuppone che il progetto sia ospitato su GitHub, ma non è un requisito. Il percorso del modulo può essere qualsiasi cosa anche se il primo componente del percorso del modulo dovrebbe avere un punto nel suo nome (la versione corrente di Go non lo applica più, ma se si utilizzano versioni leggermente più vecchie non stupirsi se le build falliscono senza di esso). Vedi Problemi37554 e32819 se vuoi saperne di più.

Questo layout del progetto è intenzionalmente generico e non tenta di imporre una specifica struttura del pacchetto Go.

Questo è uno sforzo della comunità. Apri un problema se vedi un nuovo modello o se ritieni che uno dei modelli esistenti debba essere aggiornato.

Se hai bisogno di aiuto con la denominazione, la formattazione e lo stile inizia eseguendogofmtegolint. Assicurati inoltre di leggere queste linee guida e raccomandazioni per lo stile del codice Go:

  • https://talks.golang.org/2014/names.slide
  • https://golang.org/doc/effective_go.html#names
  • https://blog.golang.org/package-names
  • https://github.com/golang/go/wiki/CodeReviewComments
  • Stile di guida per Andare pacchetti (rakyll/JBD)

Vedere Go Project Layout per ulteriori informazioni.

Ulteriori informazioni sulla denominazione e l’organizzazione dei pacchetti e altre raccomandazioni sulla struttura del codice:

  • GopherCon EU 2018: Peter Bourgon – Best practice per la programmazione industriale
  • GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen – Go best practices.
  • GopherCon 2017: Edward Muller-Go Anti-Patterns
  • GopherCon 2018: Kat Zien – Come strutturare le tue app Go

Un post cinese sulle linee guida di progettazione orientata ai pacchetti e sul livello di architettura

  • 面向包的

Go Directories

/cmd

Principali applicazioni per questo progetto.

Il nome della directory per ogni applicazione deve corrispondere al nome dell’eseguibile che si desidera avere (ad esempio, /cmd/myapp).

Non inserire molto codice nella directory dell’applicazione. Se pensi che il codice possa essere importato e utilizzato in altri progetti, allora dovrebbe vivere nella directory/pkg. Se il codice non è riutilizzabile o se non vuoi che altri lo riutilizzino, inserisci quel codice nella directory /internal. Sarete sorpresi di ciò che gli altri faranno, in modo da essere esplicito circa le vostre intenzioni!

È comune avere una piccola funzione main che importa e richiama il codice dalle directory /internal e /pkg e nient’altro.

Vedere la directory/cmd per esempi.

/interno

Applicazione privata e codice libreria. Questo è il codice che non vuoi che altri importino nelle loro applicazioni o librerie. Si noti che questo modello di layout viene applicato dal compilatore Go stesso. Vedere Go 1.4 release notes per maggiori dettagli. Si noti che non si è limitati alla directory internal di livello superiore. Puoi avere più di una directory internal a qualsiasi livello dell’albero del progetto.

Puoi opzionalmente aggiungere un po ‘ di struttura extra ai tuoi pacchetti interni per separare il tuo codice interno condiviso e non condiviso. Non è richiesto (specialmente per progetti più piccoli), ma è bello avere indizi visivi che mostrino l’uso previsto del pacchetto. Il codice effettivo dell’applicazione può andare nella directory/internal/app (ad esempio,/internal/app/myapp) e il codice condiviso da tali app nella directory/internal/pkg (ad esempio,/internal/pkg/myprivlib).

/pkg

Codice libreria che è ok da utilizzare da applicazioni esterne (ad esempio, /pkg/mypubliclib). Altri progetti importeranno queste librerie aspettandosi che funzionino, quindi pensaci due volte prima di mettere qualcosa qui 🙂 Nota che la directory internal è un modo migliore per garantire che i tuoi pacchetti privati non siano importabili perché è applicata da Go. La directory/pkg è ancora un buon modo per comunicare esplicitamente che il codice in quella directory è sicuro per l’uso da parte di altri. Il post sul blogI'll take pkg over internal di Travis Jeffery fornisce una buona panoramica delle directorypkg einternal e quando potrebbe avere senso utilizzarle.

È anche un modo per raggruppare il codice Go in un unico posto quando la tua directory root contiene molti componenti e directory non Go rendendo più facile l’esecuzione di vari strumenti Go (come menzionato in questi discorsi: Best Practices for Industrial Programming da GopherCon EU 2018, GopherCon 2018: Kat Zien-Come strutturi le tue app Go e GoLab 2018 – Massimiliano Pippi – Schemi di layout del progetto in Go).

Vedere la directory/pkg se si desidera vedere quali repository Go popolari utilizzano questo modello di layout del progetto. Questo è un modello di layout comune, ma non è universalmente accettato e alcuni nella comunità Go non lo raccomandano.

Va bene non usarlo se il tuo progetto di app è davvero piccolo e dove un livello extra di nesting non aggiunge molto valore (a meno che tu non voglia davvero :-)). Pensaci quando sta diventando abbastanza grande e la tua directory root diventa piuttosto occupata (specialmente se hai molti componenti di app non Go).

/vendor

Dipendenze dell’applicazione (gestite manualmente o dal tuo strumento di gestione delle dipendenze preferito come la nuova funzioneGo Modules integrata). Il comandogo mod vendor creerà la directory/vendor per te. Si noti che potrebbe essere necessario aggiungere il flag-mod=vendor al comandogo build se non si utilizza Go 1.14 dove è attivo per impostazione predefinita.

Non commettere le dipendenze dell’applicazione se si sta creando una libreria.

Si noti che poiché 1.13 Go ha anche abilitato la funzione proxy del modulo (utilizzando https://proxy.golang.org come server proxy del modulo per impostazione predefinita). Per saperne di più here per vedere se si adatta a tutti i requisiti e vincoli. Se lo fa, allora non avrai bisogno della directoryvendor.

Directory delle applicazioni di servizio

/api

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

Vedere la directory/api per esempi.

Directory delle applicazioni Web

/web

Componenti specifici delle applicazioni Web: risorse Web statiche, modelli lato server e SPA.

Directory comuni dell’applicazione

/configs

Modelli di file di configurazione o configurazioni predefinite.

Metti qui i tuoiconfd oconsul-template.

/init

Sistema di init (systemd, upstart, sysv) e di gestione dei processi / supervisore (runit, supervisord) configurazioni.

/scripts

Script per eseguire varie operazioni di compilazione, installazione, analisi, ecc.

Questi script mantengono il Makefile di livello root piccolo e semplice (ad esempio, https://github.com/hashicorp/terraform/blob/master/Makefile).

Vedere la directory/scripts per esempi.

/costruire

Imballaggio e integrazione continua.

Inserisci le configurazioni dei pacchetti cloud (AMI), container (Docker), OS (deb, rpm, pkg) e gli script nella directory/build/package.

Metti le configurazioni e gli script CI (travis, circle, drone) nella directory/build/ci. Si noti che alcuni degli strumenti CI (ad es., Travis CI) sono molto schizzinosi circa la posizione dei suoi archivi di configurazione. Prova a mettere i file di configurazione nella directory/build/ci collegandoli alla posizione in cui gli strumenti CI li aspettano (quando possibile).

/distribuzioni

IaaS, PaaS, sistema e contenitore orchestrazione configurazioni di distribuzione e modelli (docker-compose, kubernetes / helm, mesos, terraform, bosh). Si noti che in alcuni repository (in particolare le app distribuite con kubernetes) questa directory è chiamata /deploy.

/test

Ulteriori applicazioni di test esterni e dati di test. Sentiti libero di strutturare la directory /test comunque tu voglia. Per progetti più grandi ha senso avere una sottodirectory di dati. Ad esempio, puoi avere /test/data o /test/testdata se hai bisogno di ignorare ciò che è in quella directory. Si noti che Go ignorerà anche le directory o i file che iniziano con “.”o”_”, in modo da avere una maggiore flessibilità in termini di come si nomina la directory dei dati di test.

Vedere la directory/test per esempi.

Altre directory

/documenti

Documenti di progettazione e utente (oltre alla documentazione generata da godoc).

Vedere la directory/docs per esempi.

/strumenti

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

Vedere la directory/tools per esempi.

/esempi

Esempi per le tue applicazioni e / o librerie pubbliche.

Vedere la directory/examples per esempi.

/third_party

Strumenti di supporto esterni, codice biforcuto e altre utilità di terze parti (ad esempio, Swagger UI).

/githooks

Git ganci.

/assets

Altre risorse da accompagnare al tuo repository (immagini, loghi, ecc.).

/website

Questo è il posto dove inserire i dati del sito Web del tuo progetto se non stai usando le pagine GitHub.

Vedere la directory/website per esempi.

Directory Non dovresti avere

/src

Alcuni progetti Go hanno una cartellasrc, ma di solito accade quando gli sviluppatori provengono dal mondo Java dove è uno schema comune. Se puoi aiutare te stesso prova a non adottare questo modello Java. Non vuoi davvero che il tuo codice Go o i tuoi progetti Go assomiglino a Java: -)

Non confondere la directory a livello di progetto /src con la directory /src che Go usa per i suoi spazi di lavoro come descritto in How to Write Go Code. La variabile di ambiente$GOPATH punta all’area di lavoro (corrente) (per impostazione predefinita punta a$HOME/go su sistemi non Windows). Questo spazio di lavoro include le directory di livello superiore /pkg/bin e /src. Il tuo progetto attuale finisce per essere una sottodirectory sotto/src, quindi se hai la directory/src nel tuo progetto il percorso del progetto sarà simile a questo:/some/path/to/workspace/src/your_project/src/your_code.go. Si noti che con Go 1.11 è possibile avere il tuo progetto al di fuori del tuo GOPATH, ma non significa che sia una buona idea usare questo modello di layout.

Distintivi

  • Andare Report Card – sarà la scansione del codice con i tag gofmtgo vetgocyclogolintineffassignlicense e misspell. Sostituire github.com/golang-standards/project-layout con il riferimento del progetto.

    Vai Pagella

  • GoDoc – Fornirà la versione online della documentazione generata da GoDoc. Cambia il link per puntare al tuo progetto.

    Vai Doc

  • Pkg.andare.dev-Pkg.andare.dev è una nuova destinazione per Go discovery& documenti. È possibile creare un badge utilizzando lo strumento generazione badge.

    PkgGoDev

  • Release-Mostrerà l’ultimo numero di release per il progetto. Cambia il link github per puntare al tuo progetto.

    Release

Note

Un modello di progetto più supponente con configurazioni campione / riutilizzabili, script e codice è un WIP.

Lascia un commento

Il tuo indirizzo email non sarà pubblicato.