Ошибки и коды выхода: SilenceUsage

Контракт простой: RunE возвращает error, Cobra печатает его и usage-страницу, Execute отдаёт ошибку вызывающему. Звать os.Exit внутри RunE не нужно и вредно: os.Exit завершает процесс немедленно, минуя defer, а значит, открытые в команде файлы не закроются и PostRun-хуки из предыдущего урока не выполнятся. Пока ошибка возвращается по цепочке, у программы остаётся шанс прибраться. Стандартный хвост main выглядит так: if err := rootCmd.Execute(); err != nil { os.Exit(1) } — сообщение об ошибке уже напечатано Cobra, main лишь выставляет код. Забытый хвост — самый дешёвый баг года: Execute вернул ошибку, main дошёл до конца нормально, процесс закрылся с нулём, и мониторинг остался в неведении. Проверьте свой main прямо сейчас, это одна строка, — и переходите к тонкостям печати.

По умолчанию ошибка в RunE тянет за собой usage-страницу: пользователь опечатался во флаге и получил два экрана списка команд, среди которых ещё нужно найти саму ошибку. Для человека это шум, для скрипта — мусор в stderr. rootCmd.SilenceUsage = true убирает печать usage при ошибках; справка по --help продолжает работать, потому что SilenceUsage глушит только реакцию на ошибку, а не сам механизм usage. SilenceErrors идёт дальше: Cobra не печатает и само сообщение Error:, ошибка возвращается нетронутой, и печать берёт на себя main — один формат, одно место. Флаги можно ставить и на конкретную команду, а проверка в ExecuteC смотрит оба уровня: достаточно SilenceUsage или SilenceErrors на команде или на корне, чтобы соответствующая печать заглохла. Рабочий дефолт для утилит с командами — SilenceUsage на корне: пользователи знают, что флаги перечислены в --help, и не нуждаются в их повторе после каждой опечатки.

Код выхода — единственный канал, через который утилита говорит с обёртками: шелл читает $?, CI сравнивает его с нулём, оркестратор решает, перезапускать ли контейнер. База простая: ноль — успех, всё остальное — ошибка. Но у разветвлённых утилит полезен словарь кодов: 1 — общий провал, 2 — ошибка использования, как поступает ряд системных утилит, 3 — частичный успех вроде «синхронизировано 9 из 12». Словарь фиксируется в документации рядом с описанием команд, а не в голове автора, — иначе скриптописатели начнут угадывать. Реализация аккуратно укладывается в тип: RunE возвращает свой тип ошибки с полем Code, main разбирает его через errors.As и зовёт os.Exit с нужным числом. Дополнение к словарю: код 128+N шелл показывает, когда процесс убит сигналом N — знакомый всем 130 после Ctrl+C это 128+2. Возвращайте такой код и сами, когда прерывание пришло извне, а cleanup успел завершиться: скрипты отличат отмену от обычного провала. И помните свойство os.Exit из начала урока: он завершает процесс немедленно и defer не выполняет, поэтому весь словарь живёт в main, а не в командах.

Ошибка «permission denied» без контекста — детектив для пользователя: что именно не открылось и в какой команде? fmt.Errorf("read %s: %w", path, err) добавляет путь и причину в одну строку, а глагол %w сохраняет исходную ошибку внутри: errors.Is(err, os.ErrNotExist) и errors.As продолжают работать по всей обёрнутой цепочке. В CLI это превращается в конкретику двух уровней: RunE добавляет операцию — что делали, main добавляет команду — где делали. Разверните привычку из языка Go: каждый слой добавляет контекст, ничего не теряя, и ваши сообщения станут самодиагностируемыми — по одной строке из лога видно, какая команда, на каком файле и по какой причине упала. Полная механика %w, errors.Is и errors.As разобрана отдельным уроком в продвинутом курсе, здесь мы используем только её следствия.

Разделение потоков — половина культуры вывода CLI. В stdout пишется результат: список заметок, идентификатор созданной записи, путь к файлу — то, ради чего команду зовут и что скрипты ловят через перенаправление. В stderr — всё остальное: ошибки, предупреждения, прогресс, диагностику. Форматирование здесь то же, что и у fmt.Println, только поток другой: fmt.Fprintln(os.Stderr, ...) и fmt.Fprintf(cmd.ErrOrStderr(), ...). Cobra по умолчанию вежлива: и Error:, и usage при ошибке уходят в stderr, если вывод не переопределён через SetOut — проверьте это, прежде чем парсить вывод своих команд в шелле. Нарушение разделения стоит дорого: notes list 2>/dev/null | grep id перестанет находить идентификаторы, как только одна строка диагностики уедет в stdout, а отладка таких утечек — то ещё удовольствие, потому что отдельно взятый запуск в терминале выглядит правильно.

Схема ошибки — RunE, SilenceUsage, код выхода — теперь финальная, осталось научиться её проверять. В уроке про тестирование команд Execute вызывается из теста, вывод ловится буфером вместо терминала, и ошибки сравниваются без os.Exit — ровно поэтому os.Exit и держат в main, подальше от RunE. Как всё это собирается в цельную утилиту, покажет итоговый проект: команды add/list/done с хранилищем, кодами выхода и тестами. Механика оборачивания разобрана отдельно в уроке про ошибки и %w продвинутого курса, обзор остальных тем — на странице Cobra. Как всегда с CLI: код выхода видит только живой процесс — соберите утилиту локально, уроните её специально и проверьте значение $? в шелле.