Это базовый макет организации проектов, разработанных на Golang. Это не официально определенный командой разработчиков Golang стандарт, однако он удовлетворяет исторически сложившимся шаблонам организации проекта в экосистеме Golang. Некоторые из шаблонов могут быть известнее остальных. В макете также присутствуют несколько улучшений, включая дополнительные директории, используемые в любом достаточно большом реальном приложении.
Это базовый макет организации проектов, разработанных на Go. Это **не официально определенный командой разработчиков Go стандарт**, однако он удовлетворяет исторически сложившимся шаблонам организации проекта в экосистеме Go. Некоторые из шаблонов могут быть известнее остальных. В макете также присутствуют несколько улучшений, включая дополнительные директории, используемые в любом достаточно большом реальном приложении.
Если вы пытаетесь изучить Golang или собрать маленький обучающий проект для личного пользования, данный макет будет явным перебором. Стоит начать с чего-нибудь действительно простого (одного файла `main.go` будет достаточно). Как только ваш проект начнет расти, стоит задуматься оважности содержания кода в структурированном состоянии, чтобы в конечном итоге не получить грязный код с множеством скрытых зависимостей и global state. А когда над проектом начнут работать другие люди - понадобится еще большая структуризация. В этот момент важно определить стандартный путь организации пакетов/библиотек. Если вы разрабатываете проект с открытым исходным кодом или знаете, что вашим кодом будут пользоваться при разработке других проектов, необходимо понимать важность создания личных, внутренних (или `internal`) пакетов и кода. Склонируйте репозиторий, пользуйтесь тем, что действительно нужно,и удалите всё остальное! Наличие этого "всего остального" вовсе не означает, что это обязательно использовать. Заметьте, что ни один из этих шаблонов не обязан быть использован в абсолютно каждом проекте. Даже `vendor` не может быть универсален во всех случаях.
**Если вы пытаетесь изучить Go или же создать демо проект или маленький обучающий проект для личного пользования, данный макет будет явным перебором. Стоит начать с чего-нибудь действительно простого (одного файла `main.go`и `go.mod`будет достаточно)**. Как только ваш проект начнет расти, стоит задуматься о необходимости содержания вашего кода в структурированном состоянии, чтобы в конечном итоге не получить грязный код с множеством скрытых зависимостей и глобальным состоянием. А когда над проектом начнут работать другие люди - понадобится еще большая структуризация. В этот момент важно определить стандартный подход к организации пакетов/библиотек. Если вы разрабатываете проект с открытым исходным кодом или знаете, что вашим пакетом/библиотекой будут пользоваться при разработке других проектов, необходимо понимать важность создания личных, внутренних (или `internal`) пакетов и кода. Сделайте копию репозитория, пользуйтесь тем, что действительно нужно,и удалите всё остальное! Наличие "всего остального" вовсе не означает, что это обязательно использовать. Хочется заметить, что ни один из этих шаблонов не обязан быть использован в абсолютно каждом проекте. Даже `vendor` не может быть универсален во всех случаях.
С выходом обновления Golang 1.14, [`Go Modules`](https://github.com/golang/go/wiki/Modules) стали наконец-то доступны для использования. Применяйте [`Go Modules`](https://blog.golang.org/using-go-modules) везде, пока не столкнётесь с веской причиной отказаться от них, и если такой момент всё же настанет - вам больше не придётся волноваться о значении переменной окружения $GOPATH и месте, где вы размещаете свой проект. Базовый `go.mod` файл в репозитории показывает, что ваш проект размещён на GitHub, однако он не является обязательным. Путь к модулю может быть любым, при условии, что первый компонент пути должен содержать точку в имени (текущая версия Golang больше не требует этого, но если вы используете достаточно устаревшие версии - не стоит удивляться, что ваши сборки могу перестать работать). Ознакомьтесь с проблемами: [`37554`](https://github.com/golang/go/issues/37554) и [`32819`](https://github.com/golang/go/issues/32819) если хотите узнать об этом больше.
С выходом обновления Golang 1.14, [`Go Modules`](https://github.com/golang/go/wiki/Modules) стали наконец-то доступны для использования. Применяйте [`Go Modules`](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) если хотите узнать об этом больше.
Этот шаблон организации проекта намеренно сделан обобщенным, и не является примером структуры какого-то конкретного пакета Golang.
Этот шаблон организации проекта намеренно сделан обобщенным, и не является примером структуры какого-то конкретного пакета Go.
Этот репозиторий открыт к участию сообщества. Создайте заявку о проблеме, если вы нашли новый шаблон или считаете, что один из существующих шаблонов необходимо обновить.
Этот проект открыт сообществу для улучшения. Создайте заявку о проблеме, если вы нашли новый шаблон или считаете, что один из существующих шаблонов необходимо обновить.
Если вам нужна помощь в наименовании, форматировании или стилизации кода - начните с [`gofmt`](https://golang.org/cmd/gofmt/) и [`golint`](https://github.com/golang/lint). Также обязательно прочтите эти руководства по стилизации кода Golang и рекомендации:
Если вам нужна помощь в наименовании, форматировании или стилизации кода - начните с [`gofmt`](https://golang.org/cmd/gofmt/) и [`golint`](https://github.com/golang/lint). Также обязательно прочтите эти руководства по стилю для кода на Go и рекомендации:
* https://talks.golang.org/2014/names.slide
* https://golang.org/doc/effective_go.html#names
* https://blog.golang.org/package-names
@ -46,55 +46,55 @@ Translations:
* [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)
Пост о руководствах по пакетноориентированному дизайну и макетам архитектур
Пост о руководствах по пакетно-ориентированному дизайну и архитектурным слоям
Имя директории для каждого приложения должно совпадать с именем исполняемого файла, который вы хотите собрать (например, `/cmd/myapp`).
Не стоит располагать в этой директории большие объёмы кода. Если вы предполагаете дальнейшее использование кода в других проектах, вам стоит хранить его в директории `/pkg` в корне проекта. Если же код не должен быть переиспользован где-то еще - ему самое место в директории `/internal` в корне проекта. Вы будете удивлены тем, что могут сделать другие люди, по
тому выражайте свои намерения явно!
Самой распространнёной практикой является использование маленькой `main` функции, которая импортирует и вызывает весь необходимый код из директорий `/internal` и `/pkg` и никаких других.
Самой распространённой практикой является использование маленькой `main` функции, которая импортирует и вызывает весь необходимый код из директорий `/internal` и `/pkg`, но не из других.
Ознакомьтесь с директорией [`/cmd`](cmd/README.md) для примера.
Примеры смотрите в директории [`/cmd`](cmd/README.md).
### `/internal`
Внутренний код приложения и библиотек. Это код, который не должен быть применен в других приложениях и библиотеках. Стоит отметить, что этот шаблон навязан самим компилятором Golang. Ознакомьтесь с [`release notes`](https://golang.org/doc/go1.4#internalpackages) Go 1.4. Также, вы вольны использовать `internal`директорию на разных уровнях своего проекта.
Внутренний код приложения и библиотек. Это код, который не должен использоваться в других приложениях и библиотеках. Стоит отметить, что этот шаблон применяется самим компилятором Golang. Ознакомьтесь с [`release notes`](https://golang.org/doc/go1.4#internalpackages) Go 1.4 для более детальной информации. Также, вы вольны использовать более одной директории `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` - более оптимальный способ не дать импортировать внутренние пакеты, потому что это обеспечит сам Golang. Директория `/pkg` - всё еще хороший путь дать понять, что код в этой директории могут безопасно использовать другие. Пост [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) в блоге Трэвиса Джеффери предоставляет хороший обзор директорий `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` и когда есть смысл их использовать.
Существует возможность группировать код на Golang в одном месте, когда ваша корневая директория содержит множество не относящихся к 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 в одном месте, когда ваша корневая директория содержит множество не относящихся к 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)).
Ознакомьтесь с директорией [`/pkg`](pkg/README.md), если хотите увидеть, какие популярные репозитории используют такой шаблон организации проекта. Несмотря на его распространенность, он не был принят всеми, а некоторые в сообществе Go и вовсе не рекомендует его использовать.
Ознакомьтесь с директорией [`/pkg`](pkg/README.md), если хотите увидеть, какие популярные репозитории используют этот макет для организации проекта. Это часто используемый макет, но он не общепринятый, а некоторые в сообществе Go и вовсе не рекомендует его использовать.
Вы можете не использовать эту директорию, если проект совсем небольшой и добавление нового уровня вложенности не имеет практического смысла (разве что вы сами этого не хотите :-)). Подумайте об этом, когда ваша корневая директория начинает слишком сильно разрастаться, особенно, если у вас много компонентов, написанных не на Go.
Вы можете не использовать эту директорию, если проект совсем небольшой и добавление нового уровня вложенности не несет практического смысла (разве что вы сами этого не хотите). Подумайте об этом, когда ваша корневая директория начинает слишком сильно разрастаться, особенно, если у вас много компонентов, написанных не на Go.
### `/vendor`
Зависимости приложений, управляемые вручную или с использованием вашей любимой системы управления зависимостями, вроде новых встроенных [`Go Modules`](https://github.com/golang/go/wiki/Modules)). Команда `go mod vendor` создаст для вас директорию `/vendor`. Заметьте, что вам возможно придётся добавить флаг `-mod=vendor` к команде `go build`, если вы используете версию, отличную от Go 1.14, где такой флаг выставлен по-умолчанию.
Зависимости приложений, управляемые вручную или с использованием вашей любимой системы управления зависимостями, вроде новыго, доступных из коробки [`Go Modules`](https://github.com/golang/go/wiki/Modules). Команда `go mod vendor` создаст для вас директорию `/vendor`. Обратите внимание, что вам возможно придётся добавить флаг `-mod=vendor` к команде `go build`, если вы используете версию, отличную от Go 1.14, где такой флаг выставлен по-умолчанию.
Не стоит отправлять зависимости вашего приложения в репозиторий, если собираетесь создавать библиотеку.
Стоит отметить, что с версии [`1.13`](https://golang.org/doc/go1.13#modules) Go добавил возможность проксирования модулей (с использованием [`https://proxy.golang.org`](https://proxy.golang.org) как прокси-сервера по-умолчанию). [`Здесь`](https://blog.golang.org/module-mirror-launch) можно побольше узнать про эту возможность, чтобы убедиться, что она удовлетворяет вашим необходимостям и ограничениям. Если это так - использование директории `vendor` не требуется вовсе.
Стоит отметить, что начиная с версии [`1.13`](https://golang.org/doc/go1.13#modules) Go добавил возможность проксирования модулей (с использованием [`https://proxy.golang.org`](https://proxy.golang.org) как прокси-сервера по-умолчанию). [`Здесь`](https://blog.golang.org/module-mirror-launch) можно побольше узнать про эту возможность, чтобы убедиться, что она удовлетворяет вашим требованиям и ограничениям. Если это так - использование директории `vendor` не требуется вовсе.
## Директории приложений-сервисов
### `/api`
Спецификации OpenAPI/Swagger, файлы JSON schema, файлы определения протоколов.
Спецификации OpenAPI/Swagger, JSON schema файлы, файлы определения протоколов.
Ознакомьтесь с директорией [`/api`](api/README.md) для примеров.
Примеры смотрите в директории [`/api`](api/README.md).
## Директории Веб-приложений
@ -108,19 +108,19 @@ Translations:
Шаблоны файлов конфигураций и файлы настроек по-умолчанию.
Положите файлы конфигураций `confd` или `consul-template` сюда.
Поместите файлы конфигураций `confd` или `consul-template` сюда.
### `/init`
Файлы конфигураций для процессов инициализации системы (systemd, upstart, sysv) и менеджеров процессов (runit, supervisord).
Файлы конфигураций для инициализации системы (systemd, upstart, sysv) и менеджеров процессов (runit, supervisord).
### `/scripts`
Скрипты для сборки, установки, анализа и прочих операций над проектом.
Скрипты для выполнения различных операций сборки, установки, анализа и т.п. операций.
Эти скрипты позволяют оставить основной Makefile небольшим и простым (например, [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)).
Ознакомьтесь с директорией [`/scripts`](scripts/README.md) для примеров.
Примеры смотрите в директории [`/scripts`](scripts/README.md).
### `/build`
@ -128,37 +128,37 @@ Translations:
Поместите файлы конфигурации и скрипты облака (AMI), контейнера (Docker), пакетов (deb, rpm, pkg) в директорию `/build/package`.
Поместите ваши файлы конфигурации CI (travis, circle, drone) и скрипты в директорию `/build/ci`. Заметьте, что некоторые инструменты CI (например, Travis CI) очень требовательны к расположению их конфигурационных файлов. Попробуйте поместить их в директорию `/build/ci` создав ссылку на них в месте, где их ожидают найти инструменты Go (если возможно).
Поместите ваши файлы конфигурации CI (travis, circle, drone) и скрипты в директорию `/build/ci`. Обратите внимание, что некоторые инструменты CI (например, Travis CI) очень требовательны к расположению их конфигурационных файлов. Попробуйте поместить конфигурационные файлы в директорию `/build/ci` создав ссылку на них в месте, где их ожидают найти CI инструменты (если возможно).
### `/deployments`
Шаблоны и файлы конфигураций систем оркестраций IaaS, PaaS, операционных систем и контейнеров (docker-compose, kubernetes/helm, mesos, terraform, bosh). Отметьте, что в некоторых репозиториях, особенно в приложениях, развернутых с использованием Kubernetes, эта директория называется `/deploy`.
Шаблоны и файлы конфигураций разворачивания IaaS, PaaS, системной и контейнерной оркестрации (docker-compose, kubernetes/helm, mesos, terraform, bosh). Стоит заметить, что в некоторых репозиториях (особенно в приложениях, развернутых с использованием Kubernetes) эта директория называется `/deploy`.
### `/test`
Дополнительные внешние приложения и данные для тестирования. Вы вольны организовывать структуру директории `/test` так, как вам угодно. Для больших проектов имеет смысл создавать вложенную директорию с данными для тестов. Например,`/test/data` или `/test/testdata`, если вы хотите, чтобы Go игнорировал находящиеся там файлы. Отметьте, что Go будет также игнорировать файлы, путь к которым начинается с "." или "_", что предоставляет вам гибкость в наименовании вашей папки с тестами.
Дополнительные внешние тестовые приложения и данные для тестирования. Вы вольны организовывать структуру директории `/test` так, как вам угодно. Для больших проектов имеет смысл создавать вложенную директорию с данными для тестов. Например,`/test/data` или `/test/testdata`, если вы хотите, чтобы Go игнорировал находящиеся там файлы. Стоит заметить, что Go будет также игнорировать файлы, путь к которым начинается с "." или "_", что предоставляет вам гибкость в наименовании вашей директории с тестовыми данными.
Ознакомьтесь с директорией [`/test`](test/README.md) для примеров.
Примеры смотрите в директории [`/test`](test/README.md).
## Другие Директории
### `/docs`
Документы пользователей и дизайна (в дополнение к автоматической документации godoc).
Проектная и пользовательская документация (в дополнение к документации сгенерированной godoc).
Ознакомьтесь с директорией [`/docs`](docs/README.md) для примеров.
Примеры смотрите в директории [`/docs`](docs/README.md).
### `/tools`
Инструменты поддержки проекта. Отметьте, что эти инструменты могут импортировать код из директорий `/pkg` и `/internal`.
Инструменты поддержки проекта. Обратите внимание, что эти инструменты могут импортировать код из директорий `/pkg` и `/internal`.
Ознакомьтесь с директорией [`/tools`](tools/README.md) для примеров.
Примеры смотрите в директории [`/tools`](tools/README.md).
### `/examples`
Примеры ваших приложений и/или библиотек.
Ознакомьтесь с директорией [`/examples`](examples/README.md) для примеров.
Примеры смотрите в директории [`/examples`](examples/README.md).
### `/third_party`
@ -170,21 +170,21 @@ Git hooks.
### `/assets`
Другие ресурсы, необходимые для работы (картинки, логотипы и т.д.)
Другие ресурсы, необходимые для использования вашего репозитория (изображения, логотипы и т.д.)
### `/website`
Здесь можно разделить файлы для вебсайта вашего проекта, если вы не используете `GitHub pages`.
Здесь можно разделить файлы для сайта вашего проекта, если вы не используете `GitHub pages`.
Ознакомьтесь с директорией [`/website`](website/README.md) для примеров.
Примеры смотрите в директории [`/website`](website/README.md).
## Директории, которые не стоит размещать у себя в проекте
### `/src`
Некоторые проекты на Go имеют директорию `src`, но это обычно происходит, когда разработкой занялся человек, пришедший из мира Java, где такой подход весьма распространен. Постарайтесь не использовать его в разработке на Golang, если не хотите, чтобы ваш код или проект выглядел, будто написан на 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/your_project/src/your_code.go`. Отметьте, что в версиях после Go 1.11 возможно хранить проект отдельно от локации, описанной в`GOPATH`, но это всё еще не значит, что применять этот 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/your_project/src/your_code.go`. Стоит заметить, что в версиях Go начиная с 1.11 ваш проект может хранить за пределами вашего`GOPATH`, но это всё еще не значит, что применять этот шаблон компоновки - это хорошая идея.
* [GoDoc](http://godoc.org) - Предоставит онлайн версию вашей сгенерированной GoDoc документации
* ~~[GoDoc](http://godoc.org) - Предоставит онлайн версию вашей сгенерированной GoDoc документации. Измените ссылку, чтобы она указывала на ваш проект.~~
* [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev is a new destination for Go discovery & docs. You can create a badge using the [badge generation tool](https://pkg.go.dev/badge).
* [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev это новое место для исследования Go и документации. Вы можете создать бейдж с помощью [badge generation tool](https://pkg.go.dev/badge).
Kyle Quest
11 months ago
committed by
GitHub