[Обязательно к просмотру] Стандартный макет проекта Go

Go
[Обязательно к просмотру] Стандартный макет проекта Go

Original link: GitHub.com/go wave-beach…

Это базовая схема проекта приложения Go. Это не официальный стандарт, определенный основной командой разработчиков Go, однако это общий набор шаблонов компоновки для старых и новых проектов в экосистеме Go. Некоторые из этих режимов более популярны, чем другие. Он также имеет множество небольших улучшений, а также несколько каталогов поддержки, общих для любого достаточно большого практического приложения.

Если вы пытаетесь изучить Go или создаете PoC или игрушечный проект для себя, этот макет проекта не нужен. Начните с чего-нибудь очень простого (сmain.goдокументации более чем достаточно). По мере роста вашего проекта помните, что важно поддерживать хорошую структуру кода, иначе вы получите беспорядочный код с множеством скрытых зависимостей и глобального состояния. Чем больше людей работает над проектом, тем больше структуры вам понадобится. На этом этапе важно представить общий способ управления пакетами/библиотеками. Когда у вас есть проект с открытым исходным кодом или когда вы знаете, что другие проекты импортируют код из вашего репозитория проекта, самое время иметь частный (он жеinternal) пакет и код важны. Клонируйте репозиторий, оставьте то, что вам нужно, удалите все остальное!То, что оно есть, не означает, что вы должны использовать его все. Ни один из этих шаблонов не используется в каждом проекте. четноеvendorУзоры тоже не универсальны.

Go 1.14 Go ModulesНаконец готов к производству. Если у вас нет особой причины не использовать их, используйтеGo Modules. Если вы используете, вам не нужно беспокоиться о $GOPATH и о том, где находится ваш проект. в хранилищеgo.modФайлы в основном предполагают, что ваш проект размещен на Github, но это не обязательно. Путь к модулю может быть где угодно, хотя первый компонент пути к модулю должен иметь точку в имени (текущие версии Go больше не применяют этот модуль, но при использовании немного более старой версии, если нетmodНе удивляйтесь, если сборка файла завершится ошибкой). Если вы хотите узнать больше, см. Проблемы37554и32819.

Этот макет проекта является общим и не пытается навязать определенную структуру пакета Go.

Это усилия сообщества. Если вы видите новую схему или считаете, что существующая схема нуждается в обновлении, отправьте сообщение о проблеме.

Чтобы получить помощь по именованию, форматированию и стилю, запуститеgofmtиgolint. Также обязательно ознакомьтесь с этими рекомендациями и советами по стилю кода Go:

видетьGo Project LayoutУзнайте больше справочной информации.

Дополнительные советы по именованию и организации пакетов и другой структуре кода:

Перейти в каталог

/cmd

Основа этого проекта.

Имя каталога для каждого приложения должно совпадать с именем исполняемого файла, который вы хотите (например,/cmd/myapp).

Не помещайте слишком много кода в этот каталог. Если вы считаете, что код можно импортировать и использовать в других проектах, он должен находиться в/pkgв каталоге. Если код нельзя использовать повторно или вы не хотите, чтобы его использовали другие, поместите код в/internalв каталоге. Вы будете поражены тем, что сделают другие, так что будьте ясны в своих намерениях!

обычно имеют небольшойmainфункция, от/internalи/pkgИмпорт каталога и код вызова, больше ничего.

Для примера см./cmdсодержание.

/internal

Частное приложение и код библиотеки. Здесь вы не хотите, чтобы другие люди импортировали код в свое приложение или библиотеку. Обратите внимание, что этот шаблон компоновки применяется самим компилятором Go. См. Go 1.4 для более подробной информации.release notes. Обратите внимание, что вы не ограничены верхним уровнемinternalсодержание. На любом уровне дерева проекта может быть несколько внутренних каталогов.

При желании вы можете добавить некоторую дополнительную структуру во внутренний пакет, чтобы разделить общий и не общий внутренний код. Это не обязательно (особенно для небольших проектов), но хорошо иметь визуальные подсказки, чтобы показать предполагаемое использование пакета. Ваш фактический код приложения может быть помещен в/internal/appкаталог (например,/internal/app/myapp), код, используемый этими приложениями, может быть помещен в/internal/pkgкаталог (например,/internal/pkg/myprivlib).

/pkg

библиотечный код, который может использоваться внешними приложениями (например,/pkg/mypubliclib). Другие проекты будут импортировать эти библиотеки в надежде, что они будут работать, так что дважды подумайте, прежде чем размещать что-либо здесь :-) Обратите внимание,internalКаталоги — это лучший способ гарантировать, что частные пакеты не будут импортированы, поскольку это обеспечивается Go./pkgКаталоги по-прежнему являются хорошим способом явно указать, что код в этом каталоге является хорошим способом безопасного использования другими. Автор Трэвис ДжеффриI'll take pkg over internalсообщение в блоге предоставляетpkgиinternalХороший обзор директорий и когда имеет смысл их использовать.

Это также способ сгруппировать код Go в одном месте, когда корневой каталог содержит множество компонентов и каталогов, отличных от Go, что упрощает запуск различных инструментов Go (как упоминалось в этих докладах: через GopherCon EU 2018).Best Practices for Industrial Programming , GopherCon 2018: Kat Zien - How Do You Structure Your Go AppsиGoLab 2018 - Massimiliano Pippi - Project layout patterns in Go).

Если вы хотите узнать, какой популярный репозиторий Go использует этот шаблон макета проекта, проверьте/pkgсодержание. Это распространенный шаблон компоновки, но не все его принимают, а некоторые в сообществе Go не рекомендуют его.

