Конфигурация Go-приложения: флаги, env, файлы — рабочие приёмы

Проблема одного источника

Типичный Go-сервис начинается с двух-трёх флагов: порт, DSN базы, уровень логирования. Через полгода параметров уже тридцать, часть приходит из переменных окружения в Kubernetes, часть зашита в YAML-файле, а отладочный флаг --verbose конфликтует с LOG_LEVEL=info из .env. Приоритеты нигде не описаны, и каждый деплой — лотерея.

Ниже — три механизма загрузки конфигурации, их реальная цена и схема, которая позволяет комбинировать источники с предсказуемым приоритетом.

Флаги командной строки: стандартная библиотека

Пакет flag из стандартной библиотеки Go покрывает базовый сценарий: разбор аргументов при запуске. Он не требует зависимостей, знаком каждому Go-разработчику и отлично ложится в --help.

// main.go — Go 1.22+
package main

import (
	"flag"
	"fmt"
)

func main() {
	port := flag.Int("port", 8080, "порт HTTP-сервера")
	dsn := flag.String("dsn", "", "строка подключения к PostgreSQL")
	debug := flag.Bool("debug", false, "включить отладочный вывод")
	flag.Parse()

	fmt.Printf("port=%d dsn=%s debug=%t\n", *port, *dsn, *debug)
}

Запуск: go run main.go --port=9090 --dsn='postgres://...' --debug. Если передать неизвестный флаг, программа завершится с подсказкой — это поведение по умолчанию.

Где флаги неудобны

• Секреты в аргументах командной строки видны в ps aux любому пользователю системы. DSN с паролем в флаге — утечка.
• Тридцать флагов превращают строку запуска в нечитаемое месиво.
• В контейнерных оркестраторах (Kubernetes, Nomad) задавать переменные окружения проще, чем редактировать аргументы entrypoint.

Переменные окружения: явный контракт со средой

Переменные окружения — стандарт де-факто для контейнеров и 12-factor-приложений. В Go достаточно os.Getenv, но вручную парсить каждую переменную утомительно. Библиотека caarlos0/env (v11 на момент написания) привязывает переменные к полям структуры через теги.

// config.go — Go 1.22+, github.com/caarlos0/env/v11
package main

import (
	"fmt"
	"log"

	"github.com/caarlos0/env/v11"
)

type Config struct {
	Port     int    `env:"APP_PORT"     envDefault:"8080"`
	DSN      string `env:"APP_DSN,required"`
	LogLevel string `env:"APP_LOG_LEVEL" envDefault:"info"`
}

func main() {
	cfg := Config{}
	if err := env.Parse(&cfg); err != nil {
		log.Fatalf("не удалось прочитать конфигурацию: %v", err)
	}
	fmt.Printf("%+v\n", cfg)
}

Тег required гарантирует, что без APP_DSN приложение не стартует — ошибка обнаруживается сразу, а не при первом запросе к базе.

Подводные камни env

• Нет вложенности: если конфигурация содержит блок redis.addr, redis.password, redis.db, в переменных окружения это будет REDIS_ADDR, REDIS_PASSWORD, REDIS_DB — плоский список. При 40+ параметрах читаемость страдает.
• Типизация минимальна: переменная окружения всегда строка. Библиотека конвертирует за вас, но сложные типы (map, slice структур) требуют собственного парсера.
• Переопределение в рантайме невозможно без перезапуска процесса (если вы не перечитываете env по сигналу, что редкость).

Файлы конфигурации: YAML, TOML, JSON

Файл удобен, когда параметров много и они логически группируются. YAML и TOML читаемее JSON; JSON проще парсить без сторонних зависимостей, но комментарии не поддерживает.

# config.yaml
server:
  port: 8080
  read_timeout: 5s

database:
  dsn: "postgres://user:pass@localhost:5432/app?sslmode=disable"
  max_open_conns: 20

log:
  level: info

Для разбора YAML в Go используют пакет gopkg.in/yaml.v3:

// load.go — Go 1.22+, gopkg.in/yaml.v3
package config

import (
	"os"
	"time"

	"gopkg.in/yaml.v3"
)

type ServerConfig struct {
	Port        int           `yaml:"port"`
	ReadTimeout time.Duration `yaml:"read_timeout"`
}

type DatabaseConfig struct {
	DSN          string `yaml:"dsn"`
	MaxOpenConns int    `yaml:"max_open_conns"`
}

type LogConfig struct {
	Level string `yaml:"level"`
}

type Config struct {
	Server   ServerConfig   `yaml:"server"`
	Database DatabaseConfig `yaml:"database"`
	Log      LogConfig      `yaml:"log"`
}

