Справка: кастомизация help и usage

У каждой команды в Cobra две страницы, и это разные тексты. Usage — выжимка: строка использования UseLine, алиасы, список доступных подкоманд, локальные и глобальные флаги. Help — то, что печатается по флагу --help и по команде help: сначала абзац Long, затем Example, а в конце — usage-страница целиком. Из этого устройства следует главное правило кастомизации: содержимое пишем в поля, а не в шаблоны — Long и Example попадают на страницу сами, шаблоны нужны, когда не устраивает раскладка. Usage чаще всего видит расстроенный пользователь: при ошибке разбора флагов Cobra печатает сообщение и следом usage-страницу, и простыня флагов в этот момент скорее мешает найти саму ошибку — как её убрать, разбирается в уроке про ошибки и коды выхода. Отрендеренную usage можно получить и из кода: метод UsageString() возвращает её строкой, чем пользуются и кастомные шаблоны, и тесты.

Шаблон help — обычный text/template из стандартной библиотеки: в двойных фигурных скобках доступны поля команды, и на них можно собрать что угодно. Минимальная осмысленная замена дефолту — SetHelpTemplate с телом из описания и usage: {{.Long}}, пустая строка, {{.UsageString}}. В шаблоне доступны .Long, .Short, .Example, .CommandPath, .UseLine, .Runnable, флаги через .LocalFlags и .InheritedFlags, а из функций — rpad, gt, eq и trimTrailingWhitespaces, которыми пользуется и дефолтный шаблон. Важная деталь механики: шаблон ищется не только на самой команде. Не нашли у подкоманды — Cobra поднимается по дереву и берёт шаблон ближайшего предка, у которого он задан; установили на корне — получили для всего дерева сразу. И следите за концом шаблона: печатается ровно то, что в нём написано, включая финальный перенос строки, — без него справка прилипнет к следующему приглашению терминала.

Usage-шаблон устроен плотнее: дефолт собирает строку использования, алиасы, примеры, доступные команды, флаги, глобальные флаги и дополнительные темы помощи — каждая секция через своё условие {{if}}. Кастомизация здесь обычно точечная: русифицировать заголовок Available Commands, спрятать секцию Additional help topics, добавить в конец строку со ссылкой на документацию. Механика наследования та же, что у help-шаблона: SetUsageTemplate на корне действует на всё дерево, а отдельная команда со своим шаблоном переопределяет только себя. Совсем заменить рендеринг функцией можно методом SetUsageFunc — она принимает func(*cobra.Command) error и пригодится, когда странице нужно то, чего шаблоном не выразить, например вывод через внешнюю программу. На практике функций хватает одному проценту утилит: сначала пробуйте шаблон, и только упершись в его пределы — SetUsageFunc.

Когда шаблонов мало, остаётся функция. SetHelpFunc принимает func(*cobra.Command, []string) и полностью забирает рендеринг: Cobra больше ничего не печатает, всё на вас — хоть JSON для скриптов, хоть вывод через пейджер вроде less, хоть запрос к внешней программе. Аргументы — сама команда и хвост, который пользователь дописал после слова help: вызов notes help serve принесёт в функцию serve. Внутри принято печатать через cmd.OutOrStdout(): при обычном запуске это stdout, а в тестах вывод перехватывается буфером — им же мы будем ловить справку в уроке про тестирование. Наследование работает и здесь: HelpFunc ищется по дереву вверх, и функция корня отрисует справку всем подкомандам, у которых своей нет. Скажу честно, как о рабочем опыте: в девяти проектах из десяти хватает Long, Example и одного шаблона, а SetHelpFunc остаётся лазейкой на особые случаи — держите её в голове, но не открывайте без причины.

Флаг -h/--help не объявляется руками: Cobra добавляет его каждой команде сама, через InitDefaultHelpFlag, в момент выполнения. Поэтому notes serve --help показывает справку именно serve: её Long, её Example, её флаги, а флаги корня попадают в отдельную секцию Global Flags. Help-команда тоже строится автоматически, и notes help serve приводит к той же странице, что и notes serve --help, — разница только в привычке. Для --help не выполняется ни Run, ни хуки из следующего урока: проверка флага случается раньше, поэтому справка открывается мгновенно даже у тяжёлых команд, и звать её из скриптов безопасно. Если понадобится своё поведение помощи, команду help можно подменить через SetHelpCommand — но это экзотика, и в девяти случаях из десяти штатного флага достаточно.

Страница справки собрана, и в следующем уроке про хуки PreRun и PostRun мы переходим к тому, что происходит вокруг выполнения команды: цепочка PersistentPreRunE → PreRunE → RunE → PostRunE и знаменитая ловушка наследования PersistentPreRun. Справка — идеальный кандидат на тест: в уроке про тестирование команд вывод --help ловится буфером и сравнивается с ожидаемым, так что правки шаблона перестанут быть слепыми. Обзор всех тем курса — на странице Cobra. И напоминание про среду, уже знакомое по другим урокам курса: шаблоны исполняются только живой утилитой, поэтому соберите проект локально, вызовите --help для корня и пары подкоманд и прочитайте результат своими глазами раньше, чем это сделают пользователи.