golang-normy / projekt-rozložení

Překlady:

  • 한국어 문서
  • zjednodušená čínština
  • 正體中文
  • 简体 中文 – ???
  • Français
  • 日本語
  • angličtina
  • Español

Přehled

Toto je základní rozvržení pro Go aplikace projekty. Není to oficiální standard definovaný týmem core Go dev; jedná se však o soubor společných historických a vznikajících vzorů rozvržení projektu v ekosystému Go. Některé z těchto vzorů jsou populárnější než jiné. Má také řadu malých vylepšení spolu s několika podpůrnými adresáři společnými pro všechny dostatečně velké aplikace v reálném světě.

Pokud se snažíte naučit jít, nebo pokud stavíte PoC nebo hračka projekt pro sebe toto rozvržení projektu je zbytečná. Začněte něčím opravdu jednoduchým (jediný soubor main.go je více než dost). Jak váš projekt roste, mějte na paměti, že bude důležité zajistit, aby byl váš kód dobře strukturovaný, jinak skončíte s chaotickým kódem se spoustou skrytých závislostí a globálním stavem. Když na projektu pracuje více lidí, budete potřebovat ještě větší strukturu. Tehdy je důležité zavést běžný způsob správy balíčků / knihoven. Pokud máte projekt s otevřeným zdrojovým kódem nebo pokud znáte jiné projekty, importujte kód z úložiště projektu, kdy je důležité mít soukromé balíčky a kód (aka internal). Klonujte úložiště, Udržujte to, co potřebujete, a smažte vše ostatní! Jen proto, že je tam to neznamená, že budete muset použít všechno. Žádný z těchto vzorů se nepoužívá v každém projektu. Ani vzor vendor není univerzální.

S Go 1.14 Go Modules jsou konečně připraveny k výrobě. Použijte Go Modules pokud nemáte konkrétní důvod je nepoužívat a pokud tak učiníte, nemusíte se starat o $GOPATH a kam svůj projekt umístíte. Základní go.mod soubor v repo předpokládá, že váš projekt je hostován na Githubu, ale není to podmínkou. Modul cesta může být cokoliv, i když první modul cesta složky by měly mít tečku v názvu (aktuální verze Go nebude prosazovat to už, ale pokud používáte něco starší verze nebuďte překvapeni, pokud vaše sestavení se nezdaří bez něj). Viz Issues 37554 a 32819 pokud se o tom chcete dozvědět více.

toto rozvržení projektu je záměrně obecné a nesnaží se uložit konkrétní strukturu balíčku Go.

Toto je komunitní úsilí. Otevřete problém, pokud vidíte nový vzor nebo si myslíte, že je třeba aktualizovat jeden ze stávajících vzorů.

Pokud potřebujete pomoc s pojmenováním, formátováním a stylem, začněte spuštěním gofmt a golint. Také si přečtěte tyto pokyny a doporučení stylu Go kódu:

  • 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
  • Styl pokyn pro balení (rakyll/JBD)

Go Project Layout další informace o pozadí.

Více o pojmenování a organizování balíčky, stejně jako ostatní struktury kódu doporučení:

  • GopherCon EU 2018: Peter Bourgon – Nejlepší Praktiky pro Průmyslové Programování
  • GopherCon Rusko 2018: Ashley McNamara + Brian Ketelsen – Go osvědčených postupů.
  • GopherCon 2017: Edward Muller – Go Anti-Vzory
  • GopherCon 2018: Kat Zien – Jak Si Strukturovat Vaše Go Aplikací

Čínský Příspěvek o Balíček Orientované-pokyny Designu a Architektury vrstvy,

  • 面向包的设计和架构分层

Adresáře

/cmd

Hlavní aplikací pro tento projekt.

název adresáře pro každou aplikaci by měl odpovídat název spustitelného souboru, který chcete mít (např. /cmd/myapp).

nedávejte do adresáře aplikace Mnoho kódu. Pokud si myslíte, že kód lze importovat a použít v jiných projektech, měl by žít v adresáři /pkg. Pokud kód není opakovaně použitelný nebo pokud nechcete, aby ho ostatní znovu použili, vložte tento kód do adresáře /internal. Budete překvapeni, co ostatní budou dělat, takže buďte výslovní ohledně svých záměrů!

je běžné mít malou main funkce, která dovozu a vyvolá kód /internal/pkg adresáře a nic jiného.

