Первый запуск Go-сервиса

Эта инструкция проводит от checkout-а до работающего HTTP API и первого компонентного теста. Новые сервисы создают из backend-service-skeleton-go. Для существующего сервиса используйте его README: зависимости и фоновые роли могут отличаться от шаблона.

Команды Go, Artisan и инструментов проекта выполняются из корня сервиса через elc. Для тестов всегда передавайте --env=.env.testing, в том числе при запуске одного пакета.

1. Подготовить рабочее место

Понадобятся Docker с Compose, установленный ELC, workspace проекта и доступ к GitLab с репозиториями сервисов, библиотек и Go-образов. Общая установка описана в локальном развороте backend.

Что проверить	Источник настройки
Версия Go в контейнере	`go.mod` сервиса и Go-образ ELC
Версии генератора, Air, Delve и линтеров	`mise.toml` и `mise.lock`
Зависимости сервиса и нужные подключения	README, `config/` и `.env.example`
Правила работы агента	`AGENTS.md` и, если есть, `AGENTS.local.md`

Для создания сервиса скриптами шаблона на хосте нужны Bash, Git, tar, Perl и ripgrep (rg), а также обычные Unix-утилиты. Для начального коммита должны быть настроены Git user.name и user.email.

2. Получить код сервиса

Существующий сервис

Откройте checkout нужного Go-сервиса и перейдите к подключению ELC и подготовке окружения. Инициализатор шаблона предназначен для создания нового сервиса; в рабочем сервисе сохраняйте его настройки и локальные env-файлы.

Новый сервис без Laravel-исходника

Подготовьте локальный checkout Go-шаблона. Экспортируйте его закоммиченную версию в новый, ещё не существующий каталог. Замените пути и пример catalog / example на параметры своего сервиса:

go_template=/path/to/backend-service-skeleton-go
go_service=/path/to/catalog-example-go

mkdir "$go_service"
git -C "$go_template" archive HEAD | tar -x -C "$go_service"
cd "$go_service"
git init

./scripts/init-service.sh \
  --domain catalog \
  --service example \
  --display-name "Ensi Catalog Example Go" \
  --app-url http://catalog-example-go.ensi.127.0.0.1.nip.io \
  --dry-run

git archive копирует отслеживаемые файлы выбранного коммита без .git и неотслеживаемых файлов локального checkout-а. Родительский каталог назначения должен существовать. Скрипт init-service.sh задаёт имя приложения, БД и consumer group, конфигурацию будущего клиента и пример Kafka-топика. Без --openapi-source сохраняется учебный HTTP-контракт шаблона.

Примените те же параметры без --dry-run, проверьте результат и создайте начальный коммит:

./scripts/init-service.sh \
  --domain catalog \
  --service example \
  --display-name "Ensi Catalog Example Go" \
  --app-url http://catalog-example-go.ensi.127.0.0.1.nip.io

git status --short
git add .
git commit -m "Initial commit"

Локальные .env и .env.testing, создаваемые initializer-ом, исключены из Git через .gitignore. Наличие Git-репозитория требуется скриптам установки инструментов, а начального коммита — проверке check:generated.

Новый сервис с контрактом Laravel

В шаблоне есть отдельный скрипт, который создаёт сервис в пустом каталоге, копирует весь OpenAPI из Laravel и делает Initial commit:

/path/to/backend-service-skeleton-go/scripts/create-service.sh \
  --template-source /path/to/backend-service-skeleton-go \
  --destination /path/to/new-service-go \
  --laravel-source /path/to/laravel-service \
  --domain catalog \
  --service example

Скрипт создаёт каркас и переносит контракт. Источники требований, этапы, артефакты и порядок продолжения описаны в руководстве по портированию, которое связано с рабочими инструкциями шаблона. После замены OpenAPI учебный маршрут /api/v1/examples/{id} может отсутствовать; для проверки API выбирайте реализованную операцию перенесённого контракта.

3. Подключить сервис к ELC

Проверьте выбранный workspace и список компонентов:

elc workspace list
elc workspace show
elc list

