|
| 1 | +# Structură standard pentru aplicațiile Go |
| 2 | + |
| 3 | +Traduceri: |
| 4 | + |
| 5 | +* [English](README.md) |
| 6 | +* [한국어 문서](README_ko.md) |
| 7 | +* [简体中文](README_zh.md) |
| 8 | +* [正體中文](README_zh-TW.md) |
| 9 | +* [简体中文](README_zh-CN.md) - ??? |
| 10 | +* [Français](README_fr.md) |
| 11 | +* [日本語](README_ja.md) |
| 12 | +* [Portuguese](README_ptBR.md) |
| 13 | +* [Español](README_es.md) |
| 14 | +* [Română](README_ro.md) |
| 15 | + |
| 16 | +## General |
| 17 | + |
| 18 | +Aceasta este o structură de bază pentru aplicațiile Go. Nu este un standard oficial definit de echipa Go; însă reprezintă un set de structuri/modele comune folosite de-a lungul timpului în aplicațiile din ecosistemul Go. Unele sunt mai populare decât altele. Sunt prezente și îmbunătățiri, cu directoare specifice unei aplicații de mari dimensiuni. |
| 19 | + |
| 20 | +Dacă încerci să înveți Go sau să creezi un PoC/proiect hobby aceasta structură este excesivă. Începe cu ceva foarte simplu (un fișier `main.go` e de ajuns). Pe măsură ce proiectul crește ține minte că va fi nevoie să îl structurezi, altfel te vei trezi cu mult cod spagettă și dependințe/state-uri globale greu de întreținut. Când sunt mai mulți oameni care lucrează la proiect, vei avea nevoie de o structură și mai bună. Din acest motiv este important să introduci un mod comun de gestionare a librăriilor/package-urilor. Când ai un proiect open-source, când știi că alte proiecte importă codul din proiectul tău, e important să ai module (packages) private (internal). Clonează acest repo și ține doar ce ai nevoie. Doar pentru că e acolo, nu înseamnă că trebuie să îl folosești. Aceste standarde nu sunt folosite în toate proiectele Go, nici măcar cel comun `vendor` nu este universal. |
| 21 | + |
| 22 | +De la apariția Go 1.14 [`Go Modules`](https://github.com/golang/go/wiki/Modules) sunt gata de producție (production mode). Folosește [`Go Modules`](https://blog.golang.org/using-go-modules) doar dacă nu ai un motiv specific de a nu le folosești. Dacă nu vrei să le folosești atunci nu este nevoie să te gândești la $GOPATH și unde să îți plasezi proiectul. Fișierul `go.mod` din repo-ul tău asumă că proiectul îți este hostat pe Github, însă asta nu e o necesitate. Calea (path) modulelor poate fi orice, însă primul modul component ar trebui să aibă un punct în numele său (versiunea curentă Go nu o mai cere explicit însă dacă folosești o versiune mai veche nu fi surprins dacă primești erori la compilare). Vezi problemele [`37554`](https://github.com/golang/go/issues/37554) și [`32819`](https://github.com/golang/go/issues/32819) dacă vrei să afli mai multe. |
| 23 | + |
| 24 | +Această structură este intenționat generică și nu își dorește să impună un standard în gestiunea modulelor Go. |
| 25 | + |
| 26 | +Această structură este un efort al comunității. Deschide o problemă (issue) dacă observi o nouă structură sau consideri că una existentă ar trebui actualizată. |
| 27 | + |
| 28 | +Dacă ai nevoie de ajutor cu denumirile, formatare, stilare vezi [`gofmt`](https://golang.org/cmd/gofmt/) și [`golint`](https://github.com/golang/lint). Ar fi bine să citești și aceste linii de ghidare în vederea stilării codului Go: |
| 29 | +* https://talks.golang.org/2014/names.slide |
| 30 | +* https://golang.org/doc/effective_go.html#names |
| 31 | +* https://blog.golang.org/package-names |
| 32 | +* https://github.com/golang/go/wiki/CodeReviewComments |
| 33 | +* [Ghid de stilare pentru modulele Go](https://rakyll.org/style-packages) (rakyll/JBD) |
| 34 | + |
| 35 | +Vezi [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) pentru informații adiționale. |
| 36 | + |
| 37 | +Mai multe despre numirea și organizarea modulelor + recomandări: |
| 38 | +* [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) |
| 39 | +* [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) |
| 40 | +* [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) |
| 41 | +* [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) |
| 42 | + |
| 43 | +Un articol chinezeasc despre Package-Oriented-Design și arhitectură: |
| 44 | +* [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) |
| 45 | + |
| 46 | +## Directoarele Go |
| 47 | + |
| 48 | +### `/cmd` |
| 49 | + |
| 50 | +Aplicațiile principale ale acestui proiect. |
| 51 | + |
| 52 | +Numele directorului pentru fiecare aplicație ar trebui să coincidă cu numele executabilului pe care vrei să îl ai (e.g., `/cmd/myapp`). |
| 53 | + |
| 54 | +Nu pune mult cod în directorul aplicației. Dacă el ar trebui importat și folosit în alte proiecte, atunci ar trebui pus în `/pkg`. Dacă nu este reutilizabil sau vrei ca alții să îl reutilizeze, pune codul în `/internal`. Vei fi surprins ce vor face ceilalți, deci fii explicit în intențiile tale! |
| 55 | + |
| 56 | +Este comun să ai o funcție `main` care doar importă și invocă cod din `/internal` și `/pkg`. |
| 57 | + |
| 58 | +Vezi directorul [`/cmd`](cmd/README.md) pentru exemple. |
| 59 | + |
| 60 | +### `/internal` |
| 61 | + |
| 62 | +Cod privat al modulelor/aplicației. Acesta este cod pe care nu vrei alții să îl importe în aplicațiile/modulele lor. Această structură este forțată de compilatorul Go. Vezi Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) pentru mai multe detalii. Nu ești însă limitat de un singur director top-level `internal`. Poți avea mai multe directoare `internal` la orice nivel în cadrul proiectului tău. |
| 63 | + |
| 64 | +Poți adăuga o structură adițională modulelor tale interne pentru a separa codul partajat de cel nepartajat. Nu este necesar, dar este bune să ai indicii vizuale pentru a arăta scopul de folosire al modulelor. Codul actual al aplicației poate fi în directorul `/internal/app` (e.g., `/internal/app/myapp`) iar codul partajat de acele aplicații în `/internal/pkg` (e.g., `/internal/pkg/myprivlib`). |
| 65 | + |
| 66 | +### `/pkg` |
| 67 | + |
| 68 | +Cod librărie care poate fi folosit de aplicațiile externe (e.g., `/pkg/mypubliclib`). Alte proiecte vor importa aceste module și se vor aștepta ca ele să funcționeze, așa că gândește-te de 2 ori înainte de a pune ceva aici :) Directorul `internal` este o modalitate mai bună de a fi sigur că modulele tale no sunt importabile deoarece acest fapt este forțat de Go. Directorul `/pkg` este în continuare un mod bun de a comunica explicit codul ca fiind sigur de folosit de către ceilalți. Postarea [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) oferă o prezentare generală a directoarelor `pkg` și `internal`. |
| 69 | + |
| 70 | +Este o metodă bună să grupezi codul Go într-un singur loc atunci când directorul root al aplicației conține multe componente no-Go, (cum este menționat în aceste prezentări: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) and [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). |
| 71 | + |
| 72 | +Vezi [`/pkg`](pkg/README.md) dacă vrei să vezi care repo-uri populare Go folosesc această structură de proiect. Aceasta este o structură comună de proiect însă nu este universală și nu o recomand în comunitatea Go. |
| 73 | + |
| 74 | +### `/vendor` |
| 75 | + |
| 76 | +Dependințele aplicației (gestionate manual sau automat). Comanda `go mod vendor` va creea un director `/vendor`. Probabil va trebui să adaugi ca parametru `-mod=vendor` atunci când execuți `go build` dacă nu folosești Go 1.14 |
| 77 | + |
| 78 | +Nu da commit la dependințele aplicației dacă construiești un modul. |
| 79 | + |
| 80 | +Odată cu versiunea [`1.13`](https://golang.org/doc/go1.13#modules) Go a implementat funcționalitatea modulelor proxy (folosind [`https://proxy.golang.org`](https://proxy.golang.org) ca server proxy al modulelor implicit). Poți citi mai multe despre el [`aici`](https://blog.golang.org/module-mirror-launch). S-ar putea să nu ai nevoie de directorul `/vendor` dacă poți folosi modulele proxy. |
| 81 | + |
| 82 | +## Directoarele de servicii ale aplicației |
| 83 | + |
| 84 | +### `/api` |
| 85 | + |
| 86 | +Specificații OpenAPI/Swagger, fișiere JSON schema, fișiere cu definiții de protocoale. |
| 87 | + |
| 88 | +Vezi directorul [`/api`](api/README.md) pentru exemple. |
| 89 | + |
| 90 | +## Directorul aplicațiilor Web |
| 91 | + |
| 92 | +### `/web` |
| 93 | + |
| 94 | +Componente specifice aplicațiilor Web: asset-uri, template-uri, SPAs, etc |
| 95 | + |
| 96 | +## Directoare comune aplicațiilor |
| 97 | + |
| 98 | +### `/configs` |
| 99 | + |
| 100 | +Șablonuri de configurare, configurări implicite. |
| 101 | + |
| 102 | +Poți pune `confd` sau `consul-template` aici. |
| 103 | + |
| 104 | +### `/init` |
| 105 | + |
| 106 | +Configurări de inițializare system (systemd, upstart, sysv) și gestiune/supervizare a proceselor (runit, supervisord) |
| 107 | + |
| 108 | +### `/scripts` |
| 109 | + |
| 110 | +Scripturi pentru rularea diferitelor operații. |
| 111 | + |
| 112 | +Ele țin nivelul rădăcinii Makefile mic și simplu (e.g., [`https://github.com/hashicorp/terraform/blob/master/Makefile`](https://github.com/hashicorp/terraform/blob/master/Makefile)). |
| 113 | + |
| 114 | +Vezi directorul [`/scripts`](scripts/README.md) pentru examples. |
| 115 | + |
| 116 | +### `/build` |
| 117 | + |
| 118 | +Packaging și Integrare Continuă. |
| 119 | + |
| 120 | +Pune configurări ale modulelor AMI, Docker, OS (deb, rpm, pkg) și scripturi în directorul `/build/package` |
| 121 | + |
| 122 | +Pune configurările CI (travis, circle, drone) și scripturile similare în directorul `/build/ci`. Unele instrumente CI sunt pretențioase când vine vorba de locația configurărilor (e.g., Travis CI). Încearcă să pui fișierele de configurare în directorul `/build/ci` legându-le de locația în care uneltele CI se așteaptă să fie. |
| 123 | + |
| 124 | +### `/deployments` |
| 125 | + |
| 126 | +Conține sisteme și containere de orchestrare, implementare, șablonare (docker-compose, kubernetes/helm, mesos, terraform, bosh) IaaS, PaaS. În unele repo-uri (în special cele implementate cu kubernetes) acest director e numit direct `/deploy`. |
| 127 | + |
| 128 | +### `/test` |
| 129 | + |
| 130 | +Softuri și fișiere adiționale de testare. Poți structura directorul `/test` cum dorești. Pentru proiecte mari are sens să conțină sub-directoare. De exemplu, poți avea `/test/data` sau `/test/testdata` dacă vrei ca Go să ignore ce este in acel director. Go va ignora și directoarele sau fișierele care încep cu "." sau "\_", deci ai mai multă flexibilitate cu privire la modul în care îți numești fișierele/directoarele din `/test` |
| 131 | + |
| 132 | +Vezi [directorul](test/README.md) pentru example. |
| 133 | + |
| 134 | +## Alte directoare |
| 135 | + |
| 136 | +### `/docs` |
| 137 | + |
| 138 | +Documentația structurii aplicației |
| 139 | + |
| 140 | +Vezi [`/docs`](docs/README.md) pentru exemple. |
| 141 | + |
| 142 | +### `/tools` |
| 143 | + |
| 144 | +Unelte de suport pentru acest proiect. Ele pot importa și module din directoarele `/pkg` și `/internal` |
| 145 | + |
| 146 | +Vezi [`/tools`](tools/README.md) pentru exemple. |
| 147 | + |
| 148 | +### `/examples` |
| 149 | + |
| 150 | +Exemple pentru aplicația ta și/sau librării publice |
| 151 | + |
| 152 | +Vezi [`/examples`](examples/README.md) pentru exemple. |
| 153 | + |
| 154 | +### `/third_party` |
| 155 | + |
| 156 | +Unelte externe de ajutor, cod forked și alte utilități (e.g., Swagger UI). |
| 157 | + |
| 158 | +### `/githooks` |
| 159 | + |
| 160 | +Git hooks. |
| 161 | + |
| 162 | +### `/assets` |
| 163 | + |
| 164 | +Alte aseturi conținute de repo (images, logos, etc). |
| 165 | + |
| 166 | +### `/website` |
| 167 | + |
| 168 | +Acesta este locul în care îți pui datele website, dacă nu folosești pagini GitHub. |
| 169 | + |
| 170 | +Vezi [`/website`](website/README.md) pentru exemple. |
| 171 | + |
| 172 | +## Directoare pe care NU ar trebui să le ai |
| 173 | + |
| 174 | +### `/src` |
| 175 | + |
| 176 | +Unele proiecte Go au un director `src`, dar se întâmplă de obicei când developer-ii au venit din domeniul Java. Încearcă să nu adopți o astfel de structură, e indicat ca proiectul tău să nu se asemene cu unul tip Java. |
| 177 | + |
| 178 | +Nu confunda directorul `/src` cu cel pe care Go îl folosește ca spațiu de lucru (workspace). Variabila `$GOPATH` arată workspace-ul (implicit el e setat la `$HOME/go` pentru sistemele de operare non-Windows). Acest workspace folosește directoarele `/pkg`, `/bin` și `/src`. Proiectul tău actual ajunge să fie un sub-director sub `/src`, deci dacă ai un director `/src` în proiectul tău, calea va arăta cam așa: `/some/path/to/workspace/src/your_project/src/your_code.go`. Odată cu Go 1.11 este permis să ai proiectul în afara `GOPATH`, însă nu este neapărat o idee bună să adopți o astfel de schemă. |
| 179 | + |
| 180 | +## Adiționale |
| 181 | + |
| 182 | +* [Go Report Card](https://goreportcard.com/) - Îți va scana codul cu `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` și `misspell`. Înlocuiește `github.com/golang-standards/project-layout` cu referința la proiuectul tău. |
| 183 | + |
| 184 | + [](https://goreportcard.com/report/github.com/golang-standards/project-layout) |
| 185 | + |
| 186 | +* ~~[GoDoc](http://godoc.org) - Va furniza versiuni online ale documentației generate local de GoDoc.~~ |
| 187 | + |
| 188 | + [](http://godoc.org/github.com/golang-standards/project-layout) |
| 189 | + |
| 190 | +* [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev este o nouă destinație pentru descoperiri și documentație Go. Poți creea o insignă (badge) cu [badge generation tool](https://pkg.go.dev/badge). |
| 191 | + |
| 192 | + [](https://pkg.go.dev/github.com/golang-standards/project-layout) |
| 193 | + |
| 194 | +* Release - Va arăta ultimele lansări (versiuni) ale proiectului tău. |
| 195 | + |
| 196 | + [](https://github.com/golang-standards/project-layout/releases/latest) |
| 197 | + |
| 198 | +## Note |
| 199 | + |
| 200 | +Un șablon mai pedant cu configurări probate/reutilizabile, scripturi și cod este un WIP. |
0 commit comments