viz /cmd adresář pro příklady.

/ interní

kód soukromé aplikace a knihovny. Toto je kód, který nechcete, aby ostatní importovali do svých aplikací nebo knihoven. Všimněte si, že tento vzor rozvržení je vynucen samotným kompilátorem Go. Viz go 1.4 release notes pro více informací. Všimněte si, že nejste omezeni na nejvyšší úroveň internal adresář. Můžete mít více než jeden internal adresář na libovolné úrovni stromu projektu.

Volitelně můžete do svých interních balíčků přidat trochu zvláštní struktury, abyste oddělili sdílený a nesdílený interní kód. Není to nutné (zejména u menších projektů), ale je hezké mít vizuální stopy ukazující zamýšlené použití balíčku. Váš skutečný kód aplikace, můžete jít do /internal/app adresář (např. /internal/app/myapp) a kód sdílí tyto aplikace v /internal/pkg adresář (např. /internal/pkg/myprivlib).

/ pkg

kód knihovny, který lze použít externími aplikacemi (např., /pkg/mypubliclib). Další projekty budou importovat tyto knihovny očekával, že jim do práce, takže myslíte, že dvakrát předtím, než si dát něco tady 🙂 Všimněte si, že internal adresář je lepší způsob, jak zajistit, aby vaše vlastní balíčky nejsou dovážet, protože je vynuceno Jít. Adresář /pkg je stále dobrým způsobem, jak explicitně sdělit, že kód v tomto adresáři je bezpečný pro použití ostatními. I'll take pkg over internal blog post Travis Jeffery poskytuje dobrý přehled o pkginternal adresáře a když to dává smysl, aby jejich použití.

je To také způsob, jak skupina kód na jednom místě, když váš kořenový adresář obsahuje mnoho non-Go složek a adresářů, takže je snazší pro spuštění různých nástrojů (jak je uvedeno v těchto jednáních: Best Practices for Industrial Programming od GopherCon EU 2018, GopherCon 2018: Kat Zien – Jak Si Strukturovat Vaše Go Aplikací a GoLab 2018 – Massimiliano Pippi – Projekt rozvržení vzorů v Go).

viz /pkg adresář, pokud chcete vidět, které populární go repo používají tento vzor rozvržení projektu. Toto je běžný vzor rozvržení, ale není všeobecně přijímán a někteří v komunitě Go to nedoporučují.

je v pořádku ji nepoužívat, pokud je váš projekt aplikace opravdu malý a kde další úroveň hnízdění nepřidává velkou hodnotu (pokud opravdu nechcete: -)). Přemýšlejte o tom, když je dost velký a váš kořenový adresář je docela zaneprázdněn (zvláště pokud máte spoustu komponent aplikací, které nejsou go).

/ vendor

závislosti aplikací (spravované ručně nebo vaším oblíbeným nástrojem pro správu závislostí, jako je nová Vestavěná funkce Go Modules). Příkaz go mod vendor vytvoří pro vás adresář /vendor. Vědomí, že možná budete muset přidat -mod=vendor vlajky go build command, pokud nepoužíváte Jít 1.14, kde je ve výchozím nastavení.

neprovádějte závislosti aplikací, pokud vytváříte knihovnu.