Для нового сервиса добавьте компонент в конфигурацию workspace: путь checkout-а, Go-образ, настройки запуска, адрес HTTP и необходимые зависимости. Ориентируйтесь на соседний Go-сервис этого же workspace. Создание каталога и параметр --app-url initializer-а сами по себе не регистрируют компонент и DNS-маршрут в ELC.

Далее запускайте команды из каталога зарегистрированного сервиса: ELC определяет компонент по текущему пути. Если он не находит сервис, сначала проверьте workspace и путь компонента. Версию Go в выбранном образе можно проверить командой:

elc go version

Она должна удовлетворять go.mod сервиса. Адреса PostgreSQL, Redis и других зависимостей должны быть доступны из контейнера приложения.

4. Подготовить локальные env-файлы

Initializer создаёт отсутствующие .env и .env.testing из .env.example. Для свежего checkout-а существующего сервиса создайте только недостающие файлы:

[ -f .env ] || cp .env.example .env
[ -f .env.testing ] || cp .env.example .env.testing

Отредактируйте локальные значения до запуска приложения и тестов:

Настройка	`.env`	`.env.testing`
`APP_ENV`	`local`	`testing`
`APP_URL`, `APP_HOST`, `APP_PORT`	Адрес и порт, согласованные с ELC	Значения для тестового запуска
`APP_KEY`	Ключ локального приложения	Отдельный ключ тестового окружения
`DB_CONNECTION`, `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD`	Локальное подключение PostgreSQL, если используется	Тестовое подключение PostgreSQL
`DB_DATABASE`	БД локального приложения	Отдельное имя, например с суффиксом `_testing`
URL внешних сервисов и настройки транспортов	По интеграциям сервиса	Подмены и настройки, необходимые тестам

Для знакомства с учебным HTTP-примером нового сервиса можно выбрать в обоих локальных env-файлах:

CACHE_DRIVER=memory
QUEUE_CONNECTION=sync
QUEUE_WORKER_ENABLED=false
KAFKA_CONSUMER_ENABLED=false
SCHEDULE_ENABLED=false
PROMETHEUS_ENABLED=false
LOG_ELASTICSEARCH_HOSTS=
HTTP_CLIENT_LOG=false

Это режим первого HTTP-запуска без фоновых ролей. В существующем сервисе и при реализации бизнес-сценариев настройте используемые им интеграции по README и конфигурации. Флаг отключения consumer не отключает публикацию Kafka из action; sync выполняет отправленную job сразу в вызывающем процессе.

5. Установить инструменты и зависимости

Из корня сервиса выполните:

elc mise trust
elc mise run tools:install
elc go mod download

tools:install устанавливает закреплённые инструменты и Node-зависимости из lock-файла, необходимые в том числе для OpenAPI lint. При ошибке загрузки приватного Go-модуля проверьте доступ к GitLab и конфигурацию получения приватных модулей в Go-образе ELC.

Для новых env-файлов с пустым APP_KEY сгенерируйте ключи:

elc ./artisan key:generate
elc ./artisan key:generate --env=.env.testing

В уже настроенном окружении сохраняйте действующий ключ приложения. Подробнее об инструментах, клиентах и workspace Go — в работе с пакетами.

6. Подготовить БД, если она используется

Создайте локальную БД и настройте доступ согласно workspace сервиса. После проверки DB_* примените миграции:

elc ./artisan migrate

Миграции находятся в database/migrations и регистрируются в bootstrap/migrations.go. Полная схема и локальные справочные данные зависят от сервиса; способ наполнения указан в его README. Подробнее — работа с БД.

Компонентные тесты, использующие RunComponentTests, создают временную PostgreSQL-БД на пакет и применяют миграции автоматически. Тестовому пользователю нужны доступ к служебной БД postgres и права создания и удаления временных БД. Ручной migrate в .env.testing не заменяет этот механизм.

7. Запустить приложение и проверить HTTP

Обычный режим разработки с Air:

elc start

Air пересобирает и перезапускает приложение при изменении кода. Для запуска без Air остановите этот режим и запустите приложение вручную:

elc stop
elc go run .

Проверяйте адрес из конфигурации ELC. Например, если для учебного сервиса настроен указанный выше hostname:

