golang-normen / project-lay-out

Vertalingen:

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

overzicht

Dit is een basisopmaak voor GO-toepassingsprojecten. Het is geen officiële standaard gedefinieerd door de core Go dev team; echter, het is een set van gemeenschappelijke historische en opkomende project lay-out patronen in de go ecosysteem. Sommige van deze patronen zijn populairder dan anderen. Het heeft ook een aantal kleine verbeteringen, samen met een aantal ondersteunende directory ‘ s gemeenschappelijk voor een groot genoeg real world applicatie.

als je Go probeert te leren of als je een PoC of een toy project voor jezelf aan het bouwen bent, is deze projectopmaak een overkill. Begin met iets heel simpels (een enkel main.go bestand is meer dan genoeg). Als uw project groeit in gedachten houden dat het belangrijk zal zijn om ervoor te zorgen dat uw code is goed gestructureerd anders zul je eindigen met een rommelige code met veel verborgen afhankelijkheden en globale staat. Als er meer mensen aan het project werken, heb je nog meer structuur nodig. Dat is wanneer het belangrijk is om een gemeenschappelijke manier te introduceren om pakketten/bibliotheken te beheren. Als je een open source project hebt of als je weet dat andere projecten de code importeren uit je project repository dan is het belangrijk om private (aka internal) pakketten en code te hebben. Kloon de repository, Houd wat je nodig hebt en verwijder al het andere! Het is niet omdat het er is dat je alles moet gebruiken. Geen van deze patronen worden in elk project gebruikt. Zelfs hetvendor patroon is niet universeel.

met Go 1.14 Go Modules zijn eindelijk klaar voor productie. Gebruik Go Modules tenzij je een specifieke reden hebt om ze niet te gebruiken en als je dat doet dan hoef je je geen zorgen te maken over $GOPATH en waar je je project zet. Het basis go.mod bestand in de repo neemt aan dat je project gehost wordt op GitHub, maar het is geen vereiste. Het module pad kan van alles zijn hoewel de eerste module pad component een punt in zijn naam zou moeten hebben (de huidige versie van Go dwingt het niet meer af, maar als je iets oudere versies gebruikt, wees dan niet verbaasd als je builds falen zonder dat). Zie Issues 37554 en 32819 Als u er meer over wilt weten.

Deze projectopmaak is opzettelijk generiek en het probeert geen specifieke Go-pakketstructuur op te leggen.

Dit is een communautaire inspanning. Open een probleem als u een nieuw patroon ziet of als u denkt dat een van de bestaande patronen moet worden bijgewerkt.

Als u hulp nodig hebt met naamgeving, opmaak en stijl start met gofmt en golint. Zorg er ook voor om deze Go code style richtlijnen en aanbevelingen te lezen:

  • 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
  • Stijl richtsnoer voor Go pakketten (rakyll/JBD)

Zie Go Project Layout voor meer achtergrond informatie.

meer over het benoemen en organiseren van pakketten en andere codestructuuraanbevelingen:

  • GopherCon EU 2018: Peter Bourgon – Best Practices for Industrial Programming
  • GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen – Go best practices.
  • GopherCon 2017: Edward Muller-Go Anti-Patterns
  • GopherCon 2018: Kat Zien-How Do You Structure Your Go Apps

