​

Лучшие практики Ziva

​

Архитектура и организация кода

• Выносите создание задач в фабрики или методы слоёв, чтобы очереди оставались читаемыми.
• Группируйте задачи по этапам и используйте отдельные очереди для каждого этапа (сбор данных → проверка → применение). Это упрощает тестирование и повторное использование.
• Сохраняйте ссылки на задачи, чьи значения понадобятся позже. После queue.Run() они продолжают хранить состояние.
• Вызывайте ziva.AutoConfigure() и настройку языка (SetDefaultLanguage, SetLanguage) в main(), прежде чем создавать очереди.

​

Работа с очередями

• Используйте WithTasksNumbered(true, "[%02d]") для длинных сценариев — пользователи быстрее ориентируются в списке.
• Отключайте итоговую сводку (WithOutSummary()), если протокол ведётся в отдельном лог-файле, и наоборот добавляйте WithSummaryFunction, когда нужно показать ключевые результаты.
• Не забывайте про WithTimeout*() в headless-средах (CI, SSH). Указывайте значение по умолчанию, безопасное для сценария.
• Для динамических сценариев создавайте отдельный Queue, формируйте список задач и запускайте его после основной очереди.

​

Валидация и ввод

• Описывайте требования через Description() — Ziva показывает подсказку под полем.
• Комбинируйте встроенные валидаторы фабрики DefaultValidators с собственными типами. Для сложных правил создавайте композиции и покрывайте их тестами.
• Если поле может быть пустым, используйте WithAllowEmpty(true) и валидатор, корректно обрабатывающий пустую строку (например, OptionalEmail).
• Для сетевых проверок (дубликаты в CRM, доступность сервиса) добавляйте FuncTask сразу после ввода и отображайте краткий итог.

​

Стили и локализация

• Настраивайте цвета ошибок через ziva.SetErrorColor, если бренд требует собственную палитру. После экспериментов вызывайте ResetErrorColors().
• На ограниченных терминалах объединяйте EnableEmbeddedMode() и EnableASCIIMode() — это гарантирует читаемый вывод.

​

Производительность и встроенные устройства

• Ограничивайте историю завершённых задач переменной окружения ZIVA_MAX_COMPLETED_TASKS.
• Следите за памятью через ZIVA_MEMORY_PRESSURE_THRESHOLD и периодически очищайте кэш строк ziva.ClearInternCache() в долго живущих CLI.
• Для больших списков используйте WithViewport(...) — так интерфейс не «прыгает» и остаётся отзывчивым.
• Разделяйте операции на небольшие FuncTask, чтобы прогресс отображался чаще и пользователь понимал, что происходит.

​

Тестирование и отладка

• Покрывайте фабрики задач unit-тестами: создавайте задачу, эмулируйте сообщения (Update) и проверяйте финальный результат.
• Поднимайте демонстрационные очереди в examples/ и запускайте их вручную — скриншоты и GIF можно получать через ziva.WithClearScreen(false).
• Логируйте ошибки вне Ziva (через log/zap), особенно когда очередь останавливается из-за WithStopOnError(true). Это ускоряет диагностику.

​

Контрольный список перед релизом

• Проверены все таймауты и значения по умолчанию.
• Задачи сгруппированы по этапам, вывод адаптирован под ширину терминала.
• Валидация покрывает негативные сценарии, сложные правила протестированы.
• Цвета и локализация соответствуют требованиям бренда/рынка.
• Встроенные устройства протестированы с AutoConfigure() и embedded-режимом.