service_url=http://catalog-example-go.ensi.127.0.0.1.nip.io
curl --fail --silent --show-error "$service_url/health"
curl --fail --silent --show-error "$service_url/docs/oas/spec/index.yaml"
curl --fail --silent --show-error "$service_url/api/v1/examples/1"

Маршрут шаблона	Ожидаемый результат
`/health`	Успешный HTTP-ответ; доступность процесса не доказывает работоспособность всех интеграций
`/docs/oas`	Страница OpenAPI в браузере
`/docs/oas/spec/index.yaml`	Исходная спецификация API
`/api/v1/examples/1`	HTTP 200 и `{"data":{"id":1,"name":"Example"}}`
`/api/v1/examples/2`	HTTP 404 для отсутствующего примера

Учебный endpoint не обращается к БД. Для существующего сервиса или заменённого контракта используйте его операции. Логи и отладка описаны в логировании и настройке GoLand.

8. Запустить первый компонентный тест

В исходном шаблоне уже есть пакет app/modules/examples/tests/examples. Его тест GetTestSuite.TestStatus_200 вызывает API через внутренний HTTP-клиент и проверяет статус и JSON:

func (s *GetTestSuite) TestStatus_200() {
    resp, err := s.Http(s.T()).Get("/api/v1/examples/1")
    s.Require().NoError(err)
    resp.AssertStatus(200)
    body, err := resp.Content()
    s.Require().NoError(err)
    s.JSONEq(`{"data":{"id":1,"name":"Example"}}`, body)
}

Тест использует apptests.TestCase и проверку запроса/ответа по OpenAPI. В том же пакете есть проверки 404. Для этих сценариев не нужны TestMain с RunComponentTests, компонентная БД или отдельно запущенный HTTP-сервер.

elc go test ./app/modules/examples/tests/examples --env=.env.testing -count=1

Если учебный модуль заменён, выберите тестовый пакет реализованного ресурса. Для сценариев с PostgreSQL используется ComponentSuite и один TestMain с RunComponentTests на пакет — см. автотесты.

9. Подключить hooks и выполнить проверки перед MR

Установите hooks из репозитория:

elc set-hooks .git_hooks

В шаблоне pre-commit проверяет форматирование staged Go-файлов, OpenAPI и секреты; pre-push — env, модули, vet, тесты, генерацию и сборку. Hooks после checkout/merge синхронизируют инструменты и Node-зависимости при изменениях их конфигурации.

Перед MR запустите проверки из mise.toml своего сервиса. Базовый набор шаблона:

elc mise run check:fmt
elc mise run check:openapi
elc mise run check:env
elc mise run check:modules
elc mise run check:vet
elc mise run check:test
elc mise run check:generated
elc mise run check:secrets
elc mise run check:build

check:test передаёт .env.testing. check:generated повторяет генерацию и требует отсутствия новых изменений от генератора. После изменения OpenAPI сначала выполните elc mise exec -- ensi-gog server и просмотрите diff — см. ensi-gog. Для форматирования используется elc mise run format, для изменений конкурентного кода есть дополнительная проверка elc mise run check:race.

Дальнейшее чтение

Задача	Статьи
Разобраться в слоях и зависимостях	Структура сервиса, стиль кода, пакеты
Реализовать HTTP-операцию	Генератор, ответы и ошибки, БД
Реализовать SQL-поиск или изменение данных	Поиск, create/PATCH/delete
Подключить внешнее API или файлы	HTTP-клиенты, файловые операции
Проверить поведение	Компонентные тесты и фабрики
Подключить фоновые процессы	Kafka, очереди
Настроить диагностику	Логи, метрики, GoLand

1. Подготовить рабочее место​

2. Получить код сервиса​

Существующий сервис​

Новый сервис без Laravel-исходника​

Новый сервис с контрактом Laravel​

3. Подключить сервис к ELC​

4. Подготовить локальные env-файлы​

5. Установить инструменты и зависимости​

6. Подготовить БД, если она используется​

7. Запустить приложение и проверить HTTP​

8. Запустить первый компонентный тест​

9. Подключить hooks и выполнить проверки перед MR​

Дальнейшее чтение​