Если проект вашего приложения действительно мал, а дополнительная вложенность не добавляет большой ценности (если вы действительно этого не хотите :-), то не используйте его. Когда он становится достаточно большим, ваш корневой каталог может стать очень громоздким (особенно если у вас много компонентов приложения, отличного от Go), подумайте об этом.

/vendor

Зависимости приложений (управляйте вручную или используйте свой любимый инструмент управления зависимостями, например новый встроенныйGo ModulesФункции).go mod vendorкоманда создаст для вас/vendorсодержание. Обратите внимание: если вы не используете Go 1.14, который включен по умолчанию, вам может потребоватьсяgo buildдобавить в команду-mod=vendorлоготип.

Если вы создаете библиотеку, не фиксируйте зависимости приложения.

Обратите внимание, что поскольку1.13Позже Go также включил функцию прокси-модуля (по умолчанию с использованиемhttps://proxy.golang.orgв качестве прокси-сервера своего модуля). существуетhereУзнайте больше об этом и посмотрите, соответствует ли он всем вашим потребностям и ограничениям. Если вам это нужно, то вам это вообще не нужноvendorсодержание.

Функция прокси-сервера внутреннего модуля по умолчанию заблокирована, и у Qiniuyun есть специальное обслуживание.模块代理.

Каталог сервисных приложений

/api

Спецификация OpenAPI/Swagger, файл схемы JSON, файл определения протокола.

Для примера см./apiсодержание.

каталог веб-приложений

/web

Компоненты, специфичные для веб-приложений: статические веб-ресурсы, серверные шаблоны и SPA.

Универсальный каталог приложений

/configs

Шаблон профиля или конфигурация по умолчанию.

положить вашиconfdилиconsul-templateЗдесь размещаются файлы шаблонов.

/init

Инициализация системы (systemd, upstart, sysv) и конфигурация диспетчера процессов/супервизора (runit, супервизор).

/scripts

Скрипты, которые выполняют различные сборки, установки, анализ и многое другое.

Эти сценарии делают Makefile корневого уровня небольшим и простым (например,https://github.com/hashicorp/terraform/blob/master/Makefile).

Для примера см./scriptsсодержание.

/build

Пакет и непрерывная интеграция.

Поместите конфигурацию вашего облака (AMI), контейнер (Docker), ОС (deb, rpm, pkg) и скрипты в/build/packageПод содержанием.

Поместите свой CI (travis, Circle, Drone) конфиг и скрипты в/build/ciв каталоге. Обратите внимание, что некоторые инструменты непрерывной интеграции (например, Travis CI) очень требовательны к расположению файлов конфигурации. попробуй закинуть конфиг файл/build/ciкаталог, свяжите их с тем, где их ожидает инструмент CI (если возможно).

/deployments

Конфигурации и шаблоны развертывания IaaS, PaaS, системы и контейнера (docker-compose, kubernetes/helm, mesos, terraform, bosh). Обратите внимание, что в некоторых репозиториях (особенно в приложениях, развернутых с помощью kubernetes) этот каталог называется/deploy.

/test

Дополнительные внешние тестовые приложения и тестовые данные. Вы всегда можете построить в соответствии с вашими потребностями/testсодержание. Для больших проектов имеет смысл иметь подкаталог данных. Например, вы можете использовать/test/dataили/test/testdata(если вам нужно игнорировать содержимое каталога). Обратите внимание, что Go также игнорирует каталоги или файлы, начинающиеся с «.» или «_», поэтому существует больше гибкости в том, как называется каталог тестовых данных.

Для примера см./testсодержание.

другие каталоги

/docs

Дизайн и пользовательская документация (в дополнение к документации, созданной godoc).

Для примера см./docsсодержание.

/tools

Инструменты поддержки для этого проекта. Обратите внимание, что эти инструменты доступны из/pkgи/internalКод импорта каталога.

Для примера см./toolsсодержание.

/examples

Примеры вашего приложения и/или публичной библиотеки.

Для примера см./examplesсодержание.

/third_party

Внешние помощники, разветвленный код и другие сторонние инструменты (например, Swagger UI).

/githooks

Гит хуки.

/assets

Другие активы (изображения, логотипы и т. д.), которые можно использовать с репозиторием.

/website

Если вы не используете страницы Github, здесь вы размещаете данные веб-сайта своего проекта.

Для примера см./websiteсодержание.

Каталоги, которых у вас не должно быть

/src

Некоторые проекты Go имеютsrcпапку, но это обычно происходит, когда разработчик имеет опыт работы с Java, где это распространенный шаблон. Если можете, постарайтесь не использовать этот шаблон Java. Вы действительно не хотите, чтобы ваш код Go или проект Go выглядели как Java :-)

Не назначать уровень проектаsrcКаталоги такие же, как то, что Go использует для своего рабочего пространства.srcкаталог (например,How to Write Go Codeописано в) путаница.$GOPATHПеременная среды указывает на вашу (текущую) рабочую область (по умолчанию она указывает на$HOME/go). Это рабочее пространство включает верхний этаж/pkg, /binи/srcсодержание. Ваш фактический проект заканчивается/srcподкаталог в , поэтому, если ваш проект имеет/srcкаталог, то путь к проекту будет таким:/some/path/to/workspace/src/your_project/src/your_code.go. Обратите внимание, что в Go 1.11 можно помещать элементы вGOPATH, но это не значит, что использовать этот режим макета — хорошая идея.

Badges

  • Go Report Card - It will scan your code with gofmt, go vet, gocyclo, golint, ineffassign, license and misspell. Replace github.com/golang-standards/project-layout with your project reference.

  • GoDoc - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.

  • Release - It will show the latest release number for your project. Change the github link to point to your project.

Go Report Card Go Doc Release

Notes

A more opinionated project template with sample/reusable configs, scripts and code is a WIP.

Категории