|
|
|
Professor Seleznov
|
Что регулярно ломается в реальных сервисах, когда надо совместить YAML, .env, переменные окружения и вложенный Config.-Вот абсолютно бытовая ситуация. Есть config.yaml для локалки. Есть .env.example, который у каждого чуть свой. В проде значения прилетают через Docker/Kubernetes/systemd. В коде живет нормальный вложенный Config, а не плоская простыня.
И вот в этот момент становится ясно: в Go нет одного «очевидного» инструмента, который без плясок закрывает всю цепочку целиком.
Это не наезд на экосистему. В ней много сильных библиотек. Проблема в другом: почти каждая решает свой кусок, а швы между кусками остаются на команде.
-
Проблема в одном примере
В коде:
type Config struct {
HTTP struct {
Listen string
TLS bool
}
Database struct {
URL string
}
}
В docker-compose.yml — http.listen. В Kubernetes — HTTP_LISTEN. В YAML кто-то пишет database.url. Провайдер PostgreSQL в документации советует DATABASE_URL.
Все правы. Но бинарнику от этого не легче.
Ему нужно:
- Прочитать разные форматы.
- Слить источники в понятном порядке приоритетов.
- Заполнить типизированную структуру без ручного ада из os.Getenv и strconv.
Именно на этом месте «конфиг» перестает быть одной задачей и разваливается на три.
-
Что я называю «единым» решением
Для себя я держу простой чек-лист:
- Парсинг форматов — YAML/JSON/INI/dotenv.
- Слои и приоритеты — defaults < repo config < local override < process env (по логике 12-factor).
- Нормализация ключей — чтобы sub-service, sub_service и SUB_SERVICE жили в одном мире.
- Декод в структуры — конечная цель это Config, а не map.
- Обратная кодировка — уметь вывести эффективный конфиг обратно в файл.
- CLI для операционки — чтобы не писать вспомогательные cmd/* для каждой мелочи.
- Тестируемость — без скрытых глобалов, с фиксированным и проверяемым merge-поведением.
Важно: это не значит «одна библиотека обязана уметь всё». Нормально, когда инструмент закрывает 2-3 пункта. Ненормально, когда в README обещается «полный цикл», а сложные кейсы остаются «догадайтесь сами».
-
Кратко по инструментам
Viper
Viper — первый выбор у многих. Большое сообщество, много примеров, привычный API.
Где боль: вложенные env-ключи и связка AutomaticEnv + SetEnvKeyReplacer + BindEnv. Проблема известная и давняя, это видно по тредам вроде #641 и #2001.
Итог: рабочий вариант, особенно если команда уже на нем. Но с вложенным конфигом и сложным env-layout нужна дисциплина.
Koanf
Koanf обычно воспринимается как более аккуратная композиция: providers, parsers, явный merge-порядок.
Плюс: пайплайн прозрачен. Минус: часть решений все равно на вас (нормализация ключей, соглашения по env, стратегия декода).
Env-first библиотеки
caarlos0/env, envconfig, cleanenv отлично подходят, когда источник истины — env, а задача — быстро собрать типизированный Config.
Если же у вас YAML + env + несколько слоев, они не дадут весь конвейер «из коробки». Нужен клей.
Dotenv-парсеры
joho/godotenv делает ровно то, что заявлено: корректно читает .env.
Это хороший кирпич. Но не целый дом.
«Просто парсеры»
encoding/json, gopkg.in/yaml.v3, INI-библиотеки — хорошие парсеры.
Но они не решают сами по себе:
- порядок слоев,
- env-override,
- нормализацию имен ключей между форматами.
mapstructure
go-viper/mapstructure (v2) — по факту стандартный мост из map[string]any в структуру.
Это не парсер и не merge-движок. Его задача — декод. Поэтому без аккуратной «середины» (о ней ниже) магии не будет.
-
Почему вложенные структуры — главный тест
На плоском конфиге почти всё выглядит красиво. Проблемы приходят, когда структура становится реальной:
- Embedding /squash: где-то поля должны «подниматься», где-то жить в поддереве.
- Несколько тегов на одно поле: json, yaml, mapstructure, иногда env.
- Списки в env: a,b,c, JSON-строка, индексные ключи — у всех свои правила.
- Слабая типизация: особенно заметно на стыке any, float64, yaml-особенностей и env-строк.
- *Sectionvs value: отсутствие ключа, пустое значение и nil — не одно и то же.
- «JSON в env»: рабочий костыль, но часто больной в эксплуатации (кавычки, экранирование, логирование).
Если библиотека шикарна на плоском env, но сыпется на вложенных деревьях — это не «плохая библиотека». Просто ее зона оптимизации другая.
-
Недостающая середина: map в центре пайплайна
Практически везде рабочая схема выглядит так:
bytes -> nested map[string]any -> mapstructure -> struct
Левая часть — чтение источников. Правая — декод в структуру. А вот середину (merge + нормализация ключей) команды часто собирают сами и по-разному.
Почему это важно явно оформить:
- Одна точка для кросс-форматной эквивалентности (sub-service == SUB_SERVICE после нормализации).
- Предсказуемые тесты (можно проверять merged-map до декода).
- Простой CLI (convert, merge, get — это по сути операции вокруг той же map).
Это не призыв «всё переписать на map». Это призыв честно назвать центральный этап, от которого зависит поведение всей системы.
-
Практический вывод
Универсальной «серебряной пули» нет. Есть осознанный выбор того, каким слоем вы управляете сами, а что делегируете библиотеке.
Два правила, которые реально экономят время:
- Сразу зафиксируйте модель приоритетов и именования ключей. Не «когда начнет гореть», а в первый день.
- Сделайте merge + normalizer отдельным, тестируемым слоем. Это чаще окупается сильнее, чем замена одной библиотеки на другую.
-
Где здесь go-config
go-config — попытка сделать именно эту «середину» предсказуемой:
- одинаковый Codec-подход для env, yaml, json, ini;
- deep merge для map и last-write-wins для скаляров;
- нормализация ключей через LowerAlnum;
- CLI envc для convert / get / merge.
Для контейнеров отдельный плюс: пакет env умеет слоить dotenv-файлы и затем применять WithCurrentEnvironment(). Это берет текущее окружение процесса (os.Environ() на момент Map) как верхний слой, поэтому одна и та же схема работает и локально, и в Docker/Kubernetes.
Это не «единственно правильный путь». Это одна из рабочих реализаций подхода, описанного выше.
Подробности API — в README. Архитектурные решения — в ASR.
-Источник
|
|
|
|
