Работа с пакетами

В Go-сервисах Ensi зависимости проекта описываются файлами go.mod и go.sum в корне репозитория. Это аналог composer.json / composer.lock в PHP-мире, но с важными отличиями в модели версий и в том, как принято подключать локальные правки чужих модулей.

Команды toolchain (go get, go mod tidy, go build, go test и другие) в сервисах Ensi обычно запускают через elc, чтобы использовались те же Go и окружение, что и в контейнере проекта. Ниже примеры приведены в «чистом» виде; в рабочем репозитории пишите, например, elc go get ... и elc go mod tidy.

go.mod и go.sum

В отличие от Composer, в Go нельзя указать диапазон вроде «пакет версии ≥ 1.0». В go.mod для каждой зависимости фиксируется точная версия (тег релиза или псевдоверсия от коммита). В том же файле перечисляются и прямые зависимости (те, что вы сами импортируете), и непрямые (indirect) — то, что тянут ваши прямые пакеты. go.sum дополняет картину контрольными суммами модулей: по ним toolchain проверяет, что скачанное содержимое совпадает с ожидаемым.

Имя текущего модуля сервиса в go.mod часто выглядит просто:

module goravel

Строка goravel — это префикс импортов внутри приложения (goravel/app/..., goravel/tests и т.д.). Для кода самого сервиса конкретное имя модуля — в первую очередь соглашение шаблона; менять его без нужды не стоит.

У публикуемых пакетов (HTTP-клиенты к сервисам, общие библиотеки вроде goravel-ensi-http-client) путь модуля должен совпадать с адресом репозитория, откуда go get сможет скачать код:

module gitlab.com/greensight/ensi/catalog/clients/pim-client-go

Без такого пути другие сервисы не смогут нормально подтянуть пакет из GitLab.

Как добавить или обновить зависимость

Новый пакет подключают командой go get с путём модуля и желаемой версией или @latest:

go get gitlab.com/greensight/ensi/packages/goravel-ensi-http-client@latest

Если у репозитория ещё нет обычных semver-тегов (или вы тянете «голову» ветки), Go вычислит псевдоверсию вида v0.0.0-20260526163538-3dc84a4a5aaa. В ней зашиты дата коммита и короткий хэш: по ним видно, какой именно снимок кода попал в go.mod. После go get обычно смотрят diff go.mod / go.sum и коммитят оба файла вместе.

Отдельно полезна команда go mod tidy. Она проходит по импортам в коде проекта и приводит go.mod в соответствие: неиспользуемые модули удаляет, недостающие — добавляет (включая indirect, которые реально нужны графу). Имеет смысл запускать tidy после удаления импортов или перед сдачей изменений, чтобы в репозитории не копились «мёртвые» require.

Для клиентов Ensi в сервисах часто есть вспомогательный скрипт ./scripts/update-client.sh <branch>: он помогает выбрать *-client-go из текущего go.mod и обновить его до кончика указанной ветки. Генерация нового клиента из OpenAPI описана на странице ensi-gog; после генерации и публикации модуля потребители как раз обновляют зависимость через go get или этот скрипт.

Подключение Goravel-пакета клиента

Сгенерированный *-client-go оформлен как пакет Goravel. В сервисе-потребителе его можно поставить через artisan:

./artisan package:install gitlab.com/greensight/ensi/cms/clients/cms-client-go@latest

Локальная подмена пакетов через go.work

Иногда нужно править клиент или общую библиотеку рядом с сервисом и сразу видеть изменения в go build / go test, не публикуя каждый коммит в GitLab. Для этого в корне сервиса создают файл go.work примерно такого вида:

go 1.25.0

use (
    ./
    /home/you/work/ensi/packages/cms-client-go
    /home/you/work/ensi/packages/pim-client-go
)

В use перечисляют пути к модулям, которые должны подмениться локальными копиями. Текущий сервис тоже указывают (./): workspace описывает весь набор модулей, с которыми вы работаете вместе.

Файл go.work (и go.work.sum) не коммитят в git — в .gitignore сервисов они обычно уже исключены. Это чисто локальная настройка машины разработчика.

Важно понимать область действия workspace. Настройки go.work влияют на go build и go test (и связанные команды сборки): toolchain подставляет локальные модули вместо версий из go.mod. Команды вроде go get, go mod download и go mod tidy workspace игнорируют: они по-прежнему смотрят на go.mod и сеть/кэш модулей. Поэтому после правок в go.work не нужно «закрепить» подмену через tidy или get — достаточно следующей сборки или теста. Но при этом в GitLab уже должен существовать настоящий модуль с тем же путём: первый go get когда-то должен был что-то скачать и записать версию в go.mod. go.work подменяет содержимое при сборке, а не отменяет необходимость объявить зависимость.

Когда локальная отладка закончена, изменения публикуют в репозиторий пакета, в сервисе делают go get ...@<новый коммит или тег> (или update-скрипт), проверяют сборку без опоры на случайно оставшийся go.work, и коммитят обновлённые go.mod / go.sum.

Сброс кэша модулей

Если toolchain упорно тянет старое содержимое, модульный кэш выглядит повреждённым или после смены VPN/прокси «ломаются» странные ошибки загрузки, можно очистить кэш модулей и сборочный кэш:

go clean -modcache -cache

После этого следующий go build / go test / go get заново скачает нужные модули. Команда затрагивает глобальный кэш пользователя на машине, не только один репозиторий — имейте это в виду, если параллельно собираются другие Go-проекты.