golang-standards / projektlayout

Übersetzungen:

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

Übersicht

Dies ist ein Grundlayout für Go-Anwendungsprojekte. Es ist kein offizieller Standard, der vom Kernteam der Go-Entwickler definiert wird; Es ist jedoch eine Reihe gemeinsamer historischer und aufkommender Projektlayoutmuster im Go-Ökosystem. Einige dieser Muster sind beliebter als andere. Es hat auch eine Reihe von kleinen Verbesserungen zusammen mit mehreren unterstützenden Verzeichnissen, die jeder groß genug realen Anwendung gemeinsam sind.

Wenn Sie versuchen, Go zu lernen, oder wenn Sie ein PoC- oder Spielzeugprojekt für sich selbst erstellen, ist dieses Projektlayout ein Overkill. Beginnen Sie mit etwas wirklich Einfachem (eine einzelne main.go -Datei ist mehr als genug). Wenn Ihr Projekt wächst, denken Sie daran, dass es wichtig ist, sicherzustellen, dass Ihr Code gut strukturiert ist, da Sie sonst einen unordentlichen Code mit vielen versteckten Abhängigkeiten und einem globalen Status erhalten. Wenn mehr Leute an dem Projekt arbeiten, brauchen Sie noch mehr Struktur. Dann ist es wichtig, einen gemeinsamen Weg zur Verwaltung von Paketen / Bibliotheken einzuführen. Wenn Sie ein Open-Source-Projekt haben oder wissen, dass andere Projekte den Code aus Ihrem Projektrepository importieren, ist es wichtig, private Pakete und Code (auch bekannt als internal) zu haben. Klonen Sie das Repository, behalten Sie, was Sie brauchen, und löschen Sie alles andere! Nur weil es da ist, heißt das nicht, dass du alles benutzen musst. Keines dieser Muster wird in jedem einzelnen Projekt verwendet. Selbst das vendor -Muster ist nicht universell.

Mit Go 1.14 Go Modules sind endlich bereit für die Produktion. Verwenden Sie Go Modules es sei denn, Sie haben einen bestimmten Grund, sie nicht zu verwenden. Die grundlegende go.mod -Datei im Repo setzt voraus, dass Ihr Projekt auf GitHub gehostet wird, ist jedoch keine Voraussetzung. Der Modulpfad kann alles sein, obwohl die erste Modulpfadkomponente einen Punkt im Namen haben sollte (die aktuelle Version von Go erzwingt ihn nicht mehr, aber wenn Sie etwas ältere Versionen verwenden, wundern Sie sich nicht, wenn Ihre Builds ohne ihn fehlschlagen). Siehe Probleme 37554 und 32819 wenn Sie mehr darüber erfahren möchten.

Dieses Projektlayout ist absichtlich generisch und versucht nicht, eine bestimmte Go-Paketstruktur aufzuerlegen.

Dies ist eine Gemeinschaftsanstrengung. Öffnen Sie ein Problem, wenn Sie ein neues Muster sehen oder wenn Sie der Meinung sind, dass eines der vorhandenen Muster aktualisiert werden muss.

Wenn Sie Hilfe bei der Benennung, Formatierung und Formatierung benötigen, starten Sie gofmt und golint. Lesen Sie auch diese Richtlinien und Empfehlungen für den 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
  • akyll/JBD)

Siehe Go Project Layout für weitere Hintergrundinformationen.

Mehr über die Benennung und Organisation von Paketen sowie andere Empfehlungen zur Codestruktur:

  • GopherCon EU 2018: Peter Bourgon – Best Practices für die industrielle Programmierung
  • GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen – Go Best Practices.
  • GopherCon 2017: Edward Muller – Go Anti-Patterns
  • GopherCon 2018: Kat Zien – Wie strukturieren Sie Ihre Go-Apps

Ein chinesischer Beitrag über paketorientierte Designrichtlinien und Architekturebene

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

Go-Verzeichnisse

