golang-standards / project-layout

tłumaczenia:

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

przegląd

jest to podstawowy układ dla projektów aplikacji Go. Nie jest to oficjalny standard zdefiniowany przez core GO dev team; jest to jednak zestaw wspólnych historycznych i pojawiających się wzorców układu projektu w ekosystemie Go. Niektóre z tych wzorów są bardziej popularne niż inne. Posiada również szereg małych ulepszeń wraz z kilkoma wspierającymi katalogami wspólnymi dla każdej wystarczająco dużej aplikacji w świecie rzeczywistym.

Jeśli próbujesz nauczyć się Go lub jeśli budujesz PoC lub projekt Zabawki dla siebie ten układ projektu jest przesadą. Zacznij od czegoś naprawdę prostego (pojedynczy plik main.go wystarczy). W miarę rozwoju projektu pamiętaj, że ważne będzie, aby upewnić się, że Twój kod jest dobrze zorganizowany, w przeciwnym razie skończysz z niechlujnym kodem z wieloma ukrytymi zależnościami i globalnym stanem. Gdy więcej osób pracuje nad projektem, potrzebujesz jeszcze większej struktury. Dlatego ważne jest wprowadzenie wspólnego sposobu zarządzania pakietami/bibliotekami. Gdy masz projekt open source lub znasz inne projekty, zaimportuj kod z repozytorium projektu, wtedy ważne jest posiadanie prywatnych (aka internal) pakietów i kodu. Sklonuj repozytorium, zachowaj to, czego potrzebujesz i usuń wszystko inne! To, że tam jest, nie oznacza, że musisz używać wszystkiego. Żaden z tych wzorów nie jest używany w każdym projekcie. Nawet wzorzecvendor nie jest uniwersalny.

Z Go 1.14 Go Modules są wreszcie gotowe do produkcji. Użyj Go Modules, chyba że masz konkretny powód, aby ich nie używać, a jeśli tak, to nie musisz się martwić o $GOPATH i gdzie umieścisz swój projekt. Podstawowy plikgo.mod w repo zakłada, że twój projekt jest hostowany na Githubie, ale nie jest to wymagane. Ścieżka modułu może być dowolna, chociaż pierwszy komponent ścieżki modułu powinien mieć kropkę w swojej nazwie (aktualna wersja Go już jej nie wymusza, ale jeśli używasz nieco starszych wersji, nie zdziw się, jeśli Twoje Kompilacje zawiodą bez niej). Zobacz sprawy37554 I32819, jeśli chcesz dowiedzieć się więcej na ten temat.

ten układ projektu jest celowo ogólny i nie próbuje narzucić określonej struktury pakietów Go.

To jest wysiłek społeczności. Otwórz problem, jeśli widzisz nowy wzorzec lub jeśli uważasz, że jeden z istniejących wzorców wymaga aktualizacji.

Jeśli potrzebujesz pomocy z nazewnictwem, formatowaniem i stylem zacznij od uruchomieniagofmt Igolint. Przeczytaj również te wytyczne i zalecenia dotyczące stylu kodu Go:

  • 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
  • wytyczne stylu dla pakietów go (rakyll/JBD)

zobacz Go Project Layout, aby uzyskać dodatkowe informacje.

Więcej informacji na temat nazewnictwa i organizacji pakietów oraz innych zaleceń dotyczących struktury kodu:

  • 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

Chiński Post o wytycznych dotyczących projektowania pakietów i warstwie architektury

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

katalogi go

/cmd

główne aplikacje dla tego projektu.

nazwa katalogu dla każdej aplikacji powinna odpowiadać nazwie pliku wykonywalnego, który chcesz mieć (np./cmd/myapp).

nie umieszczaj dużo kodu w katalogu aplikacji. Jeśli uważasz, że kod może być zaimportowany i użyty w innych projektach, powinien znajdować się w katalogu/pkg. Jeśli kod nie nadaje się do ponownego użycia lub jeśli nie chcesz, aby inni go używali, umieść ten kod w katalogu /internal. Będziesz zaskoczony, co zrobią inni, więc bądź wyraźny co do swoich intencji!

często ma małą funkcjęmain, która importuje i wywołuje kod z katalogów/internal I/pkg I nic więcej.

Zobacz /cmd katalog dla przykładów.

/wewnętrzny

prywatny kod aplikacji i biblioteki. Jest to kod, którego nie chcesz, aby inni importowali w swoich aplikacjach lub bibliotekach. Zauważ, że ten wzorzec układu jest wymuszany przez sam kompilator Go. Zobacz Go 1.4 release notes, aby uzyskać więcej informacji. Zauważ, że nie jesteś ograniczony do katalogu internal. Możesz mieć więcej niż jeden katalog internal na dowolnym poziomie drzewa projektu.

