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, поддержку нескольких языков, историю сканирований и команду сравнения результатов. А затем захотим использовать тот же механизм подсчёта строк из другого приложения.

Вот здесь уже появляется причина задуматься о структуре.

Разделяем ответственность#

Разобьём приложение на три основные части:

  1. CLI-слой — принимает команды и аргументы, проверяет ввод, сообщает пользователю о результатах и ошибках.

  2. Логика приложения — выполняет полезную работу: сканирует файлы, считает строки, сравнивает результаты.

  3. Инфраструктура — взаимодействует с файловой системой, базой данных, сетью и другими внешними ресурсами.

Главное здесь не количество проектов или каталогов, а разделение ответственности. Например, обработчик команды 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 или собственный обработчик аргументов — основные архитектурные принципы останутся прежними.

А в следующей части перейдём к тестированию. Посмотрим, как проверять отдельные команды, вывод, коды завершения и поведение настоящего исполняемого файла, чтобы очередное изменение не ломало уже работающие возможности.