golang-standards/project-layout

traduceri:

  • ??
  • Fran
  • Portugheză
  • Espa

prezentare generală

acesta este un aspect de bază pentru proiectele de aplicații Go. Nu este un standard oficial definit de echipa core GO dev; cu toate acestea, este un set de modele comune de aspect istoric și emergent al proiectului în ecosistemul Go. Unele dintre aceste modele sunt mai populare decât altele. De asemenea, are o serie de îmbunătățiri mici, împreună cu mai multe directoare de sprijin comune pentru orice aplicație suficient de mare din lumea reală.

dacă încercați să învățați Go sau dacă construiți un PoC sau un proiect de jucărie pentru dvs., acest aspect al proiectului este un exces. Începeți cu ceva foarte simplu (un singur fișier main.go este mai mult decât suficient). Pe măsură ce proiectul dvs. crește, rețineți că va fi important să vă asigurați că codul dvs. este bine structurat, altfel veți ajunge la un cod dezordonat, cu o mulțime de dependențe ascunse și stare globală. Când veți avea mai mulți oameni care lucrează la proiect, veți avea nevoie de mai multă structură. Atunci este important să introduceți o modalitate comună de gestionare a pachetelor/bibliotecilor. Când aveți un proiect open source sau când știți că alte proiecte importă codul din depozitul de proiecte, atunci este important să aveți pachete și cod privat (aka internal). Clonați depozitul, păstrați ceea ce aveți nevoie și ștergeți orice altceva! Doar pentru că este acolo, nu înseamnă că trebuie să le folosești pe toate. Niciunul dintre aceste modele nu este utilizat în fiecare proiect. Chiar și modelulvendor nu este universal.

cu Go 1.14Go Modules Sunt în sfârșit gata de producție. Utilizați Go Modules dacă nu aveți un motiv specific să nu le utilizați și dacă faceți acest lucru, nu trebuie să vă faceți griji cu privire la $GOPATH și unde ați pus proiectul. Fișierul de bazăgo.mod din repo presupune că proiectul dvs. este găzduit pe GitHub, dar nu este o cerință. Calea modulului poate fi orice, deși prima componentă a căii modulului ar trebui să aibă un punct în numele său (versiunea curentă a Go nu o mai impune, dar dacă utilizați versiuni puțin mai vechi, nu vă mirați dacă versiunile dvs. eșuează fără ea). Consultați problemele 37554și32819 dacă doriți să aflați mai multe despre aceasta.

acest aspect de proiect este intenționat generic și nu încearcă să impună o structură specifică pachet Go.

acesta este un efort comunitar. Deschideți o problemă dacă vedeți un model nou sau dacă credeți că unul dintre modelele existente trebuie actualizat.

dacă aveți nevoie de ajutor pentru denumire, formatare și stil, începeți prin rulareagofmt șigolint. De asemenea, asigurați-vă că citiți aceste linii directoare și recomandări pentru stilul Codului 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
  • ghid de stil pentru pachetele Go (rakyll/JBD)

a se vedea Go Project Layoutpentru informații suplimentare de fond.

Mai multe despre denumirea și organizarea pachetelor, precum și alte recomandări privind structura codului:

  • GopherCon EU 2018: Peter Bourgon – cele mai bune practici pentru programarea industrială
  • Gophercon Rusia 2018: Ashley McNamara + Brian Ketelsen – Go best practices.
  • GopherCon 2017: Edward Muller-Go Anti-Patterns
  • GopherCon 2018: Kat Zien-cum vă structurați aplicațiile Go

un Post Chinezesc despre liniile directoare de proiectare orientate spre pachete și stratul de arhitectură

directoare Go

/cmd

principalele aplicații pentru acest proiect.

numele directorului pentru fiecare aplicație trebuie să se potrivească cu numele executabilului pe care doriți să îl aveți (de exemplu,/cmd/myapp).

nu puneți prea mult cod în directorul de aplicații. Dacă credeți că codul poate fi importat și utilizat în alte proiecte, atunci ar trebui să trăiască în directorul /pkg. Dacă codul nu este reutilizabil sau dacă nu doriți ca alții să-l reutilizeze, puneți codul în directorul /internal. Vei fi surprins de ceea ce vor face alții, așa că fii explicit cu privire la intențiile tale!

este obișnuit să ai o micămainfuncție care importă și invocă codul din directoarele/internalși/pkg și nimic altceva.

vedeți directorul/cmd pentru exemple.

