Переменные окружения: AutomaticEnv

viper.AutomaticEnv() — включатель. После него каждый Get проверяет окружение: viper.GetInt("server.port") сначала смотрит, задана ли переменная с подходящим именем, и только потом идёт дальше по слоям — к конфигу и дефолтам. Имя переменной собирается из ключа: точки и дефисы превращаются в подчёркивания, буквы поднимаются в верхний регистр. Ключ server.port соответствует переменной SERVER_PORT, ключ verbose — VERBOSE. Заметьте: сам ключ в реестре при этом не появляется — AutomaticEnv не регистрирует ничего, он только перехватывает запросы. Если утилита одна на машине и живёт в изоляции, без префикса можно жить; как только рядом появляется вторая утилита с тем же ключом, начинается конфликт имён — и его решает следующий вызов, SetEnvPrefix. Обратите внимание на слово «каждый Get»: окружение опрашивается в момент чтения, а не один раз при старте — это важно для понимания того, какие ключи вообще окажутся видимыми. Практический вывод из ленивости: читать значение до включения AutomaticEnv бессмысленно, а после включения любое обращение к известному ключу уже проверит переменную. Если переменная задана, она вернётся даже тогда, когда файл конфига существует и задаёт другое значение — окружение в цепочке стоит выше файла, и это поведение по умолчанию, а не ошибка.

Префикс — не прихоть, а страховка от коллизий: PATH, HOME, PORT, USER уже заняты системой, и утилита, читающая переменную PORT без префикса, рано или поздно наткнётся на чужую. Посмотрите на большие CLI: docker читает DOCKER_HOST, kubectl — KUBECONFIG, gh — GH_TOKEN. Все они держат собственный префикс, и это часть публичного контракта утилиты, документированная наравне с флагами. Конвенция имени складывается из трёх частей: префикс утилиты, путь ключа, верхний регистр. NOTES_SERVER_PORT читается как «в NOTES переменная для server.port». Дефисы в ключах заменяются наравне с точками: ключ max-backups превращается в MAX_BACKUPS. Плоский ключ verbose с префиксом становится NOTES_VERBOSE, а не голым VERBOSE. Подводный камень — регистр: AutomaticEnv ищет переменную по строгому шаблону, и notes_server_port Viper не увидит, сколько ни экспортируйте; это самый частый вопрос в issues, и лечится он только правильным именем, не кодом.

AutomaticEnv строит имя по шаблону, а BindEnv связывает ключ с переменной напрямую — с любой, какую вы назовёте. viper.BindEnv("server.port", "NOTES_PORT") говорит: этот ключ читается из NOTES_PORT, шаблон не нужен. Вторая форма — viper.BindEnv("server.port") без второго аргумента: Viper сама построит имя из префикса и ключа, но, в отличие от ленивого AutomaticEnv, зарегистрирует ключ в реестре заранее, и он появится в AllKeys и AllSettings. Это различие решает известную проблему «невидимых» ключей: AutomaticEnv проверяет окружение только в момент, когда кто-то спрашивает конкретный ключ, а ключ, о котором никто не спросил, не попадает ни в списки настроек, ни в Unmarshal. BindEnv вызывается на каждый ключ отдельно, поэтому в больших конфигурациях им перечисляют только особые случаи, а остальное покрывают связкой AutomaticEnv плюс дефолты. Мой ориентир: всё, что задокументировано в README как переменная, должно быть либо дефолтом, либо BindEnv — документация обещает ключ, и реестр обязан его знать; иначе пользователь получит пустое значение ровно тогда, когда поверил документации.

Честно про практику: главные потребители переменных окружения — не человек за ноутбуком, а CI и контейнеры. В docker-compose один образ конфигурируется окружением: тот же бинарник notes становится dev-версией с NOTES_SERVER_PORT=8080 и прод-версией с NOTES_SERVER_PORT=443, без пересборки. В GitHub Actions секреты приходят только окружением, и связка AutomaticEnv с префиксом ложится на это идеально. В systemd-юните ту же работу делает Environment=. Файл остаётся для того, что человек правит руками, — пути, таймауты, списки; окружение — для всего, что меняется между средами запуска. В этом и смысл двенадцатого фактора: конфигурация отделена от кода, потому что код один, а окружения разные. Правило раскладки простое: если значение меняется от машины к машине — окружение; если оно одинаково для всех запусков на этой машине — файл. Второй вывод следует из первого: чем меньше настроек меняется между средами, тем меньше переменных надо задавать в каждом деплое, поэтому дефолты в коде — не услужение, а экономия на каждом следующем окружении.

Локальная разработка живёт между двумя мирами: экспортировать десяток переменных в каждый новый терминал лень, а контейнер не нужен. Тут удобен .env-файл рядом с проектом: docker-compose умеет читать его через env_file, а чистый Go — через библиотеку godotenv, которая грузит файл в os.Environ до того, как Viper начнёт опрос. Важно понимать границы: .env-файл — это не механизм Viper, а костыль для удобства разработчика, и в продакшн его не берут. Файл с секретами не попадает в git — строка .env в .gitignore пишется раньше, чем сам файл, и проверяется это перед первым коммитом, а не после утечки. О тонкостях обращения с секретами и .env мы отдельно поговорим в уроке про watch и секреты; здесь достаточно правила: локально — .env, в CI и контейнерах — честные переменные окружения.

Разбор такой жалобы всегда один и тот же, сверху вниз. Первый шаг: убедиться, что имя совпало байт в байт — echo $NOTES_SERVER_PORT в том же shell, где запускается утилита; sudo, systemd и запускатели из IDE не наследуют ваш export, и это ловит половину случаев. Второй шаг: viper.AllKeys() — напечатайте список и найдите свой ключ; его там нет, значит ключ никто не зарегистрировал дефолтом или BindEnv, и ленивое окружение про него не знает. Третьего шага обычно не остаётся: если ключ зарегистрирован, переменная задана и имя совпало — Get вернёт значение. Полезная деталь для отладки: viper.IsSet("server.port") отвечает «задан ли ключ хоть в каком-то слое», не выдавая само значение. Ещё один источник сюрпризов — пустые значения: export NOTES_VERBOSE= оставляет переменную заданной, но пустой, и GetBool честно вернёт false, не отличив это от отсутствия. Вся цепочка проверяется только локально: соберите утилиту и пройдите её руками, браузерная песочница переменные не экспортирует.

Окружение читается, но вопрос «кто кого перекрыл» остался открытым, потому что в этом уроке мы сознательно обходили его стороной: приоритеты конфигурации расставят флаг, env, файл и дефолты по местам, заодно привяжут флаги к реестру через BindPFlags и выгрузят всё в Config-структуру. Про тонкости секретов, .env-файлов и горячей перезагрузки — в уроке про watch и секреты. Обзор курса — на странице Cobra. И стандартная оговорка: окружение проверяется только локально — соберите утилиту, экспортируйте NOTES_SERVER_PORT и убедитесь, что она победила файл; песочница сайта переменные не экспортирует.