YAML Schema Reference¶

Полный справочник всех полей конфигурации Go Project Starter.

Источник правды

Авторитетный источник — структуры в internal/pkg/config/structs.go. Эта документация синхронизируется с кодом.

Базовая структура¶

main:                      # Основные настройки проекта
git:                       # Git репозиторий
tools:                     # Версии инструментов
rest:                      # REST транспорты
grpc:                      # gRPC сервисы
kafka:                     # Kafka producers/consumers
cli:                       # CLI транспорты
worker:                    # Фоновые воркеры
driver:                    # Драйверы интеграций
applications:              # Приложения (deployment units)
grafana:                   # Grafana datasources
jsonschema:                # JSON Schema для типизации
artifacts:                 # Типы артефактов сборки
packaging:                 # Конфигурация системных пакетов
docker:                    # Docker настройки
deploy:                    # Настройки деплоя
scheduler:                 # Планировщик задач
post_generate:             # Шаги после генерации

Секция `main`¶

Основные настройки проекта.

main:
  name: string              # [required] Имя проекта (используется в путях, Docker образах)
  logger: zerolog           # [optional] Тип логгера: zerolog|logrus
  registry_type: github     # [required] Тип registry: github|digitalocean|aws|selfhosted
  author: string            # [optional] Автор для заголовков файлов
  use_active_record: bool   # [optional] Включить PostgreSQL ActiveRecord
  dev_stand: bool           # [optional] Генерировать docker-compose-dev.yaml с OnlineConf
  skip_service_init: bool   # [optional] Пропустить генерацию Service layer
  ci: [github, gitlab]      # [optional] CI провайдеры: github, gitlab, [] — без CI (default: оба)

Секция `git`¶

Настройки Git репозитория.

git:
  repo: string              # [required] URL Git репозитория
  module_path: string       # [required] Go module path
  private_repos: string     # [optional] Приватные модули для GOPRIVATE (через запятую)

Секция `tools`¶

Версии инструментов, используемых при генерации и сборке.

tools:
  golang_version: "1.26"           # [optional] Версия Go (default: 1.26)
  ogen_version: "v0.78.0"          # [optional] Версия ogen (default: v0.78.0)
  argen_version: "v1.0.0"          # [optional] Версия argen/ActiveRecord (default: v1.0.0)
  golangci_version: "1.55.2"       # [optional] Версия golangci-lint (default: 1.55.2)
  protobuf_version: "1.7.0"        # [optional] Версия protoc-gen-go (default: 1.7.0)
  go_jsonschema_version: "v0.16.0" # [optional] Версия go-jsonschema (default: v0.16.0)
  runtime_version: string          # [auto] Версия go-project-starter-runtime
  goat_version: string             # [auto] Версия GOAT test framework
  goat_services_version: string    # [auto] Версия GOAT services

Секция `rest`¶

REST API транспорты.

rest:
  - name: string                # [required] Уникальное имя транспорта
    path:                       # [required для ogen/ogen_client] Пути к OpenAPI спецификациям
      - string
    generator_type: string      # [required] Тип генератора: ogen|template|ogen_client
    generator_template: string  # [required для template] Имя шаблона (например: sys)
    generator_params:           # [optional] Дополнительные параметры генератора
      auth_handler: string      # [ogen] Кастомный auth handler
    port: int                   # [required кроме sys] HTTP порт
    version: string             # [required] Версия API (v1, v2, etc)
    api_prefix: string          # [optional] URL префикс для API
    health_check_path: string   # [optional] Путь для health check
    public_service: bool        # [optional] Публичный сервис (без авторизации)

    # Только для ogen_client:
    instantiation: string       # [optional] static (default) или dynamic
    auth_params:                # [optional] Параметры аутентификации
      transport: header         # Тип транспорта (только header)
      type: apikey              # Тип аутентификации: apikey или bearer

Типы генераторов REST¶

Тип	Описание
`ogen`	OpenAPI 3.0 сервер через ogen
`template`	Шаблонная генерация (sys для metrics/health)
`ogen_client`	REST клиент для вызова внешних API