/intern

aplicație privată și cod de bibliotecă. Acesta este codul pe care nu doriți ca alții să îl importe în aplicațiile sau bibliotecile lor. Rețineți că acest model de aspect este aplicat chiar de compilatorul Go. Consultați Go 1.4 release notes pentru mai multe detalii. Rețineți că nu vă limitați la directorul de nivel superior internal. Puteți avea mai mult de un director internal la orice nivel al arborelui Dvs. de proiect.

puteți adăuga opțional un pic de structură suplimentară pachetelor interne pentru a separa codul intern partajat și non-partajat. Nu este necesar (în special pentru proiectele mai mici), dar este plăcut să aveți indicii vizuale care să arate utilizarea pachetului dorit. Codul real al aplicației dvs. poate merge în directorul/internal/app (de exemplu,/internal/app/myapp) și Codul partajat de aceste aplicații în directorul/internal/pkg (de exemplu,/internal/pkg/myprivlib).

/pkg

Codul bibliotecii care este ok pentru a fi utilizat de aplicații externe (de ex., /pkg/mypubliclib). Alte proiecte vor importa aceste biblioteci așteptându-le să funcționeze, așa că gândiți-vă de două ori înainte de a pune ceva aici: -) rețineți că directorul internal este o modalitate mai bună de a vă asigura că pachetele dvs. private nu sunt importabile, deoarece este impus de Go. Directorul /pkg este încă o modalitate bună de a comunica în mod explicit că codul din acel director este sigur pentru utilizarea de către alții. I'll take pkg over internal blog post de Travis Jeffery oferă o imagine de ansamblu bună a pkg și internal directoare și când ar putea avea sens să le folosească.

este, de asemenea, o modalitate de a grupa Codul Go într-un singur loc atunci când directorul rădăcină conține o mulțime de componente și directoare non – Go, facilitând rularea diferitelor instrumente Go (așa cum se menționează în aceste discuții:Best Practices for Industrial Programming din GOPHERCON EU 2018, GopherCon 2018: Kat Zien – cum structurați aplicațiile Go și GoLab 2018 – Massimiliano Pippi-modele de aspect de proiect În Go).

vedeți directorul/pkg dacă doriți să vedeți ce repo-uri populare Go utilizează acest model de aspect al proiectului. Acesta este un model comun de aspect, dar nu este universal acceptat și unii din comunitatea Go nu îl recomandă.

este ok să nu-l folosească în cazul în care proiectul app este foarte mic și în cazul în care un nivel suplimentar de cuiburi nu adaugă multă valoare (cu excepția cazului în care într-adevăr doriți să: -)). Gândiți-vă când devine suficient de mare și directorul dvs. rădăcină devine destul de ocupat (mai ales dacă aveți o mulțime de componente de aplicații non-Go).

/vendor

dependențe de aplicații (gestionate manual sau de instrumentul dvs. preferat de gestionare a dependenței, cum ar fi noua caracteristică încorporatăGo Modules). Comandago mod vendor va crea directorul/vendor pentru dvs. Rețineți că este posibil să fie necesar să adăugați -mod=vendor la go build comanda dacă nu utilizați Go 1.14 unde este activat în mod implicit.

nu comiteți dependențele aplicației dacă construiți o bibliotecă.

