📁 Модули и структура проекта
Любой проект на 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.yamlmain.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/ordergo 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» — обсуждение, почему популярная схема не стандарт