К содержимому
Войти

Go Road Map

📁 Модули и структура проекта

Любой проект на Go начинается с файла go.mod, и в первый рабочий день ты увидишь его раньше, чем код. Он решает, какие версии зависимостей попадут в сборку, какие возможности языка доступны и даже как ведёт себя рантайм. Вторая половина темы — раскладка папок: где main, куда класть бизнес-логику и почему internal здесь важнее любой модной схемы. На собеседовании об этом спрашивают коротко, но по ответу сразу видно, писал ли человек сервисы сам

🧠 Как это устроено

Модуль, пакет, репозиторий

Пакет — одна папка с .go-файлами, у всех файлов одно имя в package. Модуль — дерево пакетов с общим go.mod в корне, он версионируется и скачивается целиком. Репозиторий обычно содержит один модуль, и путь модуля совпадает с адресом репозитория:

module github.com/acme/shop

go 1.26

require (
	github.com/jackc/pgx/v5 v5.12.0
	golang.org/x/sync v0.24.0 // indirect
)

Путь импорта складывается из пути модуля и папки: пакет из internal/order импортируется как github.com/acme/shop/internal/order. Отсюда первое правило: путь в module должен совпадать с тем, откуда модуль скачают, иначе чужой go get не найдёт код

Что значит строка go

С Go 1.21 строка go — жёсткий минимум, а не пожелание. Компилятор не даст использовать возможности языка новее этой версии, а старый тулчейн откажется собирать модуль, которому нужен новый. По умолчанию GOTOOLCHAIN=auto, поэтому вместо отказа go сам скачает нужную версию тулчейна как модуль golang.org/toolchain и запустит её. В CI это видно как загрузка тулчейна на первом шаге, и это нормально

Строка go включает и поведение. Переменная цикла на каждой итерации появилась в Go 1.22 только для модулей с go 1.22 и выше. GOMAXPROCS по лимиту контейнера рантайм считает только при go 1.25 и выше, это разобрано на странице про Go в контейнере. Поднять строку go — значит поменять семантику кода, а не только номер в файле

Как выбираются версии: MVS

В Go нет решателя зависимостей, как в npm или pip. Работает minimal version selection: go проходит по графу require и для каждого модуля берёт наибольшую из требуемых версий. Если твой сервис требует x v1.2.0, а библиотека внутри требует x v1.5.0, в сборку попадёт v1.5.0. Даже если вышла v1.9.0, её не возьмут, пока кто-то в графе не попросит

Из этого следуют две вещи. Сборка воспроизводима без отдельного lock-файла: тот же go.mod даёт тот же набор версий завтра и через год. А обновление всегда явное, через go get. Полный итоговый список показывает go list -m all

go.sum — не lock-файл

Здесь ошибаются чаще всего. Версии фиксирует go.mod, а go.sum хранит хэши: по строке на архив модуля и на его go.mod, алгоритм SHA-256 (h1:). При скачивании go сверяет архив с go.sum, а для новых модулей — с публичной базой sum.golang.org. Если кто-то подменил тег в репозитории, хэш не сойдётся и сборка упадёт. Поэтому go.sum коммитят всегда

Скачивает go по умолчанию через прокси https://proxy.golang.org,direct. Для внутренних модулей компании нужен GOPRIVATE=gitlab.company.ru/*: такие пути идут напрямую в git и не проверяются в публичной базе хэшей, иначе их имена утекли бы наружу

Мажорная версия — часть пути

Модуль версии v2 и выше обязан кончаться на /v2: github.com/jackc/pgx/v5. Для go это разные модули, поэтому v4 и v5 одной библиотеки могут жить в одной сборке. Ломающее изменение API в библиотеке — это новый путь и правка всех импортов у пользователей, а не просто новый тег

internal

Пакет, в пути которого есть папка internal, может импортировать только код из дерева с корнем в родителе этой папки. github.com/acme/shop/internal/order видят все пакеты github.com/acme/shop/... и никто снаружи. Правило проверяет компилятор, а не договорённость в команде:

package github.com/acme/billing
	main.go:3:8: use of internal package github.com/acme/shop/internal/order not allowed

Это главный инструмент раскладки. Всё, что лежит в internal, можно переименовывать и ломать без оглядки на чужой код

🛠️ На практике

Раскладка сервиса

Официальная страница Organizing a Go module для серверного проекта советует такую схему: команды в cmd/, вся логика в internal/, пакетов для экспорта нет. Понадобился пакет другим проектам — выносишь его в отдельный модуль