rețineți că, deoarece 1.13 Go activat, de asemenea, caracteristica proxy modul (folosindhttps://proxy.golang.org ca server proxy modul lor în mod implicit). Citiți mai multe despre el here pentru a vedea dacă se potrivește tuturor cerințelor și constrângerilor dvs. Dacă da, atunci nu veți avea nevoie deloc de directorul vendor.

directoare de aplicații de servicii

/api

specificații OpenAPI / Swagger, fișiere schemă JSON, fișiere definiție protocol.

vedeți directorul/api pentru exemple.

directoare de aplicații Web

/web

componente specifice aplicației Web: active web statice, șabloane pe partea serverului și spa-uri.

directoare de aplicații comune

/configs

șabloane de fișiere de configurare sau configs implicite.

puneți fișierele șablonconfd sauconsul-template aici.

/init

init sistem (systemd, parvenit, sysv) și manager de proces / supervizor (runit, supervisord) configs.

/script-uri

script-uri pentru a efectua diverse construi, instala, analiza, etc operațiuni.

aceste scripturi păstrează nivelul rădăcină Makefile mic și simplu (de exemplu,https://github.com/hashicorp/terraform/blob/master/Makefile).

vedeți directorul/scripts pentru exemple.

/build

ambalare și Integrare Continuă.

puneți configurațiile și scripturile de pachete cloud (AMI), container (Docker), OS (DEB, rpm, pkg) în directorul/build/package.

puneți configurațiile și scripturile CI (travis, circle, drone) în directorul/build/ci. Rețineți că unele dintre instrumentele CI (de ex., Travis CI) sunt foarte pretențioși în ceea ce privește locația fișierelor de configurare. Încercați să puneți fișierele de configurare în directorul /build/ci care le leagă de locația în care instrumentele CI le așteaptă (când este posibil).

/implementări

IaaS, PaaS, configurații și șabloane de implementare a orchestrației de sistem și container (docker-compose, kubernetes / helm, mesos, terraform, bosh). Rețineți că în unele repo-uri (în special aplicațiile implementate cu kubernetes) acest director se numește /deploy.

/test

aplicații de testare externe suplimentare și date de testare. Simțiți-vă liber să structurați directorul /test oricum doriți. Pentru proiecte mai mari este logic să aveți un subdirector de date. De exemplu, puteți avea /test/data sau /test/testdata dacă aveți nevoie, mergeți să ignorați ce este în acel director. Rețineți că Go va ignora și directoarele sau fișierele care încep cu “.”sau”_”, astfel încât să aveți mai multă flexibilitate în ceea ce privește modul în care denumiți directorul de date de testare.

vedeți directorul/test pentru exemple.

alte directoare

/documente

documente de proiectare și utilizator (pe lângă documentația generată de godoc).

vedeți directorul/docs pentru exemple.

/instrumente

instrumente de sprijin pentru acest proiect. Rețineți că aceste instrumente pot importa cod din directoarele /pkg și /internal.

vedeți directorul/tools pentru exemple.

/Exemple

exemple pentru aplicațiile și / sau bibliotecile publice.

vedeți directorul/examples pentru exemple.

/third_party

instrumente de ajutor extern, codul bifurcat și alte utilități 3rd party (de exemplu, făli UI).

/githooks

cârlige Git.

/active

alte active pentru a merge împreună cu depozitul dvs. (imagini, logo-uri, etc).

/website

acesta este locul pentru a pune datele site-ului proiectului dvs. dacă nu utilizați pagini GitHub.

vedeți directorul/website pentru exemple.

directoare nu ar trebui să aveți

/src

unele proiecte Go au unsrc folder, dar se întâmplă de obicei atunci când devs a venit din lumea Java în cazul în care este un model comun. Dacă vă puteți ajuta să încercați să nu adoptați acest model Java. Chiar nu doriți ca codul Go sau proiectele Go să arate ca Java: -)

nu confundați nivelul proiectului/src cu directorul/src directorul Go folosește pentru spațiile sale de lucru așa cum este descris înHow to Write Go Code. Variabila de mediu$GOPATH indică spațiul de lucru (curent) (implicit indică$HOME/go pe sistemele non-windows). Acest spațiu de lucru include nivelul superior /pkg/bin și /src directoare. Proiectul dvs. actual ajunge să fie un subdirector sub /src, deci dacă aveți directorul /src în proiectul dvs., calea proiectului va arăta astfel: /some/path/to/workspace/src/your_project/src/your_code.go. Rețineți că cu Go 1.11 este posibil să aveți proiectul în afara GOPATH, dar totuși nu înseamnă că este o idee bună să utilizați acest model de aspect.

Insigne

  • du – te Carte de raport-se va scana codul cu gofmtgo vetgocyclogolintineffassignlicense și misspell. Înlocuiți github.com/golang-standards/project-layout cu referința proiectului.

    du - te Carte de raport

  • GoDoc-acesta va oferi versiunea on-line a documentației generate GoDoc. Schimbați linkul pentru a indica proiectul dvs.

    Go Doc

  • Pkg.du-te.dev-Pkg.du-te.dev este o nouă destinație pentru GO discovery & docs. Puteți crea o insignă utilizând instrumentul de generare a insignelor.

    PkgGoDev

  • Release – acesta va afișa cel mai recent număr de lansare pentru proiectul dumneavoastră. Schimbați linkul github pentru a indica proiectul dvs.

    eliberare

Note

un șablon de proiect mai dogmatic cu configs eșantion / reutilizabile, script-uri și Codul este un WIP.

Lasă un răspuns

Adresa ta de email nu va fi publicată.