Go Modules

Go Modules — это официальная система управления зависимостями и версиями пакетов в Go‐проектах, предназначенная для решения ограничений модели GOPATH. Ключевые цели системы^[3]:

1. Декларативное объявление зависимостей и их точных версий в файле go.mod.
2. Проверка целостности кодовой базы через контрольные суммы, хранящиеся в go.sum.
3. Воспроизводимость сборок вне зависимости от среды разработчика.
4. Семантическое версионирование библиотек.
5. Возможность размещать проект вне каталога $GOPATH.
6. Упрощённая совместная работа команд разработчиков — все необходимые пакеты загружаются командой go автоматически.

• go.mod — корневой файл модуля, содержащий его путь, минимальную требуемую версию Go и список зависимостей^[4].
• go.sum — автоматически формируемый файл контрольных сумм всех прямых и транзитивных зависимостей; гарантирует неизменность их содержимого^[5].

• module — задаёт путь (import path) текущего модуля, служащий его уникальным идентификатором^[3].
• go — фиксирует минимальную версию Go, с которой корректно компилируется модуль; с Go 1.21 эта директива стала обязательной^[3].
• require — объявляет зависимость от конкретной версии другого модуля; допускает суффикс // indirect для транзитивных зависимостей^[2].
• replace — заменяет указанную версию модуля альтернативным источником (включая локальный каталог) ― удобно для локальной отладки^[4].
• exclude — запрещает использование конкретной версии модуля в графе зависимостей, вынуждая систему выбрать другую совместимую версию^[3].

Работа с Go Modules включает несколько последовательных этапов, каждый из которых реализуется отдельными командами и действиями.

На этом этапе создаётся новый модуль и формируется файл go.mod, фиксирующий путь модуля.

• Используется команда go mod init <имя-модуля>.
• В go.mod автоматически прописывается путь модуля и минимальная версия Go^[6].

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

• Команда go get <путь>@<версия> загружает новый пакет или обновляет версию существующего.
• Оба служебных файла (go.mod и go.sum) обновляются автоматически^[2].

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

• Команда go mod tidy анализирует исходный код и приводит go.mod и go.sum к актуальному состоянию.
• Удаляются неиспользуемые модули, добавляются отсутствующие^[5].

Все необходимые модули загружаются и кешируются для ускорения сборки, особенно в CI/CD.

• Используется команда go mod download.
• Это позволяет подготовить окружение для офлайн-сборки и ускоряет пайплайны^[7].

Внешние зависимости копируются в локальный каталог vendor/.

• Команда go mod vendor создаёт структуру vendor/ с исходниками всех внешних модулей.
• Это обеспечивает герметичность сборки и возможность работы без доступа к интернету^[8].

Проверяется соответствие контрольных сумм загруженных пакетов данным из go.sum.

• Команда go mod verify сверяет контрольные суммы всех зависимостей.
• Позволяет выявить повреждённые или подменённые пакеты^[9].

• Изоляция зависимостей каждого проекта и отсутствие конфликтов версий^[10].
• Детерминированные сборки благодаря файлам go.mod и go.sum^[11].
• Свободное расположение исходного кода вне $GOPATH^[1].
• Удобные механизмы замены и исключения модулей для локальной разработки.
• Возможность создания герметичных сборок посредством вендоринга.

• Размер репозитория возрастает при использовании vendor/^[12].
• Необходимость миграции старых проектов с модели GOPATH.
• Ручные изменения кода при переходе на новые мажорные версии библиотек^[13].
• Потенциальные сложности с приватными репозиториями и CI/CD-доступом^[12].

• Разработка веб-служб и микросервисов — управление зависимостями фреймворков и клиентов БД.
• Корпоративные приложения с приватными библиотеками.
• Пакетирование общих SDK и CLI-утилит для последующего распространения.
• Образовательные проекты и примеры кода, требующие воспроизводимых сборок.

• go mod graph — вывод полного графа зависимостей в формате «родитель → дочерний»^[14].
• go mod why <пакет> — показывает путь, по которому пакет попал в проект^[15].
• go mod edit — программное редактирование файла go.mod (добавление, замена, исключение модулей)^[16].

• proxy.golang.org — официальный общедоступный прокси и кэш модулей^[17].
• goproxy.io — глобальная сеть зеркал, популярная в Азии.
• Athens — open-source-прокси, развёртываемый внутри организации^[18].

Работа с прокси регулируется переменными окружения:

• GOPROXY — список прокси (по умолчанию https://proxy.golang.org,direct).
• GOPRIVATE, GONOPROXY — шаблоны путей приватных модулей.
• GOSUMDB, GONOSUMDB — включают или отключают проверку контрольных сумм.

• pkg.go.dev — официальный каталог, отображающий документацию и историю версий модулей^[19].