shop/
├── go.mod
├── go.sum
├── cmd/
│   ├── api/main.go        # HTTP-сервер
│   └── worker/main.go     # консьюмер очереди
├── internal/
│   ├── order/             # предметная область: заказы
│   ├── payment/
│   └── platform/
│       └── postgres/      # подключение к базе, общее для команд
├── migrations/
└── api/openapi.yaml

main.go здесь тонкий: прочитать конфиг, собрать зависимости, запустить сервер. Всё остальное лежит в пакетах, которые можно тестировать. Пакеты называются по предметной области (order, payment), а не по технической роли (models, utils, helpers). Пакет utils быстро становится свалкой, которую импортируют все, и из-за него появляются циклы

Почему standard layout не стандарт

Репозиторий golang-standards/project-layout с папками pkg/, configs/, init/, deployments/ и ещё десятком других часто называют стандартом. В его README прямо написано, что это не официальный стандарт команды Go. В 2021 году Расс Кокс из команды Go открыл там issue с заголовком «this is not a standard Go project layout»: большинство пакетов Go не кладут код в pkg/, а схема сложнее, чем нужно обычному проекту

Отсюда практическое правило. Начинай с одного пакета или с cmd/ и internal/, папки добавляй, когда они нужны. pkg/ в сервисе ничего не даёт: экспортировать сервису нечего, а для закрытия кода есть internal, который проверяет компилятор

Циклы импорта

Go запрещает циклические импорты. Если order импортирует payment, а payment импортирует order, сборка падает:

package github.com/acme/shop/cmd/api
	imports github.com/acme/shop/internal/order from main.go
	imports github.com/acme/shop/internal/payment from cycle.go
	imports github.com/acme/shop/internal/order from payment.go: import cycle not allowed

Обычно это значит, что граница пакетов проведена неудачно. Три рабочих выхода: вынести общий тип в третий пакет, который импортируют оба; объявить интерфейс в том пакете, которому нужна зависимость; или слить два пакета, если они не живут друг без друга. Где держать интерфейсы, разобрано на странице про слои и архитектуру этого модуля

Инструменты через tool

Раньше генераторы кода и линтеры фиксировали в проекте через файл tools.go с пустыми импортами. С Go 1.24 для этого есть директива tool:

go get -tool golang.org/x/tools/cmd/stringer
go tool stringer -type=Status ./internal/order

go get -tool дописывает в go.mod строку tool golang.org/x/tools/cmd/stringer и require на модуль, версия попадает под MVS и go.sum, как у любой зависимости. Вся команда работает с одной версией генератора, а в //go:generate можно писать go tool stringer без установки бинарника в $PATH. Собранный инструмент кэшируется: на Go 1.27.3 первый запуск go tool stringer занял 3 секунды, go generate с ним — 0,4 секунды

Версия в бинарнике

С Go 1.24 go build записывает в бинарник версию модуля из git-тега. Собрал сервис на теге v1.4.0, и go version -m покажет:

	path	github.com/acme/shop/cmd/api
	mod	github.com/acme/shop	v1.4.0
	build	vcs.revision=c53fee19f469f8c22dc99c97b5e73496c995c1da
	build	vcs.modified=false

Если в рабочей копии есть незакоммиченные правки, версия станет v1.4.0+dirty, а vcs.modified=true. Ту же информацию отдаёт debug.ReadBuildInfo() прямо из кода: удобно для эндпоинта /version и метрики с версией сборки

Несколько модулей рядом: go.work

Когда правишь сервис и библиотеку одновременно, не нужно публиковать библиотеку ради каждой строчки. go work init ./shop ./billing создаёт go.work, и go берёт оба модуля из локальных папок. Раньше то же делали через replace => ../billing в go.mod и забывали его удалить перед коммитом. go.work обычно в репозиторий не коммитят: он описывает раскладку папок на твоей машине, а не проекта

⚠️ Где ошибаются

  • Правят go.sum руками или удаляют его при конфликте. При мерже конфликт в go.sum решают так: берут обе стороны и запускают go mod tidy. Удалённый go.sum лишает сборку проверки хэшей
  • Забывают go mod tidy перед коммитом. В go.mod остаются ненужные зависимости или не хватает новых, и CI с -mod=readonly падает. Хорошая проверка в CI — go mod tidy и git diff --exit-code go.mod go.sum
  • Оставляют replace на локальную папку. У коллеги и в CI папки ../billing нет, сборка ломается. Для локальной работы есть go.work
  • Поднимают строку go, чтобы получить одну функцию стандартной библиотеки. Вместе с ней меняется поведение языка и рантайма, а все, кто импортирует твой модуль, будут вынуждены обновить тулчейн
  • Раскладывают пакеты по слоям на весь проект: models/, handlers/, services/. Изменение одной фичи задевает пять пакетов, а models импортируют все. Пакет по предметной области держит фичу в одном месте

