Конфигурация без магии: env, флаги, файлы и типизированный Config, падающий на старте

Три источника, одна лестница

Зачем конфигурации вообще нужна лестница приоритетов? Потому что у флагов, переменных окружения и файлов разные владельцы — и когда они расходятся, нужно правило, достаточно очевидное, чтобы разобраться в нём в три ночи. Production-сервисы на Go тянут конфигурацию из трёх мест, у каждого — свой реальный потребитель. Переменные окружения — 12-factor-база: на деплой, без пересборки, нативно для любого оркестратора — но это плоские строки, невидимые, пока их не напечатаешь, и наследуемые каждым дочерним процессом. Флаги служат операторам: -help — живая документация, а разовый override в терминале лучше правки манифеста. Файлы несут сложные формы — вложенные структуры, списки, per-tenant-карты, — которые умирают тысячей смертей при кодировании в env-строки, и проходят код-ревью. Порядок разрешения — лестница приоритетов, побеждает более осознанный:

Парсить один раз, валидировать жадно

У дисциплины, предотвращающей инцидент из крючка, две половины. Первая: конфигурация читается ровно в одном месте, на старте, в типизированную структуру — никакого os.Getenv ниже main. Вторая: валидация жадная и фатальная. Сервис, загрузившийся с мусорным конфигом, падает на запросе — часами или днями позже, под трафиком; сервис, отказавшийся загружаться, падает внутри деплоя, где раскатка останавливается автоматически, а старые поды продолжают обслуживать.

type Config struct {
	HTTPAddr     string
	CacheTimeout time.Duration
	DatabaseURL  Secret // см. ниже
}

func Load(args []string) (Config, error) {
	cfg := Config{HTTPAddr: ":8080", CacheTimeout: 50 * time.Millisecond} // дефолты

	if v, ok := os.LookupEnv("CACHE_TIMEOUT_MS"); ok { // unset и пустая — разные вещи
		ms, err := strconv.Atoi(v)
		if err != nil || ms <= 0 {
			return Config{}, fmt.Errorf("CACHE_TIMEOUT_MS=%q: нужно положительное целое", v)
		}
		cfg.CacheTimeout = time.Duration(ms) * time.Millisecond
	}

	fs := flag.NewFlagSet("api", flag.ContinueOnError)
	fs.StringVar(&cfg.HTTPAddr, "http", cfg.HTTPAddr, "адрес для прослушивания") // флаг бьёт env
	if err := fs.Parse(args); err != nil {
		return Config{}, err
	}
	return cfg, cfg.validate() // обязательные поля, диапазоны, синтаксис URL — всё сейчас
}

LookupEnv — несущая деталь: Getenv не отличает не задана от задана пустой, а это ровно та неоднозначность, что превратила отсутствующую переменную в тихий ноль. Хендлеры получают Config — или только нужную им под-структуру — через конструкторы: зависимость видна в сигнатурах и тривиально подменяется в тестах.

Секретам не место в дампах

Когда вы печатаете конфиг-структуру — а вы будете, в бут-логах или краш-репортах, — каждое незащищённое поле становится вектором утечки. Конфиг-структуры печатаются: бут-логи, краш-репорты, %+v в пути ошибки, debug-эндпоинты. Каждое из этих мест — вектор утечки пароля базы, вшитого в DSN. Флаги хуже — аргументы процесса читаются любым ps на shared-хостах. Go-нативное сдерживание — именованный тип, чьё форматирование врёт:

type Secret string

func (Secret) String() string       { return "[REDACTED]" }
func (Secret) LogValue() slog.Value { return slog.StringValue("[REDACTED]") }
func (s Secret) Reveal() string     { return string(s) } // явно и greppable

// fmt %v, %s, %+v и slog проходят через String/LogValue. json.Marshal — НЕТ:
// он читает нижележащую строку, так что определите ещё и MarshalJSON,
// если структура хоть когда-то может попасть в энкодер.

Reveal() — суть паттерна: каждое место, где сырой секрет покидает тип, теперь осознанный, ищущийся грепом акт, а не случайность форматирования. Reflection-энкодеры обходят Stringer, поэтому честная версия реализует и MarshalJSON — команды узнают это в день, когда support-бандл с сериализованным конфигом приземляется в тикет-системе.

Горячая перезагрузка, честно

Слежение за файлом выглядит апгрейдом и обычно оказывается даунгрейдом. Рестарт применяет конфиг через ровно тот путь, который вы тестируете каждым деплоем: парсинг, валидация, отказ-или-обслуживание. Reload создаёт второй путь, который выполняется редко и без тестового покрытия: полуприменённые обновления, где часть горутин держит старое значение, валидация наперегонки с in-flight запросами, причуды fsnotify вокруг симлинк-танца, который Kubernetes устраивает при обновлении ConfigMap, и флот, где каждый под подхватил изменение в свой момент. Rolling-рестарт деплоймента на двадцать подов стоит пару минут и ноль новых код-путей. Reload отрабатывает свою сложность в двух местах: флоты настолько большие, что рестарт-штормы стоят реальной ёмкости, и значения, меняющиеся много раз в день, — а это feature-флаги, и им место в flag-сервисе с явным версионированием и аудитом, а не в наблюдаемом файле.

Конфиг библиотеки — другая задача

Паттерн «типизированная структура на буте» — для приложений: они владеют main и могут быть исчерпывающими. У библиотек противоположные ограничения: экспортируемый API, замороженный обещаниями совместимости, вызывающие, которые задают два из пятнадцати параметров, и неоднозначность нулевого значения — Timeout: 0 значит «не задан, возьми дефолт» или «осознанно без таймаута»? Функциональные опции решают все три:

type Option func(*client)

func WithTimeout(d time.Duration) Option { return func(c *client) { c.timeout = d } }

func New(addr string, opts ...Option) (*Client, error) {
	c := &client{timeout: 5 * time.Second} // дефолт живёт здесь, без неоднозначности
	for _, o := range opts {
		o(c)
	}
	return c.validateAndBuild()
}

«Не задано» означает дефолт, потому что опцию просто не передали; новые параметры не ломают существующие вызовы; валидация выполняется при конструировании. Внутри приложения тот же паттерн — церемония: обычная структура greppable, исчерпывающа и очевидна.