Go: Настройка окружения
2026-02-26 18:32 Diff
https://ru.hexlet.io/courses/go-setup-environment/lessons/publishing/theory_unit

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

В этом уроке мы рассмотрим, как работает публикация модулей в Go.

Как работает загрузка через прокси-сервер

Команда go не загружает пакеты напрямую из хранилищ исходного кода, а опрашивает прокси-сервер.

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

Еще пользователя оберегает база данных контрольных сумм, которая хранит записи из файлов go.sum. Представьте, что вы загружаете модуль командой go. В этот момент команда считывает хэш загружаемого модуля и сверяет его с данными из базы контрольных сумм. Если они не совпадают, то установка завершается с ошибкой.

Как найти запрашиваемый пакет в прокси

Проследим установку пакета на примере популярной библиотеки lo. Возьмем базовый пример:

Создадим модуль со структурой:

И содержимым hxlt.go

Вызов команды go get github.com/samber/lo@latest проверит переменную окружения GOPROXY. Допустим, она содержит список прокси-серверов:

Тогда команда go выполнит следующие шаги:

  • Запросит последнюю версию github.com/samber/lo от сервера https://corp.example.com/
  • Запросит последнюю версию github.com/samber от сервера https://corp.example.com/
  • Запросит последнюю версию github.com от сервера https://corp.example.com/

Представим, что все запросы к https://corp.example.com/ выдали ошибку 404 или 410. Тогда команда перейдет к следующей записи:

  • Запросит последнюю версию github.com/samber/lo от сервера https://proxy.golang.org/
  • Запросит последнюю версию github.com/samber от сервера https://proxy.golang.org/
  • Запросит последнюю версию github.com от сервера https://proxy.golang.org/

Если в результате найдется один модуль с именем github.com/samber/lo и пакетом lo, то команда go обновит файлы go.mod и go.sum и скачает сам пакет.

Как найти последнюю версию пакета

Продолжим пример с запросом go get github.com/samber/lo@latest. Здесь можно использовать атрибут @latest, и тогда go определит последнюю версию запрашиваемого пакета.

Рассмотрим, как это работает. Допустим в системе контроля версий проекта есть несколько веток и тегов:

  • Ветка main
  • Ветка v2
  • Тег v1.0.0
  • Тег 1101-1663105068

В этом случае последней версией будет считаться тег v1.0.0, потому что Go отдает приоритет тегам перед ветками. Обратите внимание, что используются только те теги, которые начинаются с буквы v и следуют семантическому версионированию.

Если в проекте нет тегов, команда создает псевдо-версию, используя последний коммит.

Как публиковать модуль

Попробуем опубликовать собственный модуль. Этот процесс состоит из нескольких шагов.

Создаем go-модуль:

Добавляем код в модуль, созданный выше:

Запускаем go mod tidy, чтобы загрузить недостающие пакеты и удалить лишние:

Дальше нужно отформатировать код с помощью встроенного инструмента go fmt. Не забывайте запускать форматирование перед публикацией пакета — так вы убедитесь, что вывод команды не содержит ошибок.

После этого проверяем код линтером. Для Go написано множество линтеров, поэтому появились утилиты-аггрегаторы, запускающие несколько линтеров разом. Мы рекомендуем пользоваться golangci-lint.

Остался последний шаг — добавляем новый тег в репозиторий:

Модуль готов к скачиванию! Чтобы пользователи смогли найти его до загрузки, можно запустить команду go list — она добавит модуль в индекс go.pkg.

Как добавлять обратно несовместимые изменения

В работе над проектом разработчики могут переименовывать функции, изменять ее сигнатуры, удалять устаревший код. Подобные действия могут вносить ломающие изменения в API. Это значит, что пользователям придется вносить изменения в собственную кодовую базу.

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

Возьмем модуль из примера выше. Его структура выглядит так:

При этом файл go.mod выглядит так:

Чтобы создать версию 2.0.0 этого модуля, нужно обновить go.mod, чтобы он содержал в названии новую мажорную версию пакета. Сохраним текущий код в ветке v1:

Обновим go.mod файл, добавив ему в название v2:

Если бы в проекте было несколько пакетов, то для папки с v2 пришлось бы обновить все импорты, чтобы они включали суффикс v2. Добавим тег и опубликуем:

Выводы

  • Чтобы опубликовать Go-модуль, нужно внести его в хранилище исходного кода: то есть добавить сам код, файлы go.mod и go.sum в систему контроля версий
  • Имя модуля при этом должно содержать путь до модуля в этом хранилище
  • Модули по умолчанию загружаются не из хранилищ кода, а из центрального репозитория пакетов
  • Чтобы точнее указать требования к версии пакета, можно использовать version query. Отсутствующий version query имеет дефолтное значение latest
  • Перед публикацией не забывайте форматировать код и проверять его линтером
  • В работе над публичными проектами на Go добавляйте новые версии, а не изменяйте уже существующие