🎯 Вопросы с собеседований

Чем go.mod отличается от go.sum?

go.mod описывает модуль: его путь, минимальную версию Go и требуемые версии зависимостей. По нему MVS выбирает набор версий для сборки. go.sum хранит SHA-256 хэши архивов и go.mod каждой версии, которую использовал проект, и при скачивании go сверяет с ними код. Версии фиксирует go.mod, а go.sum гарантирует, что под той же версией лежит тот же код. Коммитят оба

Как Go выбирает версию зависимости, если два пакета требуют разные?

Через minimal version selection: для каждого модуля берётся наибольшая из версий, которые требуются в графе. Сервис требует v1.2.0, библиотека — v1.5.0, в сборку пойдёт v1.5.0. Самую свежую версию из реестра go сам не берёт, поэтому сборка воспроизводима без lock-файла. Если нужны разные мажорные версии, это разные модули с суффиксом /v2, и они уживаются в одной сборке

Что такое internal и зачем он нужен?

Пакет внутри папки internal может импортировать только код из дерева с корнем в родителе этой папки. Проверяет это компилятор, ошибка «use of internal package not allowed». В сервисе в internal кладут почти всё: так код можно свободно менять, не боясь сломать чужие проекты. Публичным оставляют только то, что задумано как библиотека

Как ты организуешь структуру нового сервиса?

Начинаю с минимума: cmd/<имя>/main.go для каждой точки входа и internal/ для логики, пакеты по предметной области. main только собирает зависимости и запускает сервер. Папки вроде pkg/ не добавляю, их рекомендуют не официальные гайды Go, а сторонний репозиторий, который сам пишет, что он не стандарт. Ориентир — страница go.dev/doc/modules/layout

Почему в Go запрещены циклические импорты и что делать, если цикл появился?

Пакеты собираются и инициализируются по порядку зависимостей: сначала те, кого импортируют, потом те, кто импортирует. С циклом такого порядка нет. На практике цикл почти всегда значит, что два пакета на самом деле одно целое или делят общий тип. Решения: вынести общий тип в отдельный пакет, объявить интерфейс на стороне потребителя или слить пакеты

Зачем в пути модуля /v2?

Правило семантического импорта: модуль с мажорной версией 2 и выше обязан иметь суффикс /vN в пути. Ломающее изменение API меняет путь импорта, поэтому обновление на v2 не может произойти незаметно через go get -u. Побочный плюс: v1 и v2 одной библиотеки могут жить в одной сборке, пока зависимости мигрируют

Как подключить приватный модуль из корпоративного GitLab?

Задать GOPRIVATE с маской путей компании, например gitlab.company.ru/*. Тогда go идёт за ними напрямую в git, мимо proxy.golang.org, и не сверяет хэши с публичной sum.golang.org. Доступ к git настраивают как обычно, через SSH-ключ или токен в .netrc. В CI нужны те же переменная и доступ

Что изменилось с директивой tool в Go 1.24?

Раньше версии генераторов и линтеров фиксировали через tools.go с пустыми импортами под build-тегом. Теперь go get -tool <путь> добавляет в go.mod строку tool, а запускается инструмент через go tool <имя>. Версия инструмента выбирается и проверяется так же, как у остальных зависимостей, и у всей команды одна

Что такое vendor и когда он нужен?

go mod vendor копирует все зависимости в папку vendor/ в корне модуля. Если она есть, а строка go не ниже 1.14, go собирает из неё без сети и без кэша модулей. Нужен, когда сборка обязана работать в закрытом контуре без доступа к прокси, или когда компания требует хранить весь исходный код в своём репозитории. Цена — тысячи файлов в репозитории и диффы при каждом обновлении

📚 Что почитать

  • Organizing a Go module — официальные раскладки для библиотеки, команды и сервера, коротко и с примерами
  • Go Modules Reference — справочник по go.mod, MVS, go.sum, прокси и приватным модулям, читать по разделам
  • Go Toolchains — что делает строка go и как GOTOOLCHAIN подтягивает нужную версию
  • Issue «this is not a standard Go project layout» — обсуждение, почему популярная схема не стандарт