Модули Go: go.mod, go.sum и суффикс мажорной версии

Что это такое

Справочник Go Modules Reference определяет модуль как набор пакетов, выпускаемых вместе. В его корне находится go.mod, где указаны путь модуля, директива go (минимальная версия Go; с Go 1.21 она обязательна, а не рекомендательна), строки require и необязательные директивы replace, exclude, retract и toolchain. Версии следуют Semantic Versioning 2.0.0 с префиксом v. Справочник описывает minimal version selection: команда go обходит граф требований и собирает с наибольшей из требуемых версий каждого модуля; более новый выпуск не выбирается лишь потому, что существует. Поэтому список сборки воспроизводим на основе одного go.mod. В go.sum записаны криптографические хеши всех используемых модулей; они проверяются при загрузке и по умолчанию сверяются с публичной базой контрольных сумм sum.golang.org.

Новичков часто сбивает с толку суффикс мажорной версии. Справочник формулирует правило совместимости импорта: если старый и новый пакеты имеют одинаковый путь импорта, новый должен быть обратно совместим со старым. Поэтому для мажорной версии 2 и выше требуется суффикс в пути модуля: example.com/lib/v2. У версий v0 и v1 суффикса нет; v0 не обещает совместимости. Теги v2 и выше без файла go.mod отображаются с +incompatible.

Почему это важно

pip и npm предпочитают самую новую разрешённую версию и требуют файла блокировки или фиксации версий для воспроизводимости. Go выбирает минимальную версию, удовлетворяющую всем требованиям, и при каждой команде заново вычисляет тот же список. Поскольку lib и lib/v2 — разные пути импорта, обе версии могут присутствовать в одной сборке, а переход на новую мажорную версию становится заменой путей импорта, а не конфликтом разрешения зависимостей.

Как применять

• После изменения импортов выполняйте go mod tidy: команда добавляет недостающие требования, удаляет неиспользуемые и обновляет go.sum; сохраняйте оба файла в коммите.
• Обновляйте отдельную зависимость через go get example.com/lib@v1.4.0; для новой мажорной версии импортируйте путь с суффиксом.
• При выпуске v2 собственного модуля до создания тега измените строку module, чтобы она оканчивалась на /v2; статья блога о модулях v2 рекомендует подкаталог мажорной версии (v2/go.mod), а не отдельные ветки.
• Для локальной разработки используйте replace только в главном модуле; справочник указывает, что в файлах go.mod других модулей эта директива игнорируется.
• Предпочитайте retract удалению неудачного тега: тег остаётся в базе контрольных сумм.

Подводные камни

Если присвоить тег v2.0.0 модулю без суффикса в пути, команда go отклонит версию. С Go 1.21 директива go задаёт строгое требование: инструментарий с версией ниже указанной переключается на более новый или отказывается собирать, а не просто предупреждает. go.sum — не файл блокировки версий: он проверяет то, что выбрал minimal version selection.