func Load(path string) (Config, error) {
	var cfg Config
	data, err := os.ReadFile(path)
	if err != nil {
		return cfg, err
	}
	err = yaml.Unmarshal(data, &cfg)
	return cfg, err
}

Чем платите за файлы

• Файл нужно доставить в контейнер: ConfigMap, volume mount, init-контейнер — дополнительный шаг в пайплайне.
• Секреты в файле на диске — риск: доступ к файловой системе означает доступ к паролям. Либо шифруйте (SOPS, Vault), либо не кладите секреты в файл.
• Формат нужно валидировать: YAML молча проглатывает опечатку в ключе, поле остаётся нулевым, и ошибка проявится в рантайме.

Сравнение подходов

Комбинируем источники: цепочка приоритетов

На практике удобнее всего использовать все три источника с чётким приоритетом. Принцип прост: чем ближе к моменту запуска, тем выше приоритет.

1. Файл — базовые значения по умолчанию, общие для среды (dev, staging, prod).
2. Переменные окружения — переопределяют файл. Удобно для секретов и per-pod настроек.
3. Флаги командной строки — переопределяют всё остальное. Используются для отладки и одноразовых запусков.

Реализация без «магических» фреймворков — обычная функция:

// config.go — Go 1.22+, gopkg.in/yaml.v3, os, flag
package config

import (
	"flag"
	"os"
	"strconv"
)

// Load читает конфигурацию из файла, затем перезаписывает
// значениями из env и флагов.
func Load(path string) (Config, error) {
	// 1. Файл — базовый слой
	cfg, err := loadFromFile(path)
	if err != nil {
		return cfg, err
	}

	// 2. Env — средний слой
	if v := os.Getenv("APP_PORT"); v != "" {
		if p, err := strconv.Atoi(v); err == nil {
			cfg.Server.Port = p
		}
	}
	if v := os.Getenv("APP_DSN"); v != "" {
		cfg.Database.DSN = v
	}

	// 3. Флаги — верхний слой
	port := flag.Int("port", cfg.Server.Port, "порт HTTP-сервера")
	dsn := flag.String("dsn", cfg.Database.DSN, "строка подключения к БД")
	flag.Parse()

	cfg.Server.Port = *port
	cfg.Database.DSN = *dsn

	return cfg, nil
}

Ключевой момент: значения по умолчанию для flag берутся не из констант, а из того, что уже загружено из файла и env. Это и создаёт цепочку приоритетов без лишних библиотек.

Конфигурация — не данные приложения. Если вы не можете объяснить за 30 секунд, откуда берётся каждое значение и что его переопределяет, — у вас не конфигурация, а лотерея.

Валидация: ловите ошибки на старте

Загрузить конфигурацию — полдела. Вторая половина — убедиться, что значения осмысленны. Порт 0 или пустой DSN не должны проходить дальше функции Load.

// validate.go
package config

import "fmt"

func (c Config) Validate() error {
	if c.Server.Port < 1 || c.Server.Port > 65535 {
		return fmt.Errorf("некорректный порт: %d", c.Server.Port)
	}
	if c.Database.DSN == "" {
		return fmt.Errorf("DSN базы данных не задан")
	}
	if c.Server.ReadTimeout <= 0 {
		return fmt.Errorf("read_timeout должен быть положительным")
	}
	return nil
}

Вызывайте Validate() сразу после Load(). Приложение, которое падает с понятной ошибкой при старте, экономит часы отладки по сравнению с тем, которое молча работает на порту 0.

Когда что выбирать

CLI-утилита без деплоя

Только флаги. Стандартный flag или pflag (POSIX-стиль с двойным дефисом). Файлы и env — overkill.

Микросервис в Kubernetes

Env для секретов (envFrom: secretRef), YAML-файл через ConfigMap для остального, флаги — для локальной отладки. Приоритет: файл → env → флаги.

Монолит с десятками параметров

Файл (YAML или TOML) как основной источник, env для per-environment переопределений, флаги для аварийного override. Рассмотрите горячую перезагрузку через fsnotify^* для параметров, не требующих перезапуска (уровень логирования, feature flags).

^* fsnotify — Go-библиотека для отслеживания изменений файловой системы через OS-события (inotify на Linux, kqueue на macOS). Позволяет перечитать конфиг без перезапуска процесса.

Что делать дальше

После того как конфигурация загружается предсказуемо, стоит закрыть два вопроса. Первый — секреты: не храните их ни в файлах, ни в env в открытом виде в проде; посмотрите в сторону HashiCorp Vault или встроенного секрет-менеджера вашего облака. Второй — документирование: сгенерируйте таблицу «переменная — тип — значение по умолчанию — описание» из тегов структуры и положите её в README. Это дешевле, чем отвечать на одни и те же вопросы при онбординге.