możesz opcjonalnie dodać trochę dodatkowej struktury do pakietów wewnętrznych, aby oddzielić współdzielony i nie współdzielony kod wewnętrzny. Nie jest to wymagane (szczególnie w przypadku mniejszych projektów), ale dobrze jest mieć wskazówki wizualne pokazujące zamierzone użycie pakietu. Rzeczywisty kod aplikacji może znajdować się w katalogu /internal/app (np. /internal/app/myapp) i Kod współdzielony przez te aplikacje w katalogu /internal/pkg (np. /internal/pkg/myprivlib).

/ pkg

kod biblioteki, który może być używany przez zewnętrzne aplikacje (np., /pkg/mypubliclib). Inne projekty zaimportują te biblioteki oczekując, że będą działać, więc zastanów się dwa razy, zanim coś tutaj umieścisz 🙂 zauważ, że katalog internal jest lepszym sposobem na upewnienie się, że Twoje prywatne pakiety nie są importowane, ponieważ jest wymuszany przez Go. Katalog/pkg jest nadal dobrym sposobem na jawne zakomunikowanie, że kod w tym katalogu jest bezpieczny dla innych. I'll take pkg over internal post na blogu Travisa Jeffery zapewnia dobry przegląd katalogówpkg Iinternal I kiedy warto z nich korzystać.

jest to również sposób na grupowanie kodu Go w jednym miejscu, gdy katalog główny zawiera wiele komponentów i katalogów non-go, co ułatwia uruchamianie różnych narzędzi Go (jak wspomniano w tych rozmowach: Best Practices for Industrial Programming z GopherCon EU 2018, GopherCon 2018: Kat Zien – jak Strukturyzujesz swoje aplikacje Go i GoLab 2018 – Massimiliano Pippi – wzorce układu projektu w Go).

zobacz Katalog/pkg, jeśli chcesz zobaczyć, które popularne repozytoria Go używają tego wzorca układu projektu. Jest to popularny wzór układu, ale nie jest powszechnie akceptowany i niektórzy w społeczności Go nie polecają go.

jest ok, aby nie używać go, jeśli projekt aplikacji jest naprawdę mały i gdzie dodatkowy poziom zagnieżdżania nie dodaje wiele wartości (chyba że naprawdę chcesz :-)). Pomyśl o tym, gdy robi się wystarczająco duży, a twój katalog główny jest dość zajęty (zwłaszcza jeśli masz wiele komponentów aplikacji non-Go).

/dostawcy

zależności aplikacji (zarządzane ręcznie lub przez ulubione narzędzie do zarządzania zależnościami, takie jak nowa wbudowana funkcjaGo Modules). Poleceniego mod vendor utworzy dla ciebie katalog/vendor. Zauważ, że może być konieczne dodanie flagi-mod=vendor do poleceniago build, jeśli nie używasz Go 1.14, gdzie jest domyślnie włączony.

nie zatwierdzaj zależności aplikacji, jeśli budujesz bibliotekę.

