golang-szabványok / projekt-elrendezés

fordítások:

  • ++
  • ++
  • ??
  • Fran Xiaais
  • Cseh
  • portugál
  • Espa Xiaol

áttekintés

Ez egy alapvető elrendezés Go alkalmazás projektek. Ez nem egy hivatalos szabvány, amelyet a core Go dev csapat határoz meg; azonban ez egy közös történelmi és feltörekvő projektelrendezési minták halmaza a Go ökoszisztémában. Ezen minták egy része népszerűbb, mint mások. Számos apró fejlesztéssel is rendelkezik, valamint számos támogató könyvtárral, amelyek közösek minden elég nagy valós alkalmazásban.

Ha a Go-t próbálod megtanulni, vagy ha PoC-t vagy játékprojektet építesz magadnak, ez a projekt elrendezése túlzás. Kezdje valami nagyon egyszerűvel (egyetlen main.go fájl több mint elég). Mivel a projekt növekszik, ne feledje, hogy fontos lesz, hogy megbizonyosodjon arról, hogy a kód jól strukturált, különben akkor a végén egy rendetlen kódot sok rejtett függőségek és a globális állapot. Ha több ember dolgozik a projekten, akkor még több struktúrára lesz szüksége. Ekkor fontos bevezetni a csomagok/könyvtárak kezelésének közös módját. Ha nyílt forráskódú projektje van, vagy más projekteket ismer, importálja a kódot a projekt tárolójából, akkor fontos, hogy privát (más néven internal) csomagok és kód legyen. Klónozza az adattárat, tartsa meg, amire szüksége van, és törölje minden mást! Csak azért, mert ott van, még nem jelenti azt, hogy mindent fel kell használnia. Ezen minták egyikét sem használják minden egyes projektben. Még avendor minta sem univerzális.

A Go 1.14 Go Modules végre készen állnak a gyártásra. Használja Go Modules hacsak nincs konkrét oka arra, hogy ne használja őket, és ha igen, akkor nem kell aggódnia a $GOPATH és a projekt helye miatt. Az alapvetőgo.mod fájl a repóban feltételezi, hogy a projekt a GitHub-on van tárolva, de ez nem követelmény. A modul elérési útja bármi lehet, bár az első modul elérési út összetevőjének egy ponttal kell rendelkeznie a nevében (a Go jelenlegi verziója már nem érvényesíti, de ha valamivel régebbi verziókat használ, ne lepődjön meg, ha a buildek nem működnek nélküle). Lásd kérdések 37554 és 32819 ha többet szeretne tudni róla.

Ez a projektelrendezés szándékosan általános, és nem próbál meg egy adott Go csomagstruktúrát előírni.

Ez egy közösségi erőfeszítés. Nyisson meg egy problémát, ha új mintát lát, vagy ha úgy gondolja, hogy a meglévő minták egyikét frissíteni kell.

Ha segítségre van szüksége az elnevezéshez, formázáshoz és stílushoz, indítsa el a gofmt és golintfuttatásával. Ügyeljen arra is, hogy olvassa el ezeket a GO code style irányelveket és ajánlásokat:

  • 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
  • stílus útmutató Go csomagok (rakyll/JBD)

lásd Go Project Layout további háttér-információkat.

További információ a csomagok elnevezéséről és szervezéséről, valamint egyéb kódszerkezeti ajánlásokról:

  • GopherCon EU 2018: Peter Bourgon-az ipari programozás legjobb gyakorlatai
  • Gophercon Russia 2018: Ashley McNamara + Brian Ketelsen-Go legjobb gyakorlatok.
  • GopherCon 2017: Edward Muller-Go Anti-Patterns
  • GopherCon 2018: Kat Zien-hogyan strukturálja a Go alkalmazásokat

egy kínai bejegyzés a csomag-orientált tervezési irányelvekről és az építészeti rétegről

  • ++

Go könyvtárak

/cmd

a projekt fő alkalmazásai.

az egyes alkalmazások könyvtárnevének meg kell egyeznie a kívánt futtatható fájl nevével (pl. /cmd/myapp).

ne tegyen sok kódot az alkalmazás könyvtárába. Ha úgy gondolja, hogy a kód importálható és felhasználható más projektekben, akkor a /pkg könyvtárban kell élnie. Ha a kód nem újrafelhasználható, vagy ha nem akarja, hogy mások újra felhasználják, tegye a kódot a /internal könyvtárba. Meg fog lepődni, hogy mások mit fognak tenni, ezért legyen egyértelmű a szándékaival kapcsolatban!

gyakori, hogy van egy kis main függvény, amely importálja és meghívja a kódot a /internal és /pkg könyvtárakból, és semmi más.

lásd a/cmd könyvtár példákat.

/ belső

