Знакомство с Viper: конфигурация без боли

Viper написана Стивом Франсией — тем же человеком, что и Cobra, — и с 2014 года живёт рядом с ней в github.com/spf13/viper. Идея простая: приложение спрашивает значение по строковому ключу — viper.GetInt("server.port") — а откуда оно взялось, спрашивающего не волнует. Источников пять: значения, заданные кодом через viper.Set; флаги, привязанные через BindPFlag; переменные окружения; конфиг-файл; и дефолты через SetDefault. Viper сама хранит порядок силы: Set сильнее флага, флаг сильнее окружения, окружение сильнее файла, файл сильнее дефолта. Ваш код про настройки — одна строка чтения, а не лестница из LookupEnv и парсеров. С Cobra они ходят парой в kubectl и Hugo, и весь остаток курса мы будем собирать эту связку по кусочкам: сегодня — реестр и типы, в следующих уроках — файлы и окружение.

Ключевую таблицу Viper стоит выучить наизусть — порядок силы источников. Сверху вниз: viper.Set — значение, заданное кодом во время работы; затем флаги, привязанные BindPFlag; затем переменные окружения; затем конфиг-файл; в самом низу — SetDefault. Когда вы спрашиваете GetInt, Viper проходит список сверху вниз и отдаёт первый найденный слой. Из этого следуют практические привычки: дефолты задаём сразу и много — их всегда перекрывает что-то живое; viper.Set используем осторожно — он сильнее пользователя, и если где-то в коде спрятан Set для порта, флаг бесполезен; спор флаг против окружения решается в десятой функции. Для отладки реестра пригодятся два метода-обзора: viper.AllKeys() возвращает список всех известных ключей, viper.AllSettings() — всю карту значений разом; их удобно печатать по флагу --verbose, пока лестница приоритетов не въелась в память. Всё устройство — один отсортированный список источников внутри библиотеки; никакой магии, только дисциплина порядка.

Полезно помнить, против чего Viper бунтовала. В стандартной библиотеке Go нет ни одного пакета конфигурации: flag отвечает за флаги, остальное — на вас. Типичный проект выглядел лестницей: os.LookupEnv для окружения, encoding/json или самописный парсер для файла, flag для терминала — и в каждом месте свои нулевые значения и свои ошибки. О порядке перекрытий обычно забывали: выигрывал тот источник, который проверялся последним. Viper не открыла ничего нового: она закрепила порядок, дала один API и стандартизировала ответы на четыре вопроса — где искать файл, что делать, когда его нет, как приводить типы и кто кого перекрывает. Ценность не в объёме библиотеки, а в том, что порядок больше не предмет обсуждения в каждой команде.

Внутри приведением занимается маленький пакет spf13/cast, и ведёт он себя свободнее, чем вы ожидаете. GetInt("8080") по строковому значению вернёт число, GetString(8080) — строку: приведение работает в обе стороны. GetDuration понимает и «5s», и число наносекунд; GetStringSlice развернёт и список, и одиночное значение. Плата за свободу — молчание при неудаче: если значение привести нельзя, Get* возвращает нулевое значение своего типа и ни одной ошибки. Ноль вместо порта, пустая строка вместо пути, false вместо режима — и программа продолжает жить с тихо испорченной настройкой. Отсюда правило: значения, от которых зависит запуск, проверяйте через IsSet и собственную валидацию — cast отвечает за удобство, а не за корректность. И ещё нюанс: viper.Get по несуществующему ключу вернёт nil, а GetInt по нему — 0; отличить «настройки нет» от «настройка ноль» Get не умеет, для этого существует IsSet.

Дефолты в Viper живут в коде, и это осознанное решение: SetDefault — одновременно и настройка, и документация, ведь ключи с описаниями лежат в одном месте рядом с main. Вызывать SetDefault можно сколько угодно раз и по любым ключам; точка в имени — вложенность: server.port означает секцию server с полем port, и в конфиг-файле следующего урока она же превратится в вложенную структуру YAML. Вызывайте дефолты до чтения конфига — технически порядок не важен, но один блок SetDefault в начале initConfig читается как оглавление настроек приложения. По отношению к паттерну binding из шестого урока здесь есть дублирование: дефолты и в структуре, и в Viper. Пока допустимо; в десятой функции Unmarshal соберёт весь реестр в структуру одним вызовом, и двойной учёт исчезнет.

Теперь честная часть. Если у утилиты один источник настроек — флаги из шестого урока, — Viper не нужна: паттерн binding закрывает вопрос, а лишняя зависимость в go.mod — это не только мегабайты, но и магия приоритетов, которую придётся объяснять каждому новому человеку в команде. История зависимостей у Viper тяжёлая: долгие годы она тянула клиентские библиотеки etcd и Consul для remote-бэкендов, в свежих версиях их спрятали за build-теги, но библиотека по-прежнему заметно толще flag. Мой критерий такой: появился второй источник настроек — файл или переменные окружения, — Viper окупается в первый же час; пока источник один, она окупается никогда. Спорное мнение: некоторые тянут Viper ради Get-ключей даже в маленьких утилитах — единообразие, говорят. Не соглашусь: GetString("port") вместо cfg.Port — это плюс строка, плюс кавычки, минус проверка типов компилятором. Останьтесь на структурах.

Реестр работает, но пока в нём только дефолты. Следующий урок, конфиг-файлы: YAML, TOML и JSON, научит Viper читать файл с диска и обрабатывать ConfigFileNotFoundError — ситуацию первого запуска, когда файла ещё нет. После файлов пойдут переменные окружения через AutomaticEnv — тот самый слой, который делает утилиту дружелюбной к CI. Обзор всего курса со списком уроков — на странице Cobra. Код урока, как всегда, требует локального Go с viper в go.mod: соберите, запустите, поменяйте дефолт на строку и посмотрите, как GetInt молча его проглотит.