CLI приложения #29. Архитектура: как не превратить консольную утилиту в монолит
За предыдущие выпуски мы успели разобрать немало возможностей CLI-приложений: аргументы и команды, форматирование вывода, конфигурацию, публикацию, установщики и даже сравнили JIT с Native AOT. Но почти всё это время мы рассматривали отдельные возможности, не слишком задумываясь о том, как организован код самого приложения.
А ведь консольная утилита тоже имеет свойство расти. Сегодня она принимает два аргумента и выводит результат, завтра появляются дополнительные команды, настройки, работа с файлами, сетевые запросы и обработка ошибок. И в какой-то момент оказывается, что наш некогда аккуратный Program.cs превратился в несколько сотен строк с условиями, проверками и вызовами всевозможных сервисов.
Давайте поговорим о том, как этого избежать. Причём не только применительно к System.CommandLine: принципы, которые мы рассмотрим, подходят практически для любого CLI-приложения.
Начнём с простого#
Представим небольшую утилиту для подсчёта строк исходного кода. Она получает путь к каталогу, перебирает файлы и выводит количество непустых строк.
Для первой версии вполне достаточно одного Program.cs:
var path = args.Length > 0
? args[0]
: Directory.GetCurrentDirectory();
var total = 0;
foreach (var file in Directory.EnumerateFiles(
path, "*.cs", SearchOption.AllDirectories))
{
foreach (var line in File.ReadLines(file))
{
if (!string.IsNullOrWhiteSpace(line))
total++;
}
}
Console.WriteLine($"Строк кода: {total}");
Здесь нет ничего плохого. Приложение небольшое, код понятный, и создавать ради него отдельные слои архитектуры было бы странно. Но теперь добавим исключения для каталогов bin и obj, поддержку нескольких языков, историю сканирований и команду сравнения результатов. А затем захотим использовать тот же механизм подсчёта строк из другого приложения.
Вот здесь уже появляется причина задуматься о структуре.
Разделяем ответственность#
Разобьём приложение на три основные части:
CLI-слой — принимает команды и аргументы, проверяет ввод, сообщает пользователю о результатах и ошибках.
Логика приложения — выполняет полезную работу: сканирует файлы, считает строки, сравнивает результаты.
Инфраструктура — взаимодействует с файловой системой, базой данных, сетью и другими внешними ресурсами.
Главное здесь не количество проектов или каталогов, а разделение ответственности. Например, обработчик команды scan не должен самостоятельно обходить файловую систему, разбирать правила исключений, сохранять историю и одновременно формировать красивую таблицу для терминала. Его задача гораздо проще: получить параметры, вызвать нужную операцию и представить результат пользователю.
Допустим, у нас есть сервис сканирования:
public sealed record ScanResult(
int Files,
int Lines);
public sealed class CodeScanner
{
public ScanResult Scan(string path)
{
var files = 0;
var lines = 0;
foreach (var file in Directory.EnumerateFiles(
path, "*.cs", SearchOption.AllDirectories))
{
files++;
foreach (var line in File.ReadLines(file))
{
if (!string.IsNullOrWhiteSpace(line))
lines++;
}
}
return new ScanResult(files, lines);
}
}
Это упрощённый пример: здесь ещё нет исключений, обработки недоступных файлов и поддержки других языков. Но он показывает главное — подсчёт строк больше не зависит от того, как пользователь запускает программу. Теперь эту логику можно вызывать из System.CommandLine, другого парсера, графического интерфейса или теста.
Тонкие обработчики команд#
Посмотрим, как могла бы выглядеть команда после такого разделения.
Не будем пока привязываться к конкретной библиотеке. Представим, что аргументы уже разобраны и проверены:
public sealed class ScanCommandHandler(
CodeScanner scanner,
TextWriter output)
{
public int Execute(string path)
{
var result = scanner.Scan(path);
output.WriteLine(
$"Файлов: {result.Files}, строк: {result.Lines}");
return 0;
}
}
Обработчик ничего не знает о том, как именно считаются строки. Он получает готовый результат и выводит его. Обрати внимание на TextWriter. Вместо прямого обращения к Console.WriteLine мы передаём поток вывода извне. Это небольшое решение позволяет при необходимости отправлять результат в консоль, файл или тестовый буфер. Конечно, не стоит делать из этого универсальное правило и заменять каждый Console.WriteLine абстракцией. Но если приложение развивается, управление вводом и выводом становится очень полезным.
Аналогично с кодами завершения: команда должна возвращать осмысленный результат выполнения, а не завершать процесс через Environment.Exit где-нибудь в глубине бизнес-логики.
Как организовать проект?#
Для небольшой или даже средней утилиты стоит начать с одного проекта и нескольких каталогов:
MyCli/
├── Program.cs
├── Commands/
│ ├── ScanCommand.cs
│ ├── HistoryCommand.cs
│ └── IgnoreCommand.cs
├── Services/
│ ├── CodeScanner.cs
│ └── HistoryService.cs
├── Models/
│ └── ScanResult.cs
└── Infrastructure/
└── FileHistoryStore.cs
Program.cs остаётся точкой входа: здесь собираются зависимости, регистрируются команды и запускается приложение.
В Commands находится всё, что связано с интерфейсом командной строки. В Services — операции приложения, а в Infrastructure — взаимодействие с внешними ресурсами.
Это не обязательная структура и уж точно не стандарт, которому нужно следовать буквально. Например, если команда достаточно сложная, удобнее хранить её обработчик, параметры и связанные классы рядом, в отдельном каталоге по функциональности. Именно поэтому я не сторонник создания десятка каталогов заранее. Структура должна отражать реальное устройство приложения, а не список архитектурных терминов.
А нужен ли Dependency Injection?#
Мы привыкли использовать Dependency Injection в ASP.NET Core, поэтому возникает соблазн перенести тот же подход в любую консольную программу. Но здесь всё зависит от сложности.
Если приложение состоит из двух команд и одного сервиса, вполне можно создать объекты вручную:
var scanner = new CodeScanner();
var handler = new ScanCommandHandler(
scanner,
Console.Out);
Это уже внедрение зависимостей через конструктор, просто без специального контейнера. Когда появляются десятки обработчиков, общие сервисы, конфигурация, логирование и зависимости с разным временем жизни, можно подключить Microsoft.Extensions.DependencyInjection или использовать Generic Host.
Важный момент:
**Dependency Injection**— это принцип передачи зависимостей, а контейнер DI — всего лишь инструмент для его реализации. Не стоит усложнять приложение контейнером исключительно потому, что он используется в других проектах. Но и отказываться от него из принципа, когда зависимости становятся трудноуправляемыми, тоже не нужно.
Ошибки, вывод и коды завершения#
Есть ещё один момент, который часто упускают при проектировании CLI. Приложение должно быть понятно не только человеку, который его запускает, но и другому приложению или скрипту. Для этого полезно заранее договориться о нескольких правилах. Обычный результат команды отправляем в stdout, а сообщения об ошибках — в stderr. Успешное выполнение обозначаем кодом 0, ошибки — ненулевыми кодами завершения.
Например:
try
{
return handler.Execute(path);
}
catch (DirectoryNotFoundException)
{
Console.Error.WriteLine(
$"Каталог не найден: {path}");
return 2;
}
catch (UnauthorizedAccessException)
{
Console.Error.WriteLine(
"Недостаточно прав для чтения каталога.");
return 3;
}
Это пример обработки ошибок на границе приложения. Не нужно окружать каждый метод собственным try/catch, особенно если он не может ничего полезного сделать с исключением.
Во времена, когда я был куратором на потоковых курсах, я намеренно обращал внимание учеников на обработку исключений во всех местах, где потенциально оно могло появиться. Там, в web-приложениях, считаю такой подход оправданным? т.к. разбор ошибок происходит путем просмотра логов и зачастую самими же разработчиками.
И, конечно, не следует автоматически считать любую ошибку поводом вывести огромный stack trace. Для обычного пользователя понятное сообщение гораздо полезнее, а технические подробности можно показывать в диагностическом режиме. Коды завершения тоже лучше определить заранее и использовать последовательно. Но не нужно придумывать сотню уникальных кодов на все возможные случаи.
Проектируем для расширения#
Допустим, завтра мы захотим добавить к нашей утилите вывод результата в JSON. Если подсчёт строк находится внутри обработчика, который сразу рисует таблицу в консоли, придётся переписывать существующую реализацию.
А если операция возвращает ScanResult, задача становится гораздо проще:
var result = scanner.Scan(path);
if (format == "json")
{
Console.WriteLine(
JsonSerializer.Serialize(result));
}
else
{
Console.WriteLine(
$"Файлов: {result.Files}, строк: {result.Lines}");
}
Это тоже упрощённый пример: в полноценном приложении для JSON может потребоваться заранее подготовленный JsonSerializerContext, особенно при использовании Native AOT. Но сама идея важнее конкретной реализации. Полезная работа приложения не должна зависеть от того, в каком виде мы показываем её результат. Точно так же можно добавить сохранение в файл, отправку данных по сети или другой интерфейс взаимодействия, не переписывая сканирование.
И здесь мы подходим к ещё одному преимуществу: такую логику гораздо проще тестировать. Вместо запуска всей программы можно отдельно проверить сервис на заранее подготовленном наборе файлов. А корректность аргументов и вывода проверить уже на уровне CLI.
Об этом мы подробнее поговорим в следующей части.
Не усложняйте раньше времени#
Под конец хочу отдельно подчеркнуть одну мысль: хорошая архитектура не обязательно должна быть сложной.
Ещё одна отсылочка к кураторскому прошлому, да не дадут соврать ученики, как часто я говорил "не усложняй!" ))
Иногда встречаются небольшие утилиты, в которых для выполнения одной операции созданы интерфейс, сервис, фабрика, репозиторий, несколько DTO и отдельный проект с абстракциями. Формально всё выглядит солидно, но разобраться в таком коде оказывается сложнее, чем в исходной задаче. Сформулирую так: вводите абстракции тогда, когда они решают конкретную проблему.
Нужно переиспользовать логику — отделите её от команды. Появилось несколько способов хранения данных — подумайте об интерфейсе хранилища. Стало сложно создавать и связывать зависимости — подключите DI-контейнер. Не нужно делать всё это заранее на случай, если когда-нибудь приложение превратится в огромную систему.
Итого#
Мы начали серию с небольших консольных примеров, и для них одного Program.cs вполне хватало. Но по мере развития приложения становится важно не только то, что оно умеет делать, но и насколько удобно его изменять.
На мой взгляд, основа поддерживаемого CLI довольно проста: отделяем обработку команд от полезной работы, не смешиваем бизнес-логику с форматированием вывода, последовательно обрабатываем ошибки и не создаём лишних абстракций.
И всё это практически не зависит от выбора библиотеки. Можно использовать System.CommandLine, Spectre.Console.Cli или собственный обработчик аргументов — основные архитектурные принципы останутся прежними.
А в следующей части перейдём к тестированию. Посмотрим, как проверять отдельные команды, вывод, коды завершения и поведение настоящего исполняемого файла, чтобы очередное изменение не ломало уже работающие возможности.