/cmd

Hauptanwendungen für dieses Projekt.

Der Verzeichnisname für jede Anwendung sollte mit dem Namen der ausführbaren Datei übereinstimmen, die Sie haben möchten (z. B. /cmd/myapp ).

Legen Sie nicht viel Code in das Anwendungsverzeichnis. Wenn Sie der Meinung sind, dass der Code importiert und in anderen Projekten verwendet werden kann, sollte er sich im Verzeichnis /pkg befinden. Wenn der Code nicht wiederverwendbar ist oder wenn Sie nicht möchten, dass andere ihn wiederverwenden, legen Sie diesen Code in das Verzeichnis /internal . Sie werden überrascht sein, was andere tun werden, also seien Sie explizit über Ihre Absichten!

Es ist üblich, eine kleine main Funktion zu haben, die den Code aus den /internal und /pkg Verzeichnissen importiert und aufruft und sonst nichts.

Siehe das /cmd Verzeichnis für Beispiele.

/intern

Privater Anwendungs- und Bibliothekscode. Dies ist der Code, den andere nicht in ihre Anwendungen oder Bibliotheken importieren sollen. Beachten Sie, dass dieses Layoutmuster vom Go-Compiler selbst erzwungen wird. Siehe Go 1.4 release notes für weitere Details. Beachten Sie, dass Sie nicht auf das internal Verzeichnis der obersten Ebene beschränkt sind. Sie können mehr als ein internal Verzeichnis auf jeder Ebene Ihres Projektbaums haben.

Sie können Ihren internen Paketen optional eine zusätzliche Struktur hinzufügen, um Ihren gemeinsam genutzten und nicht gemeinsam genutzten internen Code zu trennen. Es ist nicht erforderlich (insbesondere für kleinere Projekte), aber es ist schön, visuelle Hinweise zu haben, die die beabsichtigte Verwendung des Pakets anzeigen. Ihr tatsächlicher Anwendungscode befindet sich im Verzeichnis /internal/app (z. B. /internal/app/myapp) und der von diesen Apps freigegebene Code im Verzeichnis /internal/pkg (z. B. /internal/pkg/myprivlib).

/pkg

Bibliothekscode, der von externen Anwendungen (z., /pkg/mypubliclib). Denken Sie also zweimal darüber nach, bevor Sie hier etwas einfügen 🙂 Beachten Sie, dass das Verzeichnis internal eine bessere Möglichkeit ist, sicherzustellen, dass Ihre privaten Pakete nicht importiert werden können, da dies von Go erzwungen wird. Das Verzeichnis /pkg ist immer noch eine gute Möglichkeit, explizit mitzuteilen, dass der Code in diesem Verzeichnis für andere sicher ist. Der I'll take pkg over internal Blogbeitrag von Travis Jeffery gibt einen guten Überblick über die pkg und internal Verzeichnisse und wann es sinnvoll sein könnte, sie zu verwenden.

Es ist auch eine Möglichkeit, Go-Code an einem Ort zu gruppieren, wenn Ihr Stammverzeichnis viele Nicht-Go-Komponenten und -Verzeichnisse enthält, die es einfacher machen, verschiedene Go-Tools auszuführen (wie in diesen Vorträgen erwähnt: Best Practices for Industrial Programming von GopherCon EU 2018, GopherCon 2018: Kat Zien – Wie strukturieren Sie Ihre Go-Apps und GoLab 2018 – Massimiliano Pippi – Projektlayoutmuster in Go).

Sehen Sie sich das /pkg -Verzeichnis an, wenn Sie sehen möchten, welche beliebten Go-Repos dieses Projektlayoutmuster verwenden. Dies ist ein gängiges Layoutmuster, das jedoch nicht allgemein akzeptiert wird und von einigen in der Go-Community nicht empfohlen wird.