privát alkalmazás és könyvtár kód. Ez az a kód, amelyet nem szeretne, hogy mások importáljanak alkalmazásaikba vagy könyvtáraikba. Vegye figyelembe, hogy ezt az elrendezési mintát maga a GO fordító hajtja végre. Lásd a Go 1.4 release notes további részletekért. Ne feledje, hogy nem korlátozódik a legfelső szintű internal könyvtárra. Egynél többinternal könyvtár lehet A projektfa bármely szintjén.

opcionálisan hozzáadhat egy kis extra struktúrát a belső csomagokhoz, hogy elkülönítse a megosztott és a nem megosztott belső kódot. Nem szükséges (különösen kisebb projekteknél), de jó, ha vizuális nyomok mutatják a tervezett csomaghasználatot. A tényleges alkalmazás kódja a /internal/app könyvtárban (pl. /internal/app/myapp), valamint az ezen alkalmazások által megosztott kód a /internal/pkg könyvtárban (pl. /internal/pkg/myprivlib) található.

/ pkg

könyvtári kód, amelyet külső alkalmazások (pl., /pkg/mypubliclib). Más projektek importálni fogják ezeket a könyvtárakat, elvárva, hogy működjenek, ezért gondolja át kétszer, mielőtt ide tesz valamit 🙂 vegye figyelembe, hogy a internal könyvtár jobb módja annak, hogy a privát csomagok ne legyenek importálhatók, mert a Go érvényesíti. A /pkg könyvtár még mindig jó módja annak, hogy kifejezetten közöljük, hogy a könyvtárban lévő kód biztonságos mások számára. AI'll take pkg over internal Travis Jeffery blogbejegyzése jó áttekintést nyújt apkg ésinternal könyvtárakról és arról, hogy mikor érdemes használni őket.

Ez is egy módja annak, hogy Csoport Go kódot egy helyen, ha a gyökér könyvtár tartalmaz sok nem-Go komponensek és könyvtárak, így könnyebb futtatni a különböző Go eszközök (mint említettük ezeket a beszélgetéseket: Best Practices for Industrial Programming származó GOPHERCON EU 2018, GopherCon 2018: Kat Zien – hogyan strukturálja a Go Apps és GoLab 2018 – Massimiliano Pippi – Project layout patterns in Go).

lásd a /pkg könyvtárat, ha szeretné látni, hogy mely népszerű Go repók használják ezt a projekt elrendezési mintát. Ez egy általános elrendezési minta, de nem általánosan elfogadott, és a Go közösségben néhányan nem ajánlják.

rendben van, ha nem használja, ha az alkalmazásprojektje valóban kicsi, és ahol egy extra fészkelési szint nem ad sok értéket (kivéve, ha igazán akarod :-)). Gondoljon rá, amikor elég nagy lesz, és a gyökérkönyvtár elég elfoglalt lesz (különösen, ha sok nem Go alkalmazáskomponens van).

/ vendor

Alkalmazásfüggőségek (manuálisan vagy kedvenc függőségkezelő eszközével kezelve, mint például az új beépített Go Modules funkció). A go mod vendor parancs létrehozza a /vendor könyvtárat az Ön számára. Vegye figyelembe, hogy előfordulhat, hogy hozzá kell adnia a -mod=vendor jelzőt a go build parancshoz, ha nem a GO 1.14-et használja, ahol alapértelmezés szerint be van kapcsolva.

ne kövesse el az alkalmazásfüggőségeket, ha könyvtárat épít.