a Chinese Post about Package-Oriented-Design guidelines and Architecture layer

  • Go directory ‘ s

    /cmd

    Hoofdtoepassingen voor dit project.

    de mapnaam voor elke toepassing moet overeenkomen met de naam van het uitvoerbare bestand dat u wilt hebben (bijvoorbeeld /cmd/myapp).

    plaats niet veel code in de toepassingsmap. Als je denkt dat de code geïmporteerd en gebruikt kan worden in andere projecten, dan zou het in de /pkg directory moeten staan. Als de code niet herbruikbaar is of als je niet wilt dat anderen het hergebruiken, plaats die code in de /internal map. U zult verrast zijn wat anderen zullen doen, dus wees expliciet over uw intenties!

    Het is gebruikelijk om een kleine main functie te hebben die de code importeert en aanroept vanuit de /internal en /pkg mappen en niets anders.

    zie de /cmd map voor voorbeelden.

    / interne

    private toepassing en bibliotheek code. Dit is de code die je niet wilt dat anderen importeren in hun applicaties of bibliotheken. Merk op dat dit opmaakpatroon wordt afgedwongen door de go compiler zelf. Zie de Go 1.4 release notes voor meer details. Merk op dat u niet beperkt bent tot de map internal. U kunt meer dan één internal map hebben op elk niveau van uw projectboom.

    u kunt optioneel een beetje extra structuur toevoegen aan uw interne pakketten om uw gedeelde en niet-gedeelde interne code te scheiden. Het is niet nodig (vooral voor kleinere projecten), maar het is leuk om visuele aanwijzingen te hebben die het beoogde gebruik van het pakket laten zien. Uw eigenlijke toepassingscode kan in de /internal/app map (bijvoorbeeld /internal/app/myapp) en de code die door deze apps wordt gedeeld in de /internal/pkg map (bijvoorbeeld /internal/pkg/myprivlib).

    /pkg

    Bibliotheekcode die mag worden gebruikt door externe toepassingen (bijv., /pkg/mypubliclib). Andere projecten zullen deze bibliotheken importeren die verwachten dat ze werken, dus denk twee keer na voordat je hier iets plaatst 🙂 merk op dat de internal map een betere manier is om ervoor te zorgen dat je privé pakketten niet importeerbaar zijn omdat het wordt afgedwongen door Go. De/pkg map is nog steeds een goede manier om expliciet te communiceren dat de code in die map veilig is voor gebruik door anderen. De I'll take pkg over internal blogpost door Travis Jeffery geeft een goed overzicht van de pkg en internal mappen en wanneer het zinvol zou kunnen zijn om ze te gebruiken.

    het is ook een manier om Go code op één plaats te groeperen wanneer je root directory veel non-Go componenten en directory ‘ s bevat, waardoor het makkelijker wordt om verschillende Go tools te draaien (zoals vermeld in deze talks: Best Practices for Industrial Programming van GopherCon EU 2018, GopherCon 2018: Kat Zien – hoe structureer je je Go Apps en GoLab 2018 – Massimiliano Pippi – Project lay-out patronen in Go).

    zie de /pkg map als u wilt zien welke populaire Go repo ‘ s dit projectopmaakpatroon gebruiken. Dit is een veel voorkomende lay-out patroon, maar het is niet universeel geaccepteerd en sommige in de Go Gemeenschap niet aanraden.

    Het is ok om het niet te gebruiken als je app project echt klein is en waar een extra niveau van nesting niet veel waarde toevoegt (tenzij je echt wilt :-)). Denk erover na als het groot genoeg wordt en je root directory behoorlijk druk wordt (vooral als je veel niet-Go App componenten hebt).

    /vendor

    toepassingsafhankelijkheden (handmatig beheerd of door uw favoriete hulpprogramma voor afhankelijkheidsbeheer, zoals de nieuwe ingebouwde Go Modules functie). Het commando go mod vendor zal de map /vendor voor u aanmaken. Merk op dat je mogelijk de -mod=vendor vlag moet toevoegen aan je go build commando als je niet Go 1.14 gebruikt waar het standaard aan staat.

    commit uw toepassingsafhankelijkheden niet als u een bibliotheek aan het bouwen bent.

    merk op dat sinds 1.13 Go ook de module proxy functie heeft ingeschakeld (met https://proxy.golang.org als hun module proxy server standaard). Lees er meer over here om te zien of het voldoet aan al uw vereisten en beperkingen. Als dat zo is, dan heb je de vendor directory helemaal niet nodig.

    Service Application directory ‘ s

    /api

    OpenAPI / Swagger specs, JSON schema bestanden, protocol definitie bestanden.

    zie de /api map voor voorbeelden.

    Webapplicatiemappen

    / web

    webapplicatiespecifieke componenten: statische webactiva, serversjablonen en spa ‘ s.

    gemeenschappelijke toepassingsmappen

    / configs

    Configuratiebestandssjablonen of standaardconfiguraties.

    Plaats uw confd of consul-template template bestanden hier.

    /init

    Systeeminit (systemd, upstart, sysv) en procesmanager/supervisor (runit, supervisor) configureren.

    / scripts

    Scripts om verschillende build, install, analyse, etc operaties uit te voeren.

    deze scripts houden de Makefile op rootniveau klein en eenvoudig (bijvoorbeeld https://github.com/hashicorp/terraform/blob/master/Makefile).

    zie de /scripts map voor voorbeelden.

    /build

    verpakking en continue integratie.

    Plaats uw cloud (AMI), container (Docker), OS (deb, rpm, pkg) pakketconfiguraties en scripts in de /build/package map.

    Plaats uw CI (travis, circle, drone) configuraties en scripts in de /build/ci map. Merk op dat sommige van de CI tools (bijv., Travis CI) zijn erg kieskeurig over de locatie van hun configuratiebestanden. Probeer de configuratiebestanden in de /build/ci map te plaatsen die ze linkt naar de locatie waar de CI tools ze verwachten (indien mogelijk).

    / deployments

    IaaS, PaaS, systeem en container orkestratie deployment configuraties en templates (docker-compose, kubernetes/helm, mesos, terraform, bosh). Merk op dat in sommige repo ‘ s (vooral apps die met kubernetes worden ingezet) deze map /deploywordt genoemd.

    / test

    aanvullende externe testapps en testgegevens. Voel je vrij om de /test map te structureren zoals je wilt. Voor grotere projecten is het zinvol om een data subdirectory te hebben. U kunt bijvoorbeeld /test/data of /test/testdata hebben als u moet gaan om te negeren wat er in die map staat. Merk op dat Go ook directory ‘ s of bestanden die beginnen met “zal negeren.”of”_”, zodat u meer flexibiliteit hebt in termen van hoe u uw test data directory een naam geeft.

    zie de /test map voor voorbeelden.

    andere mappen

    /docs

    ontwerp-en gebruikersdocumenten (naast uw Door godoc gegenereerde documentatie).

    zie de /docs map voor voorbeelden.

    / tools

    ondersteunende tools voor dit project. Merk op dat deze tools code kunnen importeren uit de /pkg en /internal mappen.

    zie de /tools map voor voorbeelden.

    /voorbeelden

    voorbeelden voor uw toepassingen en / of openbare bibliotheken.

    zie de /examples map voor voorbeelden.

    /third_party

    externe hulpgereedschappen, gevorkte code en andere hulpprogramma ‘ s van derden (bijvoorbeeld Swagger UI).

    / githooks

    Git hooks.

    /activa

    andere activa die samen met uw repository gaan (afbeeldingen, logo ‘ s, enz.).

    / website

    Dit is de plaats om de website-gegevens van uw project te plaatsen als u geen GitHub-pagina ‘ s gebruikt.

    zie de /website map voor voorbeelden.

    mappen

    /src

    sommige Go-projecten hebben een src map, maar dit gebeurt meestal wanneer de devs uit de Java-wereld komen waar het een gemeenschappelijk patroon is. Als je jezelf kunt helpen probeer dit Java patroon niet aan te nemen. U wilt echt niet dat uw GO-code of Go-projecten op Java lijken: -)

    verwar het projectniveau /src map niet met de /src map die Go gebruikt voor zijn werkruimten zoals beschreven in How to Write Go Code. De$GOPATH omgevingsvariabele wijst naar uw (huidige) werkruimte (standaard wijst het naar $HOME/go op niet-windows-systemen). Deze werkruimte bevat de top level /pkg/bin en /src mappen. Uw eigenlijke project wordt een submap onder /src, dus als u de /src map in uw project heeft, ziet het projectpad er als volgt uit: /some/path/to/workspace/src/your_project/src/your_code.go. Merk op dat met Go 1.11 het is mogelijk om uw project buiten uw GOPATH te hebben, maar het betekent nog steeds niet dat het een goed idee is om dit opmaakpatroon te gebruiken.

    Badges

    • Ga Report Card – Het scant de code met gofmtgo vetgocyclogolintineffassignlicense en misspell. Vervang github.com/golang-standards/project-layout door uw projectreferentie.

      Go rapport kaart

    • GoDoc – het zal online versie van uw GoDoc gegenereerde documentatie. Wijzig de link naar uw project.

      Go Doc

    • Pkg.gaan.dev-Pkg.gaan.dev is een nieuwe bestemming voor Go discovery & docs. U kunt een badge maken met behulp van de badge generatie tool.

      PkgGoDev

    • Release – Het toont het laatste releasenummer voor uw project. Wijzig de GitHub link om naar je project te wijzen.

      Release

    Notes

    een meer eigenwijs projectsjabloon met voorbeeldconfiguraties, scripts en code is een WIP.

Geef een antwoord

Het e-mailadres wordt niet gepubliceerd.