golang-standarder / projektlayout

oversættelser:

  • Karri
  • Karri
  • Karri
  • Karri
  • Karri – ???

  • Franrilisais
  • Liri
  • Portugisisk
  • Espa Larsol

oversigt

Dette er et grundlæggende layout til go-applikationsprojekter. Det er ikke en officiel standard defineret af core Go dev-teamet; det er dog et sæt fælles historiske og nye projektlayoutmønstre i Go-økosystemet. Nogle af disse mønstre er mere populære end andre. Det har også en række små forbedringer sammen med flere understøttende mapper, der er fælles for enhver stor nok applikation i den virkelige verden.

Hvis du prøver at lære Go, eller hvis du bygger en PoC eller et legetøjsprojekt til dig selv, er dette projektlayout en overkill. Start med noget virkelig simpelt (en enkelt main.go fil er mere end nok). Når dit projekt vokser, skal du huske, at det vil være vigtigt at sikre, at din kode er godt struktureret, ellers ender du med en rodet kode med masser af skjulte afhængigheder og global tilstand. Når du har flere mennesker, der arbejder på projektet, har du brug for endnu mere struktur. Det er da det er vigtigt at introducere en fælles måde at administrere pakker/biblioteker på. Når du har et open source-projekt, eller når du kender andre projekter, importerer koden fra dit projektlager, det er da det er vigtigt at have private (aka internal) pakker og kode. Klon repository, holde, hvad du har brug for og slette alt andet! Bare fordi det er der, betyder det ikke, at du skal bruge det hele. Ingen af disse mønstre bruges i hvert enkelt projekt. Selvvendor mønsteret er ikke universelt.

Med Go 1.14Go Modules er endelig klar til produktion. Brug Go Modules medmindre du har en bestemt grund til ikke at bruge dem, og hvis du gør det, behøver du ikke bekymre dig om $GOPATH og hvor du lægger dit projekt. Den grundlæggendego.mod fil i repoen antager, at dit projekt er hostet på GitHub, men det er ikke et krav. Modulstien kan være alt, selvom den første modulstikomponent skal have en prik i sit navn (den aktuelle version af Go håndhæver den ikke længere, men hvis du bruger lidt ældre versioner, skal du ikke blive overrasket, hvis dine builds fejler uden det). Se problemer 37554og 32819 hvis du vil vide mere om det.

dette projektlayout er bevidst generisk, og det forsøger ikke at pålægge en bestemt Go-pakkestruktur.

Dette er en fællesskabsindsats. Åbn et problem, hvis du ser et nyt mønster, eller hvis du mener, at et af de eksisterende mønstre skal opdateres.

Hvis du har brug for hjælp til navngivning, formatering og stil start med at køre gofmtog golint. Sørg også for at læse disse retningslinjer og anbefalinger for Go code-stil:

  • 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
  • style guideline for GO-pakker (rakyll/JBD)

seGo Project Layout for yderligere baggrundsinformation.

mere om navngivning og organisering af pakker samt andre kodestrukturanbefalinger:

  • GopherCon EU 2018: Peter Bourgon – bedste praksis for industriel programmering
  • Gophercon Rusland 2018: Ashley McNamara + Brian Ketelsen – go bedste praksis.
  • GopherCon 2017: GopherCon 2018: Hvordan strukturerer du dine Go-Apps

et kinesisk indlæg om Pakkeorienterede designretningslinjer og Arkitekturlag

  • kar

go-mapper

/cmd

vigtigste applikationer til dette projekt.

katalognavnet for hver applikation skal matche navnet på den eksekverbare, du vil have (f.eks./cmd/myapp).

læg ikke meget kode i applikationsmappen. Hvis du mener, at koden kan importeres og bruges i andre projekter, skal den leve i mappen /pkg. Hvis koden ikke kan genbruges, eller hvis du ikke ønsker, at andre skal genbruge den, skal du placere koden i /internal – mappen. Du vil blive overrasket over, hvad andre vil gøre, så vær eksplicit om dine intentioner!

det er almindeligt at have en lille main funktion, der importerer og påberåber koden fra /internal og /pkg mapper og intet andet.

se mappen/cmd for eksempler.

/intern