vegye figyelembe, hogy mivel a 1.13 go a modul proxy funkcióját is engedélyezte (alapértelmezés szerint a https://proxy.golang.org modul proxy szerverként). Tudjon meg többet róla here hogy lássa, megfelel-e az összes követelménynek és korlátozásnak. Ha igen, akkor egyáltalán nem lesz szüksége a vendor könyvtárra.

szolgáltatási Alkalmazáskönyvtárak

/api

OpenAPI/Swagger SPECIFIKÁCIÓK, JSON séma fájlok, protokolldefiníciós fájlok.

lásd a/api könyvtár példákat.

webalkalmazás-könyvtárak

/web

webalkalmazás-specifikus összetevők: statikus webes eszközök, szerveroldali sablonok és gyógyfürdők.

gyakori Alkalmazáskönyvtárak

/configs

konfigurációs fájlsablonok vagy alapértelmezett konfigurációk.

tegye ide aconfd vagyconsul-template sablonfájlokat.

/ init

System init (systemd, upstart, sysv) és process manager/supervisor (runit, supervisord) konfigurációk.

/ scripts

szkriptek különböző build, install, analysis, stb Műveletek végrehajtásához.

Ezek a szkriptek A gyökérszintű Makefile-t kicsinek és egyszerűnek tartják (pl. https://github.com/hashicorp/terraform/blob/master/Makefile).

lásd a/scripts könyvtár példákat.

/build

csomagolás és folyamatos integráció.

tegye a felhő (AMI), konténer (Docker), OS (deb, rpm, pkg) csomagkonfigurációkat és parancsfájlokat a/build/package könyvtárba.

tegye a CI (travis, circle, drone) konfigurációkat és parancsfájlokat a /build/ci könyvtárba. Vegye figyelembe, hogy egyes CI eszközök (pl., Travis CI) nagyon válogatós a konfigurációs fájlok helyét illetően. Próbálja meg a konfigurációs fájlokat a /build/ci könyvtárba helyezni, amely összekapcsolja őket azzal a hellyel, ahol a CI eszközök elvárják őket (ha lehetséges).

/ telepítések

IaaS, PaaS, rendszer – és konténerszervezési telepítési konfigurációk és sablonok (docker-compose, kubernetes/helm, mesos, terraform, bosh). Vegye figyelembe, hogy egyes repókban (különösen a kubernetes-szel telepített alkalmazásokban) ez a könyvtár /deploy.

/ test

további külső tesztalkalmazások és tesztadatok. Nyugodtan strukturálja a /test könyvtárat, amit csak akar. Nagyobb projektek esetén érdemes egy adat alkönyvtárat létrehozni. Például lehet /test/data vagy /test/testdata ha figyelmen kívül szeretné hagyni, hogy mi van abban a könyvtárban. Ne feledje, hogy a Go figyelmen kívül hagyja a “.”vagy”_”, így nagyobb rugalmassággal rendelkezik a tesztadatok könyvtárának megnevezése szempontjából.

lásd a/test könyvtár példákat.

Egyéb könyvtárak

/docs

tervezési és felhasználói dokumentumok (a godoc által generált dokumentáción kívül).

lásd a/docs könyvtár példákat.

/ eszközök

támogató eszközök ehhez a projekthez. Vegye figyelembe, hogy ezek az eszközök a /pkg és /internal könyvtárakból importálhatnak kódot.

lásd a/tools könyvtár példákat.

/ példák

példák az alkalmazásokhoz és/vagy a nyilvános könyvtárakhoz.

lásd a/examples könyvtár példákat.

/ third_party

külső segítő eszközök, villás kód és egyéb 3rd party segédprogramok (pl. Swagger UI).

/ githooks

Git hooks.

/ eszközök

egyéb eszközök a tárolóval együtt (képek, logók stb.).

/ website

Ez az a hely, ahol elhelyezheti a projekt webhelyadatait, ha nem használja a GitHub oldalakat.

lásd a/website könyvtár példákat.

könyvtárak nem kellett volna

/ src

néhány Go projektnek van egysrc mappája, de ez általában akkor történik, amikor a fejlesztők a Java világból származnak, ahol ez egy közös minta. Ha tudsz segíteni magadnak, próbáld meg nem elfogadni ezt a Java mintát. Nem akarod, hogy a Go kódod vagy a Go projektjeid úgy nézzenek ki, mint a Java 🙂

ne keverd össze a /src könyvtárat a /src könyvtárral, amelyet a GO használ a munkaterületeihez a How to Write Go Codealatt leírtak szerint. A$GOPATH környezeti változó a (jelenlegi) munkaterületre mutat (alapértelmezés szerint a$HOME/go nem windows rendszereken). Ez a munkaterület tartalmazza a legfelső szintű/pkg/bin és/src könyvtárakat. A tényleges projekt végül egy alkönyvtár lesz a /src alatt, tehát ha a /src könyvtár van a projektben, a Projekt elérési útja a következőképpen fog kinézni: /some/path/to/workspace/src/your_project/src/your_code.go. Vegye figyelembe, hogy a Go 1.11 lehetséges, hogy a projekt kívül a GOPATH, de ez még mindig nem jelenti azt, hogy ez egy jó ötlet, hogy használja ezt az elrendezési mintát.

jelvények

  • Go jelentés kártya – ez beolvassa a kódot gofmtgo vetgocyclogolintgolintlicenseés misspell. Cserélje le agithub.com/golang-standards/project-layout elemet a projekt referenciájára.

    Go jelentés kártya

  • GoDoc – ez biztosítja az online változata a GoDoc generált dokumentáció. Módosítsa a linket, hogy a projektre mutasson.

    Go Doc

  • Pkg.menj.dev-Pkg.menj.a dev a Go discovery új célpontja & docs. A jelvényt a jelvénygeneráló eszköz segítségével hozhat létre.

    PkgGoDev

  • Release – megmutatja a projekt legújabb kiadási számát. Módosítsa a github linket, hogy a projektre mutasson.

    Release

Megjegyzések

egy véleményesebb projektsablon minta/újrafelhasználható konfigurációkkal, szkriptekkel és kódokkal egy WIP.

Vélemény, hozzászólás?

Az e-mail-címet nem tesszük közzé.