Instantiation modes (ogen_client)¶

Режим	Описание
`static`	Один экземпляр клиента на всё приложение (default)
`dynamic`	Новый экземпляр для каждого запроса

Секция `grpc`¶

gRPC сервисы.

grpc:
  - name: string                # [required] Уникальное имя сервиса
    path: string                # [required] Путь к .proto файлу
    short: string               # [optional] Короткое имя для пакетов
    port: int                   # [required] gRPC порт
    generator_type: string      # [required] Тип: buf_client
    buf_local_plugins: bool     # [optional] Использовать локальные buf плагины

    # Только для buf_client:
    instantiation: string       # [optional] static (default) или dynamic

Instantiation modes (buf_client)¶

Режим	Описание
`static`	Один экземпляр клиента на всё приложение (default)
`dynamic`	Клиент создаётся в рантайме через `NewDynamicClient(ctx, address)`

Секция `kafka`¶

Kafka producers и consumers.

kafka:
  - name: string                # [required] Уникальное имя
    type: string                # [required] Тип: producer|consumer
    driver: string              # [optional] Драйвер: segmentio (default)|custom
    client: string              # [required] Имя клиента для OnlineConf путей
    group: string               # [required для consumer] Consumer group
    events:                     # [required] Список событий
      - name: string            # [required] Имя события (используется для методов)
        schema: string          # [optional] Ссылка на JSON schema: schemaset.schemaid

    # Только для custom driver:
    driver_import: string       # [required] Import path драйвера
    driver_package: string      # [required] Имя пакета
    driver_obj: string          # [required] Имя struct драйвера

Секция `cli`¶

CLI транспорты для интерактивных приложений.

cli:
  - name: string                # [required] Уникальное имя CLI
    path:                       # [optional] Путь к спецификации команд (commands.yaml)
      - string
    generator_type: template    # [required] Тип генератора
    generator_template: cli     # [required] Имя шаблона
    generator_params:           # [optional] Параметры генератора
      key: value

Спецификация команд (`commands.yaml`)¶

Файл, указанный в path, описывает CLI команды:

commands:
  - name: string                # [required] Имя команды
    description: string         # [required] Описание команды

    # Leaf-команда (без subcommands):
    flags:                      # [optional] Флаги команды
      - name: string            # [required] Имя флага (--name)
        type: string            # [required] Тип: string|int|bool|float64|duration
        required: bool          # [optional] Обязательный флаг
        default: string         # [optional] Значение по умолчанию
        description: string     # [optional] Описание

    # Команда с подкомандами (исключает flags):
    subcommands:                # [optional] Подкоманды
      - name: string            # [required] Имя подкоманды
        description: string     # [required] Описание подкоманды
        flags:                  # [optional] Флаги подкоманды
          - name: string
            type: string
            required: bool
            default: string
            description: string

Типы флагов¶

Тип	Go тип	Пример default
`string`	`string`	`"hello"`
`int`	`int`	`"100"`
`bool`	`bool`	`"true"`
`float64`	`float64`	`"3.14"`
`duration`	`time.Duration`	`"5s"`

Правила валидации¶

Команда может иметь subcommands или flags, но не оба
Имена команд должны быть уникальны
Имена подкоманд уникальны в рамках родительской команды
type флага должен быть одним из допустимых значений

Секция `worker`¶

Фоновые воркеры.

worker:
  - name: string                # [required] Уникальное имя воркера
    path:                       # [optional] Пути к спецификациям
      - string
    version: string             # [optional] Версия
    generator_type: template    # [required] Тип генератора
    generator_template: string  # [required] Шаблон: telegram|daemon
    generator_params:           # [optional] Параметры генератора
      key: value

Доступные шаблоны воркеров¶

Шаблон	Описание
`telegram`	Telegram бот
`daemon`	Фоновый daemon процесс

Секция `driver`¶

Кастомные драйверы для интеграций.