privat applikation og bibliotekskode. Dette er den kode, du ikke ønsker, at andre importerer i deres applikationer eller biblioteker. Bemærk, at dette layout mønster håndhæves af Go compiler selv. Se Go 1.4 release notes for flere detaljer. Bemærk, at du ikke er begrænset til det øverste niveau internal mappe. Du kan have mere end eninternal mappe på ethvert niveau af dit projekttræ.

Du kan eventuelt tilføje lidt ekstra struktur til dine interne pakker for at adskille din delte og ikke-delte interne kode. Det er ikke påkrævet (især for mindre projekter), men det er rart at have visuelle spor, der viser den tilsigtede pakkebrug. Din faktiske applikationskode kan gå i/internal/app – mappen (f.eks./internal/app/myapp) og koden, der deles af disse apps i/internal/pkg – mappen (f. eks./internal/pkg/myprivlib).

/pkg

Bibliotekskode, der er ok at bruge af eksterne applikationer (f. eks., /pkg/mypubliclib). Andre projekter importerer disse biblioteker og forventer, at de fungerer, så tænk to gange, før du lægger noget her 🙂 bemærk, at internal – mappen er en bedre måde at sikre, at dine private pakker ikke kan importeres, fordi de håndhæves af Go. /pkg – mappen er stadig en god måde at eksplicit kommunikere, at koden i den mappe er sikker til brug for andre. I'll take pkg over internal blogindlæg af Travis Jeffery giver et godt overblik overpkg oginternal mapper, og når det kan være fornuftigt at bruge dem.

det er også en måde at gruppere Go-kode på et sted, når din rodmappe indeholder masser af ikke – Go – komponenter og mapper, der gør det lettere at køre forskellige Go – værktøjer (som nævnt i disse samtaler:Best Practices for Industrial Programming fra GopherCon EU 2018, GopherCon 2018: Kat lynlås-hvordan strukturerer du dine Go-Apps og GoLab 2018-Massimiliano Pippi-Projektlayoutmønstre I Go).

se mappen/pkg, hvis du vil se, hvilke populære go-repoer der bruger dette projektlayoutmønster. Dette er et almindeligt layoutmønster, men det er ikke universelt accepteret, og nogle I Go-samfundet anbefaler det ikke.

det er ok ikke at bruge det, hvis dit appprojekt er virkelig lille, og hvor et ekstra niveau af nesting ikke tilføjer meget værdi (medmindre du virkelig vil :-)). Tænk over det, når det bliver stort nok, og din rodmappe bliver ret travlt (især hvis du har mange ikke-Go-appkomponenter).

/vendor

Applikationsafhængigheder (administreret manuelt eller af dit foretrukne afhængighedsstyringsværktøj som den nye indbyggedeGo Modules funktion). Kommandoengo mod vendor opretter/vendor mappe til dig. Bemærk, at du muligvis skal tilføje -mod=vendor flag til din go build kommando, hvis du ikke bruger Go 1.14, hvor den er tændt som standard.

forpligt ikke dine applikationsafhængigheder, hvis du bygger et bibliotek.

