Updated word project to new grammar rules
This commit is contained in:
Rostislav Pylypiv
parent
93f9b19413
commit
0036211c55
40
README_ua.md
40
README_ua.md
@ -19,11 +19,11 @@ Translations:
|
||||
|
||||
Це базовий макет для проєктів Go-додатків. Це **`не є офіційним стандартом, визначеним командою розробників Go`**; тим не менш, це звід паттернів програмування в екосистемі Go, що склалися історично. Деякі з цих паттернів більш популярні та відомі ніж інші. Також в цьому макеті є декілька покращень, в тому числі декілька додаткових дерикторій, що використовуються в будь-якому достатньо великому реальному застосунку.
|
||||
|
||||
**`Якщо ви тільки вивчаєте Go або створюєте якийсь демонстраційний чи простий проєкт для себе цей макет буде занадто складним. Почність з чогось дійсно простого (одного файлу `main.go` та `go.mod` буде достатньо).`** Коли проєкт почне рости не забувайте, важливо щоб код залишався добре структурованим, інакше ви отримаєте брудний код з великою кількістю прихованих залежностей та глобальних станів. Коли над проектом працює більше людей, вам знадобиться ще більше структури. Саме тоді важливо запровадити єдиний спосіб управління пакетами/бібліотеками. Коли ви маєте проект з відкритим вихідним кодом або коли ви знаєте, що інші проекти імпортують код з вашого репозиторію проекту, саме тоді важливо мати приватні (`internal`) пакети та код. Клонуйте сховище, зберігайте те, що вам потрібно, а все інше видаляйте! Те, що це є, не означає, що ви повинні використовувати все це. Жодна з цих моделей не використовується в кожному окремому проекті. Навіть паттерн `vendor` не є універсальним.
|
||||
**`Якщо ви тільки вивчаєте Go або створюєте якийсь демонстраційний чи простий проєкт для себе цей макет буде занадто складним. Почність з чогось дійсно простого (одного файлу `main.go` та `go.mod` буде достатньо).`** Коли проєкт почне рости не забувайте, важливо щоб код залишався добре структурованим, інакше ви отримаєте брудний код з великою кількістю прихованих залежностей та глобальних станів. Якщо над проєктом працює більше людей, необхідно ще більше структури. Саме тоді важливо запровадити єдиний спосіб управління пакетами/бібліотеками. Коли ви маєте проєкт з відкритим вихідним кодом або коли ви знаєте, що інші проєкти імпортують код з вашого репозиторію проєкту, саме тоді важливо мати приватні (`internal`) пакети та код. Клонуйте сховище, зберігайте те, що вам потрібно, а все інше видаляйте! Те, що це є, не означає, що ви повинні використовувати все це. Жодна з цих моделей не використовується в кожному окремому проєкті. Навіть паттерн `vendor` не є універсальним.
|
||||
|
||||
Починаючи з Go 1.14 [`Go модулі`](https://github.com/golang/go/wiki/Modules) нарешті готові до використання. Використовуйте [`Go модулі`](https://blog.golang.org/using-go-modules) якщо у вас немає конкретної причини не використовувати їх, а якщо є, то вам не потрібно турбуватися про $GOPATH і про те, куди ви помістили свій проект. Базовий файл `go.mod` в репозиторії передбачає, що ваш проєкт розміщено на GitHub, однак це не є обов'язковою вимогою. Шлях до модуля може бути будь-яким, але перший компонент шляху до модуля повинен містити крапку в назві (поточна версія Go більше не вимагає цього, але якщо ви використовуєте трохи старіші версії, не дивуйтеся, якщо ваші збірки не працюватимуть без цього). Якщо ви хочете дізнатися більше про це, дивіться: [`37554`](https://github.com/golang/go/issues/37554) та [`32819`](https://github.com/golang/go/issues/32819).
|
||||
Починаючи з Go 1.14 [`Go модулі`](https://github.com/golang/go/wiki/Modules) нарешті готові до використання. Використовуйте [`Go модулі`](https://blog.golang.org/using-go-modules) якщо у вас немає конкретної причини не використовувати їх, а якщо є, то вам не потрібно турбуватися про $GOPATH і про те, куди ви помістили свій проєкт. Базовий файл `go.mod` в репозиторії передбачає, що ваш проєкт розміщено на GitHub, однак це не є обов'язковою вимогою. Шлях до модуля може бути будь-яким, але перший компонент шляху до модуля повинен містити крапку в назві (поточна версія Go більше не вимагає цього, але якщо ви використовуєте трохи старіші версії, не дивуйтеся, якщо ваші збірки не працюватимуть без цього). Якщо ви хочете дізнатися більше про це, дивіться: [`37554`](https://github.com/golang/go/issues/37554) та [`32819`](https://github.com/golang/go/issues/32819).
|
||||
|
||||
Ця схема проекту є навмисно загальною і не намагається нав'язати конкретну структуру пакета Go.
|
||||
Ця схема проєкту є навмисно загальною і не намагається нав'язати конкретну структуру пакета Go.
|
||||
|
||||
Це зусилля спільноти. Відкрийте тему, якщо ви бачите новий шаблон або якщо ви вважаєте, що один з існуючих шаблонів потребує оновлення.
|
||||
|
||||
@ -42,7 +42,7 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
* [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8)
|
||||
* [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0)
|
||||
|
||||
Китайська публікація про керівні принципи пакетно-орієнтованого проектування та рівень архітектури
|
||||
Китайська публікація про керівні принципи пакетно-орієнтованого проєктування та рівень архітектури
|
||||
* [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md)
|
||||
|
||||
## Go каталоги
|
||||
@ -53,7 +53,7 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
Ім'я каталогу для кожного додатка повинно збігатися з ім'ям виконуваного файлу, який ви хочете мати (наприклад `/cmd/myapp`).
|
||||
|
||||
Не розміщуйте багато коду в каталозі програми. Якщо ви вважаєте, що код може бути імпортований і використаний в інших проектах, то він повинен знаходитися в каталозі `/pkg`. Якщо код не може бути використаний повторно або якщо ви не хочете, щоб інші використовували його повторно, помістіть цей код в каталог `/internal`. Ви будете здивовані тим, що будуть робити інші, тому будьте відверті у своїх намірах!
|
||||
Не розміщуйте багато коду в каталозі програми. Якщо ви вважаєте, що код може бути імпортований і використаний в інших проєктах, то він повинен знаходитися в каталозі `/pkg`. Якщо код не може бути використаний повторно або якщо ви не хочете, щоб інші використовували його повторно, помістіть цей код в каталог `/internal`. Ви будете здивовані тим, що будуть робити інші, тому будьте відверті у своїх намірах!
|
||||
|
||||
Зазвичай є невелика функція `main`, яка імпортує та викликає код з каталогів `/internal` та `/pkg` і нічого більше.
|
||||
|
||||
@ -61,21 +61,21 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
### `/internal`
|
||||
|
||||
Приватний код додатків та бібліотек. Це код, який ви не хочете, щоб інші імпортували у свої програми або бібліотеки. Зауважте, що цей шаблон компонування забезпечується самим компілятором Go. Дивіться Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) для додаткових деталей. Зверніть увагу, що ви не обмежені директорією `internal` верхнього рівня. Ви можете мати більше одного каталогу `internal` на будь-якому рівні дерева вашого проекту.
|
||||
Приватний код додатків та бібліотек. Це код, який ви не хочете, щоб інші імпортували у свої програми або бібліотеки. Зауважте, що цей шаблон компонування забезпечується самим компілятором Go. Дивіться Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) для додаткових деталей. Зверніть увагу, що ви не обмежені директорією `internal` верхнього рівня. Ви можете мати більше одного каталогу `internal` на будь-якому рівні дерева вашого проєкту.
|
||||
|
||||
За бажанням ви можете додати трохи додаткової структури до ваших внутрішніх пакунків, щоб відокремити ваш спільний і не спільний внутрішній код. Це не є обов'язковим (особливо для невеликих проектів), але приємно мати візуальні підказки, що показують передбачуване використання пакунків. Ваш власне код програми може знаходитися у каталозі `/internal/app` (наприклад, `/internal/app/myapp`), а код, який використовується спільно з іншими програмами, у каталозі `/internal/pkg` (наприклад, `/internal/pkg/myprivlib`).
|
||||
За бажанням ви можете додати трохи додаткової структури до ваших внутрішніх пакунків, щоб відокремити ваш спільний і не спільний внутрішній код. Це не є обов'язковим (особливо для невеликих проєктів), але приємно мати візуальні підказки, що показують передбачуване використання пакунків. Ваш власне код програми може знаходитися у каталозі `/internal/app` (наприклад, `/internal/app/myapp`), а код, який використовується спільно з іншими програмами, у каталозі `/internal/pkg` (наприклад, `/internal/pkg/myprivlib`).
|
||||
|
||||
### `/pkg`
|
||||
|
||||
Код бібліотеки, який можна використовувати зовнішніми програмами (наприклад, `/pkg/mypubliclib`). Інші проекти імпортуватимуть ці бібліотеки, очікуючи, що вони будуть працювати, тому подумайте двічі, перш ніж щось сюди класти :-) Зауважте, що каталог `internal` є кращим способом гарантувати, що ваші приватні пакунки не будуть імпортовані, оскільки це забезпечується Go. Каталог `/pkg` все ще є гарним способом явно повідомити, що код у цьому каталозі є безпечним для використання іншими. Допис у блозі [`I'll take pkg over internal`] (https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) Тревіса Джеффрі (Travis Jeffery) надає гарний огляд каталогів `pkg` та `internal` і того, коли може мати сенс їх використання.
|
||||
Код бібліотеки, який можна використовувати зовнішніми програмами (наприклад, `/pkg/mypubliclib`). Інші проєкти імпортуватимуть ці бібліотеки, очікуючи, що вони будуть працювати, тому подумайте двічі, перш ніж щось сюди класти :-) Зауважте, що каталог `internal` є кращим способом гарантувати, що ваші приватні пакунки не будуть імпортовані, оскільки це забезпечується Go. Каталог `/pkg` все ще є гарним способом явно повідомити, що код у цьому каталозі є безпечним для використання іншими. Допис у блозі [`I'll take pkg over internal`] (https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) Тревіса Джеффрі (Travis Jeffery) надає гарний огляд каталогів `pkg` та `internal` і того, коли може мати сенс їх використання.
|
||||
|
||||
Це також спосіб згрупувати код Go в одному місці, коли ваш кореневий каталог містить багато не-Go компонентів і каталогів, що полегшує запуск різних інструментів Go (як згадувалося в цих доповідях: [`Best Practices for Industrial Programming`] (https://www.youtube.com/watch?v=PTE4VJIdHPg) з GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps] (https://www.youtube.com/watch?v=oL6JBUk6tj0) та [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go] (https://www.youtube.com/watch?v=3gQa1LWwuzk)).
|
||||
|
||||
Якщо ви хочете побачити, які популярні репозиторії Go використовують цей шаблон оформлення проектів, зверніться до каталогу [`/pkg`](pkg/README.md). Це загальноприйнятий шаблон, але він не є загальноприйнятим, і дехто у спільноті Go не рекомендує його використовувати.
|
||||
Якщо ви хочете побачити, які популярні репозиторії Go використовують цей шаблон оформлення проєктів, зверніться до каталогу [`/pkg`](pkg/README.md). Це загальноприйнятий шаблон, але він не є загальноприйнятим, і дехто у спільноті Go не рекомендує його використовувати.
|
||||
|
||||
Можна не використовувати його, якщо ваш проект програми дійсно невеликий і де додатковий рівень вкладеності не додає особливої цінності (якщо тільки ви дійсно цього не хочете :-)). Подумайте про це, коли він стане досить великим і ваш кореневий каталог буде досить зайнятий (особливо якщо у вас багато компонентів програми, які не є Go).
|
||||
Можна не використовувати його, якщо ваш проєкт програми дійсно невеликий і де додатковий рівень вкладеності не додає особливої цінності (якщо тільки ви дійсно цього не хочете :-)). Подумайте про це, коли він стане досить великим і ваш кореневий каталог буде досить зайнятий (особливо якщо у вас багато компонентів програми, які не є Go).
|
||||
|
||||
Походження каталогу `pkg`: старий вихідний код Go використовував `pkg` для своїх пакунків, а потім різні проекти Go у спільноті почали копіювати цей шаблон (див. [`це`] (https://twitter.com/bradfitz/status/1039512487538970624) твіт Бреда Фіцпатріка для більш детального контексту).
|
||||
Походження каталогу `pkg`: старий вихідний код Go використовував `pkg` для своїх пакунків, а потім різні проєкти Go у спільноті почали копіювати цей шаблон (див. [`це`] (https://twitter.com/bradfitz/status/1039512487538970624) твіт Бреда Фіцпатріка для більш детального контексту).
|
||||
|
||||
### `/vendor`
|
||||
|
||||
@ -133,7 +133,7 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
### `/test`
|
||||
|
||||
Додаткові зовнішні тестові програми та тестові дані. Не соромтеся структурувати каталог `/test` як завгодно. Для великих проектів має сенс мати підкаталог даних. Наприклад, ви можете мати `/test/data` або `/test/testdata`, якщо вам потрібно, щоб команда Go ігнорувала те, що знаходиться в цьому каталозі. Зауважте, що Go також ігноруватиме каталоги або файли, які починаються з "." або "_", тому у вас є більше гнучкості в плані того, як ви можете назвати свій каталог тестових даних.
|
||||
Додаткові зовнішні тестові програми та тестові дані. Не соромтеся структурувати каталог `/test` як завгодно. Для великих проєктів має сенс мати підкаталог даних. Наприклад, ви можете мати `/test/data` або `/test/testdata`, якщо вам потрібно, щоб команда Go ігнорувала те, що знаходиться в цьому каталозі. Зауважте, що Go також ігноруватиме каталоги або файли, які починаються з "." або "_", тому у вас є більше гнучкості в плані того, як ви можете назвати свій каталог тестових даних.
|
||||
|
||||
Приклади дивіться у каталозі [`/test`](test/README.md).
|
||||
|
||||
@ -141,13 +141,13 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
### `/docs`
|
||||
|
||||
Проектна та користувацька документація (на додаток до вашої документації, згенерованої в godoc).
|
||||
Проєктна та користувацька документація (на додаток до вашої документації, згенерованої в godoc).
|
||||
|
||||
Приклади дивіться у каталозі [`/docs`](docs/README.md).
|
||||
|
||||
### `/tools`
|
||||
|
||||
Допоміжні інструменти для цього проекту. Зверніть увагу, що ці інструменти можуть імпортувати код з каталогів `/pkg` та `/internal`.
|
||||
Допоміжні інструменти для цього проєкту. Зверніть увагу, що ці інструменти можуть імпортувати код з каталогів `/pkg` та `/internal`.
|
||||
|
||||
Приклади дивіться у каталозі [`/tools`](tools/README.md).
|
||||
|
||||
@ -171,7 +171,7 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
### `/website`
|
||||
|
||||
Це місце для розміщення даних сайту вашого проекту, якщо ви не використовуєте GitHub Pages.
|
||||
Це місце для розміщення даних сайту вашого проєкту, якщо ви не використовуєте GitHub Pages.
|
||||
|
||||
Приклади дивіться у каталозі [`/website`](website/README.md).
|
||||
|
||||
@ -179,9 +179,9 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
### `/src`
|
||||
|
||||
Деякі проекти Go мають папку `src`, але це зазвичай трапляється, коли розробники прийшли зі світу Java, де це є поширеним шаблоном. Намагайтеся не використовувати цей патерн Java. Ви ж не хочете, щоб ваш Go код або Go проекти виглядали як Java :-)
|
||||
Деякі проєкти Go мають папку `src`, але це зазвичай трапляється, коли розробники прийшли зі світу Java, де це є поширеним шаблоном. Намагайтеся не використовувати цей патерн Java. Ви ж не хочете, щоб ваш Go код або Go проєкти виглядали як Java :-)
|
||||
|
||||
Не плутайте каталог `/src` на рівні проекту з каталогом `/src`, який Go використовує для своїх робочих областей, як описано в [`How to Write Go Code`] (https://golang.org/doc/code.html). Змінна оточення `$GOPATH` вказує на вашу (поточну) робочу область (за замовчуванням вона вказує на `$HOME/go` на системах, відмінних від Windows). Ця робоча область включає в себе каталоги верхнього рівня `/pkg`, `/bin` та `/src`. Ваш фактичний проект закінчується підкаталогом у каталозі `/src`, тому, якщо у вашому проекті є каталог `/src`, шлях до проекту буде виглядати наступним чином: `/some/path/to/workspace/src/ваш_проект/src/ваш_код.go`. Зауважте, що з Go 1.11 можна мати проект поза `GOPATH`, але це ще не означає, що це гарна ідея використовувати цей шаблон компонування.
|
||||
Не плутайте каталог `/src` на рівні проєкту з каталогом `/src`, який Go використовує для своїх робочих областей, як описано в [`How to Write Go Code`] (https://golang.org/doc/code.html). Змінна оточення `$GOPATH` вказує на вашу (поточну) робочу область (за замовчуванням вона вказує на `$HOME/go` на системах, відмінних від Windows). Ця робоча область включає в себе каталоги верхнього рівня `/pkg`, `/bin` та `/src`. Ваш фактичний проєкт закінчується підкаталогом у каталозі `/src`, тому, якщо у вашому проєкті є каталог `/src`, шлях до проєкту буде виглядати наступним чином: `/some/path/to/workspace/src/ваш_проєкт/src/ваш_код.go`. Зауважте, що з Go 1.11 можна мати проєкт поза `GOPATH`, але це ще не означає, що це гарна ідея використовувати цей шаблон компонування.
|
||||
|
||||
|
||||
## Badges
|
||||
@ -190,7 +190,7 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
[](https://goreportcard.com/report/github.com/golang-standards/project-layout)
|
||||
|
||||
* ~~[GoDoc](http://godoc.org) - надає онлайн-версію вашої документації, створеної у форматі GoDoc. Змініть посилання, щоб воно вказувало на ваш проект.~~
|
||||
* ~~[GoDoc](http://godoc.org) - надає онлайн-версію вашої документації, створеної у форматі GoDoc. Змініть посилання, щоб воно вказувало на ваш проєкт.~~
|
||||
|
||||
[](http://godoc.org/github.com/golang-standards/project-layout)
|
||||
|
||||
@ -198,10 +198,10 @@ IЯкщо вам потрібна допомога з іменуванням, ф
|
||||
|
||||
[](https://pkg.go.dev/github.com/golang-standards/project-layout)
|
||||
|
||||
* Реліз - покаже номер останнього релізу для вашого проекту. Змініть посилання на github, щоб воно вказувало на ваш проект.
|
||||
* Реліз - покаже номер останнього релізу для вашого проєкту. Змініть посилання на github, щоб воно вказувало на ваш проєкт.
|
||||
|
||||
[](https://github.com/golang-standards/project-layout/releases/latest)
|
||||
|
||||
## Нотатки
|
||||
|
||||
Більш розгорнутий шаблон проекту зі зразками/багаторазовими конфігураціями, скриптами та кодом - це WIP.
|
||||
Більш розгорнутий шаблон проєкту зі зразками/багаторазовими конфігураціями, скриптами та кодом - це WIP.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user