driver:
  - name: string                # [required] Уникальное имя драйвера
    import: string              # [required] Import path
    package: string             # [required] Имя пакета
    obj_name: string            # [required] Имя struct объекта
    service_injection: string   # [optional] Код для инъекции в Service

Секция `applications`¶

Приложения — атомарные единицы деплоя (контейнеры).

applications:
  - name: string                # [required] Имя приложения (= имя контейнера)

    transport:
      - name: string            # Имя REST транспорта
        config:                 # [optional] Переопределение настроек
          instantiation: string # static|dynamic (для ogen_client)

    kafka:                      # [optional] Kafka producers/consumers
      - string
    worker:                     # [optional] Воркеры
      - string
    cli: string                 # [optional] CLI транспорт (исключает transport/worker)

    driver:                     # [optional] Драйверы с параметрами
      - name: string            # Имя драйвера
        params:                 # [optional] Параметры инициализации
          - string

    deploy:                     # [optional] Настройки деплоя
      volumes:                  # Docker volumes
        - path: string          # Путь к файлу/директории
          mount: string         # Точка монтирования в контейнере

    use_active_record: bool     # [optional] Переопределить глобальную настройку
    use_envs: bool              # [optional] Использовать environment variables
    depends_on_docker_images:   # [optional] Docker образы для pre-pull
      - string

    # GOAT тесты:
    goat_tests: bool            # [optional] Включить GOAT тесты (простой флаг)
    goat_tests_config:          # [optional] Расширенная конфигурация GOAT
      enabled: bool
      binary_path: string       # Путь к тестовому бинарнику

    # Grafana:
    grafana:
      datasources:              # Ссылки на datasources по имени
        - string

    # Артефакты (переопределяют глобальные):
    artifacts:
      - docker
      - deb

CLI приложения

Если указан cli, нельзя использовать transport и worker.

Секция `grafana`¶

Глобальные настройки Grafana datasources.

grafana:
  datasources:
    - name: string              # [required] Уникальное имя
      type: string              # [required] Тип: prometheus|loki
      access: string            # [optional] Режим: proxy (default)|direct
      url: string               # [required] URL datasource
      isDefault: bool           # [optional] Default datasource
      editable: bool            # [optional] Редактируемый в UI

Секция `jsonschema`¶

JSON Schema для генерации Go структур с валидацией.

jsonschema:
  - name: string                # [required] Уникальное имя группы схем
    package: string             # [optional] Имя Go пакета (default: name)

    # Новый формат (рекомендуется):
    schemas:
      - id: string              # [required] Уникальный ID для ссылок из kafka
        path: string            # [required] Путь к JSON schema файлу
        type: string            # [optional] Имя Go типа (auto-generated если пусто)

    # Legacy формат (deprecated):
    path:
      - string

Секция `artifacts`¶

Типы артефактов для сборки.

artifacts:
  - docker                      # Docker образы
  - deb                         # Debian пакеты
  - rpm                         # RPM пакеты
  - apk                         # Alpine пакеты

Секция `packaging`¶

Конфигурация системных пакетов (deb/rpm/apk).

packaging:
  maintainer: string            # [required] Email maintainer'а
  description: string           # [required] Описание пакета
  homepage: string              # [optional] URL проекта
  license: string               # [optional] Лицензия
  vendor: string                # [optional] Компания/организация
  install_dir: string           # [optional] Путь установки бинарника
  config_dir: string            # [optional] Путь установки конфигов
  upload:                       # [optional] Загрузка пакетов
    type: string                # Тип хранилища: minio|aws|rsync

Credentials для upload

Credentials (endpoint, bucket, keys) передаются через CI/CD переменные, не через конфиг.

Секция `docker`¶

Docker настройки.

docker:
  image_prefix: string          # [optional] Префикс для Docker образов

Секция `deploy`¶

Настройки деплоя.

deploy:
  log_collector:                # [optional] Сборщик логов
    type: string                # Тип сборщика
    parameters:                 # Параметры
      key: value

