Флаги и структура конфига: паттерн binding

Основа паттерна — обычная структура с именованными полями. Никаких map[string]any: я с картами настроек наигрался в старых проектах и больше не борюсь с искушением — опечатка в ключе карты живёт до рантайма, опечатка в поле структуры ловится компилятором на месте. Каждому флагу соответствует своё поле с честным типом: Port int, Host string, Watch bool. Рядом живёт конструктор defaultServeConfig(), который возвращает структуру с дефолтами — это единственное место, где значения по умолчанию задаются в коде. Третьий элемент — метод bindFlags(cmd), который навешивает Var-методы на поля структуры. Связка получается замкнутая: поле — строка биндинга — флаг в справке. Компилятор следит за типами, справка печатается сама, а тест может собрать конфиг руками, без os.Args.

Самый частый вопрос по паттерну: почему бы не собрать структуру прямо внутри RunE? Потому что к моменту вызова RunE разбор строки запуска уже закончен. Cobra парсит флаги в Execute — до Run, — и каждый флаг, который она встретила, должен быть зарегистрирован к этому моменту. Флаг, объявленный внутри RunE, объявлен слишком поздно: на нём разбор падает с unknown flag ещё до запуска команды. Поэтому биндинг живёт в init() файла команды — именно так раскладывает код генератор cobra-cli, — либо в конструкторе команды, который вызывается до AddCommand. Проверить это легко только локально: соберите утилиту и попробуйте оба варианта, песочница сайта строку запуска не исполняет. Ручной вызов cmd.ParseFlags внутри RunE тоже возможен, но нужен редко — это костыль для динамически объявляемых флагов, и в обычном CLI ему делать нечего.

Пока у нас два источника настроек, и иерархия простая: дефолт из конструктора перекрывается флагом, если пользователь его передал. pflag делает это бесплатно — пользовательское значение пишется в то же поле, куда смотрит Var-метод. Но CLI зреют, и между дефолтом и флагом встаёт конфиг-файл: пользователь один раз прописал порт в notes.yaml и не хочет набирать --port 8080 каждый запуск. План приоритетов, к которому мы придём к десятому уроку: дефолт — самый слабый слой, над ним конфиг-файл, над ним переменные окружения, и сильнее всех флаг, набранный в терминале. Чтобы флаг честно побеждал конфиг, связку берут на себя Viper и BindPFlag — о них пойдут седьмой и десятый уроки. Пока запомните принцип: чем ближе источник к пользователю, тем он сильнее, и структура с дефолтами — фундамент, на котором слои раскладываются без переписывания RunE.

Валидация — недооценённая часть паттерна. MarkFlagRequired отвечает только на вопрос «флаг передан вообще», а большинство ошибок настройки — про значения: порт занят или вне диапазона, таймаут в наносекундах из-за опечатки в единицах, watch на адресе 0.0.0.0, который выставляет сервер наружу. Собирать эти проверки в RunE — значит утопить бизнес-логику под парсингом; с Config-структурой им естественно живётся в методе Validate, который вызывается первой строкой RunE. Дополнительный бонус: валидатор можно гонять в тестах на готовых структурах — без Execute, без os.Args, без сборки бинарника. Отсюда и выбор RunE вместо Run: команда, которая может отклонить настройку, обязана уметь возвращать ошибку, а Run ошибки не пробрасывает — об этом отдельный разговор в уроке про коды выхода.

С ростом утилиты возникает соблазн сделать один гигантский Config на всё приложение — не поддавайтесь. У каждой подкоманды своя структура: serveConfig для serve, listConfig для list, и пересечение между ними — только персистентные флаги корня вроде --verbose, у которых своя маленькая структура или одиночные переменные. Общий конфиг оправдан в одном случае: несколько подкоманд одного семейства шарят один и тот же набор настроек — тогда общий тип в отдельном файле пакета cmd уместен. Связку между конфигом подкоманды и корневым состоянием делают параметры конструктора: подкоманда получает нужный кусок при создании, а не лезет в чужие пакеты за глобальной переменной. Такая изоляция бесплатна, пока дерево маленькое, и спасает, когда оно вырастает: правка настроек serve перестаёт задевать list чисто механически — файлы разные.

Когда доменный тип совпадает с набором настроек, промежуточный Config-тип не нужен: биндите флаги прямо в его поля. У репортера заметок есть тип Report с полями Limit, Author, Since — флаг --limit биндится в report.Limit, и слой передачи значений исчезает как класс. Нюанс один: доменный тип обязан жить в том же пакете, что и команда, либо в пакете, который команда может импортировать; циклические импорты в Go запрещены, и это само решает, чья ответственность где. Паттерн ломается, когда у команды настроек больше, чем полей у доменного типа: --verbose не про отчёт, а про вывод. В таких случаях комбинируйте: часть флагов в доменную структуру, часть — в маленький cmdConfig рядом. Я так делаю всегда: перебор абстракций ради одного булева флага дороже, чем два биндинга.

Скрытая выгода паттерна проявляется в тестах. До биндинга протестировать Run означало собрать os.Args руками и вызвать Execute — хрупко и многословно. С Config-структурой тест собирает структуру напрямую: cfg := serveConfig{Port: 8080, Watch: true}, прогоняет Validate и вызывает функцию serve с конфигом. Команда — тонкая оболочка над логикой, логика тестируется без CLI. Если вы уже проходили тестирование в продвинутом курсе, сравните оба подхода на своём проекте: разница в количестве кода на один тест — примерно в три раза. Мы к тестам Cobra-команд вернёмся ближе к финалу курса, когда дерево утилиты соберётся целиком; пока запомните приём — команда читает структуру, структура собирается где угодно.

Со следующего урока в проекте появится Viper, и вопрос «а куда теперь девается cfg?» закономерен. Ответ: структура остаётся, а наполняется иначе. Пока источника два — дефолт и флаг, — биндинг из этого урока работает как есть. Когда добавятся файл и окружение, порядок наполнения станет таким: defaultServeConfig задаёт базу, Viper читает конфиг и окружение, и в конце срабатывает BindPFlag или ручной перенос флагов — самый сильный слой. В десятой функции Unmarshal соберёт реестр Viper в структуру одним вызовом, и тогда bindFlags либо перепишется на BindPFlag, либо останется командам без конфига. Важно, что интерфейс RunE не меняется ни на каком шаге: команда по-прежнему читает структуру. Именно поэтому паттерн binding стоит ставить сразу, а не «когда понадобится конфиг»: миграция слоёв не трогает ни одну команду.

Структура с дефолтами и флагами закрывает два слоя из плана приоритетов; третий — конфиг-файл — потребует библиотеки, и следующий урок, знакомство с Viper, покажет, что она решает и когда её брать не нужно. Полная связка флагов с Viper и расстановка слоёв — в уроке про приоритеты конфигурации, а пример того же паттерна в другом фреймворке — в уроке про zap.Config, где YAML-конфиг собирается в структуру логгера. Обычное напоминание: паттерн проверяется только в терминале — соберите serve, прогоните его с -p 9000 и без флагов, сравните вывод; песочница сайта Cobra не исполняет.