Es ist in Ordnung, es nicht zu verwenden, wenn Ihr App-Projekt wirklich klein ist und eine zusätzliche Verschachtelungsebene nicht viel Wert hinzufügt (es sei denn, Sie möchten es wirklich :-)). Denken Sie darüber nach, wenn es groß genug wird und Ihr Stammverzeichnis ziemlich beschäftigt ist (insbesondere wenn Sie viele Nicht-Go-App-Komponenten haben).

/vendor

Anwendungsabhängigkeiten (manuell verwaltet oder von Ihrem bevorzugten Abhängigkeitsverwaltungstool wie dem neuen integrierten Go Modules -Feature). Der Befehl go mod vendor erstellt das Verzeichnis /vendor für Sie. Beachten Sie, dass Sie möglicherweise das Flag -mod=vendor zu Ihrem Befehl go build hinzufügen müssen, wenn Sie Go 1.14 nicht verwenden, wo es standardmäßig aktiviert ist.

Schreiben Sie Ihre Anwendungsabhängigkeiten nicht fest, wenn Sie eine Bibliothek erstellen.

Beachten Sie, dass Go seit 1.13 auch die Modul-Proxy-Funktion aktiviert hat (standardmäßig https://proxy.golang.org als Modul-Proxy-Server). Lesen Sie mehr darüber here um zu sehen, ob es alle Ihre Anforderungen und Einschränkungen erfüllt. Wenn dies der Fall ist, benötigen Sie das Verzeichnis vendor überhaupt nicht.

Dienstanwendungsverzeichnisse

/api

OpenAPI / Swagger-Spezifikationen, JSON-Schemadateien, Protokolldefinitionsdateien.

Siehe das /api Verzeichnis für Beispiele.

Webanwendungsverzeichnisse

/web

Webanwendungsspezifische Komponenten: statische Web-Assets, serverseitige Vorlagen und SPAs.

Allgemeine Anwendungsverzeichnisse

/configs

Konfigurationsdateivorlagen oder Standardkonfigurationen.

Legen Sie hier Ihre confd oder consul-template Vorlagendateien ab.

/init

Systeminitkonfigurationen (systemd, Upstart, sysv) und Prozessmanager/Supervisor (runit, supervisord).

/scripts

Skripte zum Ausführen verschiedener Build-, Installations-, Analyse- usw.-Vorgänge.

Diese Skripte halten das Makefile auf Root-Ebene klein und einfach (z. B. https://github.com/hashicorp/terraform/blob/master/Makefile ).

Siehe das /scripts Verzeichnis für Beispiele.

/build

Verpackung und kontinuierliche Integration.

Legen Sie Ihre Cloud (AMI), Container (Docker), OS (deb, rpm, pkg) Paketkonfigurationen und Skripte im /build/package Verzeichnis ab.

Legen Sie Ihre CI (travis, circle, drone) Konfigurationen und Skripte in das /build/ci Verzeichnis. Beachten Sie, dass einige der CI-Tools (z., Travis CI) sind sehr wählerisch in Bezug auf den Speicherort ihrer Konfigurationsdateien. Versuchen Sie, die Konfigurationsdateien in das Verzeichnis /build/ci zu stellen, das sie mit dem Speicherort verknüpft, an dem die CI-Tools sie erwarten (wenn möglich).

/Bereitstellungen

IaaS-, PaaS-, System- und Container-Orchestrierungs-Bereitstellungskonfigurationen und -vorlagen (Docker-compose, kubernetes/helm, mesos, Terraform, bosh). Beachten Sie, dass dieses Verzeichnis in einigen Repos (insbesondere mit Kubernetes bereitgestellten Apps) /deploy .

/test

Zusätzliche externe Test-Apps und Testdaten. Sie können das /test -Verzeichnis beliebig strukturieren. Für größere Projekte ist es sinnvoll, ein Datenunterverzeichnis zu haben. Sie können beispielsweise /test/data oder /test/testdata wenn Sie Go ignorieren möchten, was sich in diesem Verzeichnis befindet. Beachten Sie, dass Go auch Verzeichnisse oder Dateien ignoriert, die mit ” beginnen.” oder “_”, sodass Sie mehr Flexibilität bei der Benennung Ihres Testdatenverzeichnisses haben.

Siehe das /test Verzeichnis für Beispiele.

Andere Verzeichnisse

/docs

Design- und Benutzerdokumente (zusätzlich zu Ihrer von godoc generierten Dokumentation).

Siehe das /docs Verzeichnis für Beispiele.

/tools

Unterstützende Tools für dieses Projekt. Beachten Sie, dass diese Tools Code aus den Verzeichnissen /pkg und /internal importieren können.

Beispiele finden Sie im /tools Verzeichnis.

/examples

Beispiele für Ihre Anwendungen und/oder öffentlichen Bibliotheken.

Siehe das /examples Verzeichnis für Beispiele.

/third_party

Externe Hilfsprogramme, gegabelter Code und andere 3rd-Party-Dienstprogramme (z. B. Swagger UI).

/githooks

Git Haken.

/assets

Andere Assets, die zu Ihrem Repository gehören (Bilder, Logos usw.).

/website

Hier können Sie die Website-Daten Ihres Projekts ablegen, wenn Sie GitHub Pages nicht verwenden.

Siehe das /website Verzeichnis für Beispiele.

Verzeichnisse, die Sie nicht haben sollten

/src

Einige Go-Projekte haben einen src Ordner, aber es passiert normalerweise, wenn die Entwickler aus der Java-Welt kamen, wo es ein gemeinsames Muster ist. Wenn Sie sich selbst helfen können, versuchen Sie, dieses Java-Muster nicht zu übernehmen. Sie möchten wirklich nicht, dass Ihr Go-Code oder Ihre Go-Projekte wie Java aussehen 🙂

Verwechseln Sie nicht das /src -Verzeichnis auf Projektebene mit dem /src -Verzeichnis, das Go für seine Arbeitsbereiche verwendet, wie in How to Write Go Code beschrieben. Die Umgebungsvariable $GOPATH zeigt auf Ihren (aktuellen) Arbeitsbereich (standardmäßig auf $HOME/go auf Nicht-Windows-Systemen). Dieser Arbeitsbereich enthält die Verzeichnisse der obersten Ebene /pkg/bin und /src. Ihr tatsächliches Projekt endet als Unterverzeichnis unter /src , wenn Sie also das Verzeichnis /src in Ihrem Projekt haben, sieht der Projektpfad folgendermaßen aus: /some/path/to/workspace/src/your_project/src/your_code.go. Beachten Sie, dass mit Go 1.11 es ist möglich, Ihr Projekt außerhalb Ihres GOPATH , aber es bedeutet immer noch nicht, dass es eine gute Idee ist, dieses Layoutmuster zu verwenden.

Abzeichen

  • Go Report Card – Es wird Ihren Code scannen mit gofmtgo vetgocyclogolintineffassignlicense und misspell. Ersetzen Sie github.com/golang-standards/project-layout durch Ihre Projektreferenz.

    Go Report Card

  • GoDoc – Es wird eine Online-Version Ihrer von GoDoc generierten Dokumentation bereitgestellt. Ändern Sie den Link, um auf Ihr Projekt zu verweisen.

    Gehe zu Doc

  • Pkg.gehen.dev – Pkg.gehen.dev ist ein neues Ziel für Go discovery & docs . Sie können ein Abzeichen mit dem Tool zum Generieren von Abzeichen erstellen.

    PkgGoDev

  • Release – Es wird die neueste Release-Nummer für Ihr Projekt angezeigt. Ändern Sie den Github-Link, um auf Ihr Projekt zu verweisen.

    Release

Hinweise

Eine eher eigenwillige Projektvorlage mit Beispiel- / wiederverwendbaren Konfigurationen, Skripten und Code ist ein WIP.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.