Секция `scheduler`¶

Планировщик задач.

scheduler:
  enabled: bool                 # [optional] Включить scheduler

Секция `post_generate`¶

Шаги, выполняемые после генерации.

post_generate:
  - git_install                 # Инициализация git репозитория
  - tools_install               # Установка инструментов
  - clean_imports               # Организация импортов (goimports)
  - executable_scripts          # chmod +x для скриптов
  - call_generate               # Вызов make generate
  - go_mod_tidy                 # go mod tidy

Правила валидации¶

Обязательные проверки¶

main.name — обязательно
main.registry_type — обязательно, допустимые значения: github, digitalocean, aws, selfhosted
git.repo и git.module_path — обязательны
REST/gRPC транспорты должны быть назначены в applications
Драйверы, на которые есть ссылки, должны существовать в driver
Имена транспортов, воркеров, драйверов не должны дублироваться
Порты обязательны для REST (кроме шаблона sys)

Специфичные проверки¶

Условие	Требование
`use_active_record: true`	Требуется `tools.argen_version`
`artifacts` содержит `deb/rpm/apk`	Требуется секция `packaging`
`kafka.type: consumer`	Требуется `group`
`kafka.driver: custom`	Требуются `driver_import`, `driver_package`, `driver_obj`
`rest.generator_type: template`	Требуется `generator_template`
`rest.instantiation`	Только для `ogen_client`

Полный пример¶

main:
  name: myservice
  logger: zerolog              # или logrus
  registry_type: github
  use_active_record: true
  dev_stand: true

git:
  repo: https://github.com/myorg/myservice
  module_path: github.com/myorg/myservice

tools:
  golang_version: "1.22"
  ogen_version: "v1.0.0"

rest:
  - name: api
    path: [./api/openapi.yaml]
    generator_type: ogen
    port: 8080
    version: v1
    health_check_path: /health

  - name: sys
    generator_type: template
    generator_template: sys
    port: 9090
    version: v1

  - name: external_api
    generator_type: ogen_client
    path: [./api/external.yaml]
    instantiation: dynamic
    auth_params:
      transport: header
      type: apikey

kafka:
  - name: events_producer
    type: producer
    client: main_kafka
    events:
      - name: user_created
        schema: models.user

jsonschema:
  - name: models
    schemas:
      - id: user
        path: ./schemas/user.json

applications:
  - name: api
    transport:
      - name: api
      - name: sys
      - name: external_api
        config:
          instantiation: dynamic
    kafka: [events_producer]
    goat_tests: true

  - name: workers
    worker: [telegram_bot]

worker:
  - name: telegram_bot
    generator_type: template
    generator_template: telegram

artifacts:
  - docker

YAML Schema Reference¶

Базовая структура¶

Секция main¶

Секция git¶

Секция tools¶

Секция rest¶

Типы генераторов REST¶

Instantiation modes (ogen_client)¶

Секция grpc¶

Instantiation modes (buf_client)¶

Секция kafka¶

Секция cli¶

Спецификация команд (commands.yaml)¶

Типы флагов¶

Правила валидации¶

Секция worker¶

Доступные шаблоны воркеров¶

Секция driver¶

Секция applications¶

Секция grafana¶

Секция jsonschema¶

Секция artifacts¶

Секция packaging¶

Секция docker¶

Секция deploy¶

Секция scheduler¶

Секция post_generate¶

Правила валидации¶

Обязательные проверки¶

Специфичные проверки¶

Полный пример¶

Секция `main`¶

Секция `git`¶

Секция `tools`¶

Секция `rest`¶

Секция `grpc`¶

Секция `kafka`¶

Секция `cli`¶

Спецификация команд (`commands.yaml`)¶

Секция `worker`¶

Секция `driver`¶

Секция `applications`¶

Секция `grafana`¶

Секция `jsonschema`¶

Секция `artifacts`¶

Секция `packaging`¶

Секция `docker`¶

Секция `deploy`¶

Секция `scheduler`¶

Секция `post_generate`¶