Všimněte si, že jelikož 1.13 Go také povoleno modulu proxy (pomocí https://proxy.golang.org jako jejich modul proxy server ve výchozím nastavení). Přečtěte si více o tom here a zjistěte, zda vyhovuje všem vašim požadavkům a omezením. Pokud ano, pak nebudete potřebovat vendor adresář vůbec.

servisní adresáře aplikací

/ api

OpenAPI / Swagger SPECIFIKACE, soubory schématu JSON, soubory definice protokolu.

viz/api adresář pro příklady.

adresáře webových aplikací

/ web

komponenty specifické pro webové aplikace: statická webová aktiva, šablony na straně serveru a Lázně.

běžné adresáře aplikací

/ configs

šablony konfiguračních souborů nebo výchozí configs.

confd nebo consul-template template soubory.

/ init

konfigurace System init (systemd, upstart, sysv) a process manager/supervisor (runit, supervisord).

/ skripty

skripty pro provádění různých operací sestavení, instalace, analýzy atd.

tyto skripty udržují kořenovou úroveň Makefile malou a jednoduchou (např. https://github.com/hashicorp/terraform/blob/master/Makefile).

viz /scripts adresář pro příklady.

/ build

balení a kontinuální integrace.

Dát vaše cloud (AMI), kontejner (Docker), OS (deb, rpm, pkg) balíček konfigurace a skripty v /build/package adresář.

vložte konfigurace a skripty CI (travis, circle, drone) do adresáře /build/ci. Všimněte si, že některé z nástrojů CI (např., Travis CI) jsou velmi vybíraví ohledně umístění svých konfiguračních souborů. Zkuste umístit konfigurační soubory do adresáře /build/ci, který je spojuje s umístěním, kde je Nástroje CI očekávají (pokud je to možné).

/ nasazení

konfigurace a šablony nasazení IaaS, PaaS, systémové a kontejnerové orchestrace (docker-compose, kubernetes/helm, mesos, terraform, bosh). Všimněte si, že v některých repozitářích (zejména v aplikacích nasazených s kubernetes) se tento adresář nazývá /deploy.

/ test

další externí testovací aplikace a testovací data. Neváhejte strukturovat /test adresář, který chcete. Pro větší projekty má smysl mít podadresář dat. Například můžete mít /test/data nebo /test/testdata pokud potřebujete ignorovat, co je v tomto adresáři. Všimněte si, že Go bude také ignorovat adresáře nebo soubory, které začínají”.”nebo”_”, Takže máte větší flexibilitu, pokud jde o to, jak pojmenujete adresář testovacích dat.

viz /test adresář pro příklady.

Ostatní adresáře

/ dokumenty

Design a uživatelské dokumenty (kromě vaší dokumentace generované godoc).

viz /docs adresář pro příklady.

/ nástroje

Podpůrné nástroje pro tento projekt. Všimněte si, že tyto nástroje mohou importovat kód z adresářů /pkg a /internal.

viz/tools adresář pro příklady.

/ příklady

příklady pro vaše aplikace a / nebo veřejné knihovny.

viz /examples adresář pro příklady.

/ third_party

externí pomocné nástroje, vidlicový kód a další nástroje 3rd party (např.

/githooks

git hooks.

/ aktiva

další aktiva, která mají jít spolu s úložištěm (obrázky, loga atd.).

/ website

Toto je místo, kde můžete umístit data webových stránek vašeho projektu, pokud nepoužíváte stránky GitHub.

viz /website adresář pro příklady.

Adresáře, Neměli Byste Mít

/src

Některé projekty mají src složky, ale to se obvykle stane, když vývojáři přišli z Java světa, kde je to společný vzor. Pokud si můžete pomoci sami, zkuste tento vzor Java nepřijmout. Opravdu nechci Go kód, nebo Jít projektů, aby vypadal jako Java 🙂

nepleťte úrovni projektu /src adresář /src adresář Jít používá pro jeho pracovní plochy, jak je popsáno v How to Write Go Code. Proměnná prostředí $GOPATH ukazuje na váš (aktuální) pracovní prostor (ve výchozím nastavení ukazuje na $HOME/go v systémech jiných než windows). Tento pracovní prostor obsahuje nejvyšší úrovni /pkg/bin/src adresáře. Váš aktuální projekt skončí jako sub-adresáře pod /src takže pokud máte /src adresář ve vašem projektu projekt cesta bude vypadat takto: /some/path/to/workspace/src/your_project/src/your_code.go. Všimněte si, že s Go 1.11 je možné mít váš projekt mimo GOPATH, ale stále to neznamená, že je vhodné použít tento vzor rozvržení.

Odznaky

  • Jdi vysvědčení – To prohledá váš kód gofmtgo vetgocyclogolintineffassignlicensemisspell. Nahraďte github.com/golang-standards/project-layout odkazem na váš projekt.

    Go Report Card

  • GoDoc-poskytne online verzi vaší dokumentace generované GoDoc. Změňte odkaz na odkaz na váš projekt.

    Go Doc

  • Pkg.přejít.dev-Pkg.přejít.dev je nový cíl pro Go discovery & docs. Odznak můžete vytvořit pomocí nástroje pro generování odznaků.

    PkgGoDev

  • Release-zobrazí nejnovější číslo vydání pro váš projekt. Změňte odkaz na github a přejděte na svůj projekt.

    Zpráva

Poznámky

více tvrdohlavý šablona projektu s vzorek/opakovaně použitelných konfigurační soubory, skripty a kód je WIP.

Napsat komentář

Vaše e-mailová adresa nebude zveřejněna.