Troubleshooting¶

FAQ и решение типичных проблем.

Генерация¶

Ошибка "main.name is required"¶

Причина: Отсутствует обязательное поле main.name в конфигурации.

Решение:

main:
  name: my-service  # Добавьте это поле

Ошибка "duplicate rest name"¶

Причина: Два REST транспорта с одинаковым именем и версией.

Решение: Используйте уникальные комбинации name + version:

rest:
  - name: api
    version: v1
  - name: api
    version: v2  # OK - разные версии

Файлы не генерируются¶

Причина: Неправильный путь к target директории.

Решение:

# Используйте абсолютный путь
go-project-starter --config=config.yaml --target=/home/user/my-project

# Или убедитесь, что директория существует
mkdir -p ./my-project
go-project-starter --config=config.yaml --target=./my-project

Ogen: ошибки компиляции¶

"undefined: oas.ErrorDefault" или "undefined: oas.ErrorDefaultStatusCode"¶

Причина: В OpenAPI-спецификации отсутствует схема ErrorDefault или она имеет другое имя/структуру. Генератор ожидает, что ogen создаст типы ErrorDefault и ErrorDefaultStatusCode с конкретными полями.

Решение: Добавьте в components.schemas вашей OpenAPI-спецификации:

components:
  schemas:
    ErrorDefault:
      required:
        - code
        - error
      properties:
        code:
          type: integer
          format: int32
        error:
          type: string
      type: object

И используйте $ref: '#/components/schemas/ErrorDefault' в default ответах endpoints.

Что генерирует ogen из этой схемы:

ErrorDefault — struct { Code int32; Error string } с методом Encode(e *jx.Encoder)
ErrorDefaultStatusCode — struct { StatusCode int; Response ErrorDefault }

Оба типа используются в сгенерированных файлах error_response.go, handler/handler.go и router.go.

"errResp.Encode undefined" или "errResp.Code undefined"¶

Причина: Схема ErrorDefault определена, но с другими полями. Генератор ожидает поля code (int32) и error (string).

Решение: Проверьте, что структура схемы точно соответствует примеру выше. Поля code и error — обязательны и должны быть именно такого типа.

Сборка проекта¶

"cannot find package"¶

Причина: Зависимости не загружены.

Решение:

go mod download
go mod tidy

"undefined: ogen"¶

Причина: Ogen код не сгенерирован.

Решение:

make generate
# или
make ogen

Приватные модули не загружаются¶

Причина: Не настроен GOPRIVATE.

Решение: Добавьте в конфигурацию:

git:
  private_repos:
    - github.com/myorg/*

Docker¶

"Cannot connect to Docker daemon"¶

Причина: Docker не запущен.

Решение:

# Linux
sudo systemctl start docker

# macOS
open -a Docker

"port is already allocated"¶

Причина: Порт занят другим процессом.

Решение:

# Найти процесс
lsof -i :8080

# Или изменить порт в docker-compose
# Или остановить conflicting контейнер
docker compose down

Dev Stand¶

OnlineConf updater не создаёт TREE.cdb¶

Причина: Проблемы с MySQL или Admin UI.

Решение:

# Проверить логи
docker compose -f docker-compose-dev.yaml logs onlineconf-updater
docker compose -f docker-compose-dev.yaml logs onlineconf-database

# Пересоздать окружение
make dev-drop
make dev-up

Изменения в init-config.sql не применяются¶

Причина: MySQL выполняет init-скрипты только при первом запуске.

Решение:

make dev-drop  # Удаляет volumes
make dev-up

Submodule не инициализирован¶

Причина: OnlineConf submodule не загружен.

Решение:

git submodule update --init --recursive

Тесты¶

"API did not become ready"¶

Причина: Приложение не запустилось.

Решение:

Проверьте бинарник: ls -la /tmp/api
Проверьте Docker: docker ps
Посмотрите логи: tail -f /tmp/yourproject-test-*.log

"Database connection refused"¶

Причина: Testcontainers не запустили PostgreSQL.

Решение:

Проверьте Docker daemon
Проверьте права на Docker socket
Увеличьте таймаут запуска

"TestEnvInitializer not implemented"¶

Причина: Не создан файл tests/init.go.

Решение: Создайте файл с реализацией интерфейса (см. GOAT).

CI/CD¶

"permission denied" в GitHub Actions¶

Причина: Неправильные секреты или права.

Решение:

Проверьте секреты в Settings → Secrets
Убедитесь, что SSH ключ правильный
Проверьте права на registry

Docker push fails¶

Причина: Неверные credentials для registry.

Решение:

# GitHub Container Registry
gh secret set GHCR_USER --body "username"
gh secret set GHCR_TOKEN --body "ghp_..."

# Проверьте локально
docker login ghcr.io -u username -p token

Общие советы¶

Предпросмотр изменений¶

Используйте --dry-run перед генерацией:

go-project-starter --dry-run --config=config.yaml --target=.

Логирование¶

Включите debug логирование:

export LOG_LEVEL=debug
go-project-starter --config=config.yaml

Версии инструментов¶

Убедитесь, что версии совместимы:

go version          # Должен быть 1.24+
docker --version    # Должен быть 20.10+

Очистка и перегенерация¶

При серьёзных проблемах:

# Сохраните ваш код
cp -r internal/app/*/transport/rest/*/handler.go /tmp/backup/

# Удалите сгенерированные файлы
rm -rf cmd/ internal/ pkg/ Makefile Dockerfile docker-compose.yaml

# Перегенерируйте
go-project-starter --config=config.yaml

# Восстановите ваш код
cp /tmp/backup/*.go internal/app/*/transport/rest/*/

Получение помощи¶

Если проблема не решена:

Проверьте GitHub Issues
Создайте новый issue с:
Версия генератора (go-project-starter --version)
Конфигурация (без секретов)
Полный вывод ошибки
Шаги воспроизведения