Bemærk, at da 1.13Go også aktiverede modulets fuldmagtsfunktion (ved hjælp afhttps://proxy.golang.org som deres modul fuldmagts server som standard). Læs mere om det here for at se, om det passer til alle dine krav og begrænsninger. Hvis det gør det, behøver du slet ikke vendor – mappen.

Serviceapplikationsmapper

/api

OpenAPI / Svagger-SPECIFIKATIONER, JSON-skemafiler, protokoldefinitionsfiler.

se/api mappe for eksempler.

Netapplikationsmapper

/internet

netapplikationsspecifikke komponenter: statiske netaktiver, serversideskabeloner og kurbade.

almindelige applikationsmapper

/configs

konfigurationsfilskabeloner eller standardkonfigurationer.

Sæt dinconfd ellerconsul-template skabelonfiler her.

/init

System init (systemd, upstart, sysv) og process manager / supervisor (runit, supervisord) configs.

/scripts

Scripts til at udføre forskellige build, installere, analyse, etc operationer.

disse scripts holder rodniveauet Makefile lille og enkel (f.eks. https://github.com/hashicorp/terraform/blob/master/Makefile).

se mappen/scripts for eksempler.

/build

emballage og kontinuerlig Integration.

Sæt din cloud (AMI), container (Docker), os (deb, rpm, pkg) pakkekonfigurationer og scripts i/build/package mappe.

Sæt din CI (travis, circle, drone) konfigurationer og scripts i /build/ci mappe. Bemærk, at nogle af CI-værktøjerne (f. eks., Travis CI) er meget kræsen om placeringen af deres konfigurationsfiler. Prøv at placere konfigurationsfilerne i/build/ci – mappen, der forbinder dem med det sted, hvor CI-værktøjerne forventer dem (når det er muligt).

/implementeringer

IaaS, PaaS, system og container orkestrering implementeringskonfigurationer og skabeloner (docker-compose, kubernetes / helm, mesos, terraform, bosh). Bemærk, at i nogle repos (især apps implementeret med kubernetes) kaldes denne mappe /deploy.

/test

yderligere eksterne testapps og testdata. Du er velkommen til at strukturere /test mappen alligevel du vil. For større projekter er det fornuftigt at have en data undermappe. For eksempel kan du have /test/data eller /test/testdata hvis du har brug for at ignorere, hvad der er i den mappe. Bemærk, at Go også ignorerer mapper eller filer, der begynder med “.”eller”_”, så du har mere fleksibilitet med hensyn til, hvordan du navngiver din testdatakatalog.

se/test mappe for eksempler.

andre mapper

/docs

design-og brugerdokumenter (ud over din godoc-genererede dokumentation).

se mappen/docs for eksempler.

/værktøjer

understøttende værktøjer til dette projekt. Bemærk, at disse værktøjer kan importere kode fra/pkg og/internal mapper.

se/tools mappe for eksempler.

/eksempler

eksempler til dine applikationer og/eller offentlige biblioteker.

se/examples mappe for eksempler.

/third_party

eksterne hjælpeværktøjer, gaffelkode og andre 3.parts hjælpeprogrammer (f. eks.

/githooks

Git kroge.

/aktiver

andre aktiver til at gå sammen med dit lager (billeder, logoer osv.).

/hjemmeside

dette er stedet at placere dit projekts hjemmesidedata, hvis du ikke bruger GitHub-sider.

se/website mappe for eksempler.

mapper du bør ikke have

/src

nogle Go-projekter har ensrc mappe, men det sker normalt, når devs kom fra Java-verdenen, hvor det er et fælles mønster. Hvis du kan hjælpe dig selv, prøv ikke at vedtage dette Java-mønster. Du vil virkelig ikke have din Go-kode eller Go-projekter til at ligne Java: -)

forveksl ikke projektniveauet /src mappe med /src directory go bruger til sine arbejdsområder som beskrevet i How to Write Go Code. Miljøvariablen$GOPATH peger på dit (nuværende) arbejdsområde (som standard peger det på$HOME/go på ikke-Vinduer systemer). Dette arbejdsområde inkluderer det øverste niveau/pkg/bin og/src mapper. Dit egentlige projekt ender med at blive en undermappe under/src, så hvis du har/src mappen i dit projekt vil projektstien se sådan ud:/some/path/to/workspace/src/your_project/src/your_code.go. Bemærk, at med Go 1.11 Det er muligt at have dit projekt uden for dit GOPATH, men det betyder stadig ikke, at det er en god ide at bruge dette layoutmønster.

Badges

  • Go Report Card – det vil scanne din kode med gofmtgo vetgocyclogolintineffassignlicense og misspell. Erstat github.com/golang-standards/project-layout med din projektreference.

    Go rapport Card

  • GoDoc – det vil give online version af din GoDoc genereret dokumentation. Skift linket for at pege på dit projekt.

    Go Doc

  • Pkg.gå.dev-Pkg.gå.dev er en ny destination for Go discovery & docs. Du kan oprette et badge ved hjælp af badgegenereringsværktøjet.

    PkgGoDev

  • Release – det viser det seneste udgivelsesnummer til dit projekt. Skift github-linket for at pege på dit projekt.

    Release

noter

en mere meningsfuld projektskabelon med prøve / genanvendelige configs, scripts og kode er en VIP.

Skriv et svar

Din e-mailadresse vil ikke blive publiceret.