zauważ, że ponieważ1.13 Go włączył również funkcję modułu proxy (domyślnie używająchttps://proxy.golang.org jako serwera proxy modułu). Przeczytaj więcej na ten temathere, aby sprawdzić, czy spełnia wszystkie twoje wymagania i ograniczenia. Jeśli tak, to nie będziesz w ogóle potrzebował katalogu vendor.

katalogi aplikacji serwisowych

/api

specyfikacje OpenAPI/Swagger, pliki schematu JSON, pliki definicji protokołu.

Zobacz /api katalog dla przykładów.

katalogi aplikacji internetowych

/Web

komponenty specyficzne dla aplikacji internetowych: statyczne zasoby internetowe, szablony po stronie serwera i spa.

wspólne katalogi aplikacji

/configs

szablony plików konfiguracyjnych lub domyślne configs.

umieść tutaj swojeconfd lubconsul-template pliki szablonów.

/init

konfiguracja systemu init (systemd, upstart, sysv) oraz Menedżera/nadzorcy procesów (runit, supervisord).

/scripts

skrypty do wykonywania różnych operacji kompilacji, instalacji, analizy itp.

te skrypty utrzymują mały i prosty plik Makefile poziomu głównego (np.https://github.com/hashicorp/terraform/blob/master/Makefile).

Zobacz /scripts katalog dla przykładów.

/build

Pakowanie i ciągła Integracja.

umieść konfiguracje pakietów cloud (AMI), container (Docker), OS (deb, rpm, pkg) i skrypty w katalogu/build/package.

umieść swoje konfiguracje i skrypty CI (travis, circle, drone) w katalogu /build/ci. Należy zauważyć, że niektóre z narzędzi CI (np., Travis CI) są bardzo wybredni co do lokalizacji swoich plików konfiguracyjnych. Spróbuj umieścić pliki konfiguracyjne w katalogu/build/ci łącząc je z lokalizacją, w której oczekują ich narzędzia CI (jeśli to możliwe).

/wdrożenia

konfiguracje i szablony IaaS, PaaS, system i kontener orchestration deployment (docker-compose, kubernetes/helm, mesos, terraform, bosh). Zauważ, że w niektórych reposach (zwłaszcza aplikacjach wdrożonych z kubernetes) ten katalog nazywa się /deploy.

/test

dodatkowe zewnętrzne aplikacje testowe i dane testowe. Zapraszam do uporządkowania katalogu /test. W przypadku większych projektów warto mieć podkatalog danych. Na przykład możesz mieć /test/data lub /test/testdata, jeśli chcesz zignorować to, co znajduje się w tym katalogu. Zauważ, że Go zignoruje również katalogi lub pliki zaczynające się od “.”lub”_”, dzięki czemu masz większą elastyczność w zakresie nazwy katalogu danych testowych.

Zobacz /test katalog dla przykładów.

inne katalogi

/docs

dokumenty projektu i Użytkownika (oprócz dokumentacji Wygenerowanej Przez godoc).

Zobacz /docs katalog dla przykładów.

/tools

narzędzia wspierające ten projekt. Zauważ, że te narzędzia mogą importować kod z katalogów /pkg I /internal.

Zobacz /tools katalog dla przykładów.

/przykłady

przykłady dla Twoich aplikacji i/lub bibliotek publicznych.

Zobacz /examples katalog dla przykładów.

/third_party

zewnętrzne narzędzia pomocnicze, rozwidlony kod i inne narzędzia innych firm (np.

/githooks

Git Hooki.

/assets

inne aktywa, które mogą być dołączone do twojego repozytorium (obrazy, logo itp.).

/strona internetowa

To jest miejsce na umieszczenie danych strony internetowej twojego projektu, jeśli nie korzystasz ze stron GitHub.

Zobacz /website katalog dla przykładów.

katalogi nie powinieneś mieć

/src

niektóre projekty Go mająsrc folder, ale zwykle dzieje się tak, gdy programiści pochodzą ze świata Javy, gdzie jest to powszechny wzorzec. Jeśli możesz sobie pomóc, spróbuj nie przyjmować tego wzorca Javy. Naprawdę nie chcesz, aby Twój kod Go lub projekty Go wyglądały jak Java: -)

nie myl katalogu /srcz katalogiem /srcgo używa do swoich Przestrzeni Roboczych, jak opisano w How to Write Go Code. Zmienna środowiskowa$GOPATH wskazuje na (bieżący) obszar roboczy (domyślnie wskazuje na$HOME/go w systemach innych niż windows). Ta przestrzeń robocza zawiera katalogi /pkg/bin I /src. Twój rzeczywisty projekt kończy się jako podkatalog pod /src, więc jeśli masz /src katalog w swoim projekcie ścieżka projektu będzie wyglądać następująco: /some/path/to/workspace/src/your_project/src/your_code.go. Zauważ, że za pomocą Go 1.11 możliwe jest posiadanie projektu poza GOPATH, ale nadal nie oznacza to, że dobrym pomysłem jest użycie tego wzorca układu.

odznaki

  • Go Report Card – zeskanuje Twój kod za pomocągofmtgo vetgocyclogolintineffassignlicense Imisspell. Zastąp github.com/golang-standards/project-layout odnośnikiem do projektu.

    Przejdź kartę zgłoszenia

  • GoDoc – dostarczy on wersję online dokumentacji Wygenerowanej Przez GoDoc. Zmień link, aby wskazać swój projekt.

    przejdź do dokumentu

  • Pkg.idź.dev-Pkg.idź.dev jest nowym celem dla GO discovery & docs. Możesz utworzyć odznakę za pomocą narzędzia generowanie plakietek.

    PkgGoDev

  • Release – wyświetli najnowszy numer wydania dla Twojego projektu. Zmień link github, aby wskazywał na twój projekt.

    Release

uwagi

bardziej opiniowany szablon projektu z przykładowymi/wielokrotnego użytku konfiguracjami, skryptami i kodem to WIP.

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany.