Skip to main content

Основы и ядро (Core)

Ядро JT-LIB представляет собой фундаментальные компоненты, на которых построена вся библиотека. Эти компоненты обеспечивают базовую функциональность для всех остальных частей системы.

BaseObject - Базовый класс для всех объектов​

BaseObject является корневым классом для всех объектов в JT-LIB. Он предоставляет базовую функциональность для управления жизненным циклом объектов.

Основные возможности​

  • Уникальная идентификация - каждый объект получает уникальный ID
  • Управление жизненным циклом - создание, уничтожение, восстановление
  • Система дочерних объектов - иерархическая структура объектов
  • Обработка ошибок - встроенная система логирования ошибок
  • Подписка на события - автоматическая отписка при уничтожении

Ключевые методы​

  • id: string - уникальный идентификатор объекта
  • addChild(child: BaseObject): void - добавление дочернего объекта для корректного управления жизненным циклом
  • async call(functionName: string, data?: any): Promise<any> - вызов метода по имени
  • destroy(): void - корректное уничтожение объекта и всех дочерних
  • error(msg: string | Error, context?: any): void - обработка ошибок с контекстом

Система управления жизненным циклом​

BaseObject автоматически регистрируется в глобальном хранилище globals при создании. Это обеспечивает централизованное управление всеми объектами в системе.

Важно понимать: В TypeScript нельзя просто "уничтожить" объект - у него остаются активные подписки на события, которые могут вызывать ошибки. Поэтому для корректного завершения работы объекта необходимо вызывать метод destroy().

Функция addChild() служит для того, чтобы при уничтожении родительского объекта корректно отписывались от всех подписок все дочерние объекты. Это предотвращает утечки памяти и некорректное поведение системы.

Globals - Глобальное состояние системы​

Globals управляет глобальным состоянием приложения и предоставляет доступ ко всем основным сервисам.

Основные сервисы​

  • Script - текущий торговый скрипт (ранее Strategy)
  • Events - система событий (EventEmitter)
  • Triggers - сервис триггеров с автоматическим хранением
  • Report - система отчетности
  • Storage - хранение данных
  • CandlesBufferService - управление свечными данными
  • Indicators - технические индикаторы

Ключевые свойства​

  • script: BaseScript - текущий торговый скрипт (ранее strategy)
  • events: EventEmitter - система событий
  • triggers: TriggerService - сервис триггеров с автоматическим хранением
  • report: Report - система отчетности
  • storage: Storage - хранение данных
  • candlesBufferService: CandlesBufferService - управление свечными данными
  • indicators: Indicators - технические индикаторы
  • isTradeAllowed: boolean - разрешение на торговые операции
  • _objects: Record<string, BaseObject> - глобальное хранилище всех объектов
  • userData: Map<string, any> - пользовательские данные
  • IS_NO_LOGS: number - управление логированием
  • isDebug: boolean - режим отладки

Централизованное управление объектами​

Globals обеспечивает централизованное управление всеми объектами в системе. При создании любого объекта, наследующего от BaseObject, он автоматически регистрируется в globals._objects с уникальным идентификатором.

Это позволяет системе отслеживать все активные объекты, управлять их жизненным циклом и обеспечивать корректное освобождение ресурсов при завершении работы.

Base - Утилиты для работы с аргументами​

Base предоставляет набор утилитарных функций для работы с глобальной переменной ARGS, которая содержит параметры, передаваемые при запуске скрипта из JT-Trader.

Важно понимать: Все функции getArg* работают с глобальной переменной ARGS, которая автоматически заполняется параметрами, указанными пользователем в интерфейсе JT-Trader при запуске торговой стратегии.

Основные функции​

uniqueId()​

Генерирует уникальный идентификатор заданной длины. По умолчанию создает ID длиной 4 символа, но можно указать произвольную длину.

getArgNumber()​

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

getArgString()​

Безопасно извлекает строковый аргумент из глобальной переменной ARGS. Обеспечивает корректную обработку строковых значений с поддержкой обязательных аргументов. Если обязательный аргумент не найден, функция выбросит ошибку с указанием названия параметра.

getArgBoolean()​

Безопасно извлекает булевый аргумент из глобальной переменной ARGS. Поддерживает как булевые, так и строковые значения ('true'/'false'). Автоматически конвертирует строки в соответствующие булевые значения. Если обязательный аргумент не найден, функция выбросит ошибку.

isIterable()​

Проверяет, является ли объект итерируемым. Распознает массивы, Map, Set и другие итерируемые структуры данных.

Как работает система ARGS в JT-Trader​

При запуске торговой стратегии в JT-Trader создается глобальная переменная ARGS, которая содержит все параметры, переданные при запуске. Система поддерживает два режима:

Режим Runtime (торговля в реальном времени):

ARGS = {
  connectionName: 'Binance',
  symbols: 'BTC/USDT,ETH/USDT',
  amount: 0.001,
  stopLoss: 45000,
  takeProfit: 55000,
  isDebug: true
}

Режим Tester (тестирование на исторических данных):

ARGS = {
  connectionName: 'Binance',
  symbols: 'BTC/USDT,ETH/USDT',
  symbol: 'BTC/USDT',
  // Параметры тестера
  start: '2021-01',
  end: '2021-12',
  startDate: new Date('2021-01-01T00:00:00.000Z'),
  endDate: new Date('2021-12-31T23:59:59.999Z'),
  timeframe: '1h',
  optimizerIteration: 1,
  makerFee: 0.001,
  takerFee: 0.001,
  marketOrderSpread: 0.0001,
  balance: 10000,
  leverage: 1,
  // Пользовательские параметры
  amount: 0.001,
  stopLoss: 45000,
  takeProfit: 55000,
  isDebug: true
}

Использование в стратегии:

const symbol = getArgString('symbol', 'ETH/USDT');        // 'BTC/USDT'
const amount = getArgNumber('amount', 0.001, true);      // 0.001 (обязательный)
const stopLoss = getArgNumber('stopLoss', 0);            // 45000
const isDebug = getArgBoolean('isDebug', false);         // true

Storage - Система хранения данных​

Storage обеспечивает персистентное хранение объектов и их состояния между запусками стратегии.

Основные возможности​

  • Кэширование объектов - хранение ссылок на объекты
  • Сохранение состояния - автоматическое сохранение свойств объектов
  • Восстановление состояния - восстановление объектов при перезапуске
  • Поддержка сложных типов - Array, Date, Map, Set, RegExp
  • Отладка - детальное логирование операций

Ключевые методы​

  • addObject(key: string, obj: BaseObject | object, props?: string[]): void - добавление объекта для отслеживания с указанием свойств для сохранения
  • removeObject(key: string): void - удаление объекта из системы отслеживания
  • saveState(): Promise<void> - сохранение состояния всех отслеживаемых объектов
  • loadState(): Promise<void> - загрузка сохраненного состояния
  • reStoreState(key: string, obj: object): void - восстановление состояния конкретного объекта

Поддерживаемые типы данных​

Storage автоматически обрабатывает и сохраняет следующие типы данных:

  • Array - массивы
  • Date - даты и время
  • Map - Map объекты
  • Set - Set объекты
  • Object - обычные объекты
  • RegExp - регулярные выражения

Автоматическое управление состоянием​

При добавлении объекта в Storage система автоматически отслеживает изменения в указанных свойствах и сохраняет их состояние. При перезапуске стратегии все объекты восстанавливаются с сохраненными значениями.

Log - Система логирования и отладки​

Log предоставляет комплексную систему логирования для отладки и мониторинга работы стратегий.

Система событий в логах​

Критически важная особенность: Каждая функция логирования принимает параметр event - это название события или компонента, откуда вызывается лог. Это позволяет в сложных системах с множеством объектов легко идентифицировать источник каждого сообщения.

Почему это важно:

  • В торговых роботах одновременно работает множество объектов (стратегии, индикаторы, триггеры, ордера)
  • Без системы событий невозможно понять, откуда пришло конкретное сообщение
  • При отладке можно быстро найти все логи от конкретного компонента
  • Упрощает анализ работы системы в реальном времени

Формат логов:

2024-01-15 10:30:45| StrategyManager | Запуск новой стратегии BTC/USDT
2024-01-15 10:30:46| OrderManager | Создан ордер на покупку 0.001 BTC
2024-01-15 10:30:47| TriggerService | Активирован триггер stopLoss
2024-01-15 10:30:48| IndicatorService | Обновлен RSI: 65.4

Уровни логирования​

log()​

Основной уровень логирования для информационных сообщений. Используется для записи важных событий в работе стратегии.

Синтаксис: log(event: string, msg: string, context?: object, showInConsole?: boolean)

trace()​

Детальное логирование для отладки. Предоставляет подробную информацию о выполнении операций.

Синтаксис: trace(event: string, msg: string, context?: object, showInConsole?: boolean)

warning()​

Предупреждения, которые не останавливают выполнение стратегии, но требуют внимания разработчика.

Синтаксис: warning(event: string, msg: string, context?: object, showInConsole?: boolean)

error()​

Ошибки с детальным контекстом и стеком вызовов. Автоматически увеличивает счетчик ошибок и может привести к остановке стратегии.

Синтаксис: error(event: string, msg: string, context?: any) или error(error: Error, context?: any)

debug()​

Отладочная информация, доступная только в debug режиме. В тестере отключается для повышения производительности.

Синтаксис: debug(event: string, msg: string, context?: object)

Специальные функции логирования​

logOnce()​

Записывает сообщение только один раз за определенный период времени. Полезно для избежания спама в логах от повторяющихся событий.

Синтаксис: logOnce(event: string, msg: string, context?: object, ttl?: number)

errorOnce()​

Записывает ошибку только один раз за определенный период времени. Предотвращает засорение логов повторяющимися ошибками.

Синтаксис: errorOnce(event: string, msg: string, context?: object, ttl?: number)

warningOnce()​

Записывает предупреждение только один раз за определенный период времени.

Синтаксис: warningOnce(event: string, msg: string, context?: object, ttl?: number)

Примеры использования:

// Предотвратить спам от повторяющихся предупреждений
warningOnce('ConnectionManager', 'Медленное соединение с биржей', { 
  latency: 5000 
}, 60000); // Показать только раз в минуту

// Логировать ошибку подключения только раз в час
errorOnce('ExchangeAPI', 'Ошибка авторизации', { 
  error: 'Invalid API key' 
}, 3600000); // TTL = 1 час

Практические примеры использования событий​

В торговой стратегии:

// В классе стратегии
log('Strategy', 'Инициализация стратегии BTC/USDT', { symbol: 'BTC/USDT', timeframe: '1h' });
log('Strategy', 'Анализ тренда завершен', { trend: 'bullish', confidence: 0.85 });

// В классе управления ордерами
log('OrderManager', 'Создан ордер на покупку', { 
  symbol: 'BTC/USDT', 
  amount: 0.001, 
  price: 45000 
});

// В классе индикаторов
log('RSI', 'RSI пересек уровень 70', { 
  value: 72.5, 
  level: 70, 
  signal: 'overbought' 
});

// В системе триггеров
log('TriggerService', 'Активирован триггер stopLoss', { 
  orderId: '12345', 
  triggerPrice: 44000 
});

Фильтрация логов по событиям:

// Получить все логи от конкретного компонента
const strategyLogs = getLogs('log').filter(log => log.event === 'Strategy');
const orderLogs = getLogs('log').filter(log => log.event === 'OrderManager');

// Найти все ошибки от индикаторов
const indicatorErrors = getLogs('error').filter(log => log.event.includes('Indicator'));

Структура логов и их получение​

Структура записи лога:

{
  date: string,        // Время записи в формате "YYYY-MM-DD HH:mm:ss"
  event: string,       // Название события/компонента
  msg: string,         // Текст сообщения
  context: string | object  // Контекст (JSON строка или объект)
}

Получение логов:

// Получить все логи определенного типа
const allLogs = getLogs('log');        // Информационные сообщения
const allErrors = getLogs('error');    // Ошибки
const allWarnings = getLogs('warning'); // Предупреждения
const allDebug = getLogs('debug');     // Отладочная информация

// Получить логи "один раз"
const logOnceMessages = getLogs('logOnce');

Ограничения системы:

  • Максимум 200 сообщений каждого типа в памяти
  • В тестере максимум 200 вызовов функций логирования с showInConsole = true
  • Автоматическая очистка старых сообщений при превышении лимитов

⚠️ Важно: Использование console.log​

В JT-LIB НЕ рекомендуется использовать console.log! Вместо этого используйте специализированные функции логирования:

  • log() - для информационных сообщений
  • trace() - для детального логирования
  • warning() - для предупреждений
  • error() - для ошибок
  • debug() - для отладочной информации

Преимущества функций JT-LIB:

  • Структурированное логирование с контекстом
  • Автоматическое управление выводом
  • Интеграция с системой отчетов
  • Контроль производительности

Куда выводятся логи​

Система логирования работает в двух режимах в зависимости от параметра showInConsole:

Режим 1: Логи в консоль (showInConsole = true)​

Когда логи выводятся в консоль, они попадают в несколько мест:

В Runtime (торговля в реальном времени):

  • Консоль браузера - все логи отображаются в консоли разработчика
  • Вкладка Runtime - логи отображаются в интерфейсе JT-Trader на вкладке "Runtime"
  • Файл на сервере - все логи автоматически сохраняются в файл на сервере для последующего анализа

В Tester (тестирование на исторических данных):

  • Консоль тестера - логи отображаются в консоли тестера
  • Отчет тестера - логи включаются в итоговый отчет о тестировании
  • Файл результатов - сохраняются вместе с результатами тестирования

Режим 2: Логи в памяти (showInConsole = false)​

Когда логи НЕ выводятся в консоль, они сохраняются только в памяти:

Хранение в памяти:

  • globals.logs - все логи сохраняются в глобальном объекте globals.logs
  • Доступ через getLogs() - можно получить программно через функцию getLogs()
  • Отчет стратегии - логи включаются в итоговый отчет стратегии

Важно понимать:

  • Логи в памяти доступны только во время работы стратегии
  • При перезапуске стратегии логи в памяти теряются
  • Для постоянного хранения нужно использовать режим с консолью

Автоматический вывод в консоль​

Некоторые типы логов всегда выводятся в консоль независимо от параметра:

  • error() - все ошибки всегда попадают в консоль
  • warning() - предупреждения всегда показываются в консоли

Практические рекомендации​

Для отладки в реальном времени:

// Логи будут видны в консоли и на вкладке Runtime
log('Strategy', 'Важное событие', { data: 'value' }, true);
trace('OrderManager', 'Детальная информация', { orderId: '123' }, true);

Для сбора данных в отчет:

// Логи сохранятся в памяти и попадут в отчет
log('Strategy', 'Статистика работы', { trades: 5, profit: 100 });
debug('IndicatorService', 'Расчет индикатора', { rsi: 65.4 });

Смешанный подход:

// Критичные события - в консоль
error('ConnectionManager', 'Ошибка подключения', { error: 'timeout' }); // всегда в консоль

// Обычная информация - в память для отчета
log('Strategy', 'Ежедневная статистика', { date: '2024-01-15', profit: 50 });

Доступ к логам в разных режимах​

В Runtime (торговля в реальном времени):

// Просмотр логов в консоли браузера
// 1. Откройте Developer Tools (F12)
// 2. Перейдите на вкладку Console
// 3. Все логи с showInConsole=true будут видны в реальном времени

// Просмотр логов в интерфейсе JT-Trader
// 1. Откройте вкладку "Runtime" в JT-Trader
// 2. Логи отображаются в специальном окне логов
// 3. Можно фильтровать по типу и событию

// Программный доступ к логам в памяти
const allLogs = getLogs('log');
const errors = getLogs('error');
const strategyLogs = getLogs('log').filter(log => log.event === 'Strategy');

В Tester (тестирование на исторических данных):

// Логи в консоли тестера
// - Отображаются в окне тестера во время выполнения
// - Сохраняются в файл результатов тестирования

// Логи в отчете тестера
// - Включаются в итоговый HTML/PDF отчет
// - Группируются по типам и событиям
// - Доступны для анализа после завершения тестирования

// Программный доступ (только во время выполнения)
const testLogs = getLogs('log');
const testErrors = getLogs('error');

Файлы логов на сервере:

  • Логи с showInConsole=true автоматически сохраняются в файлы
  • Расположение файлов зависит от конфигурации JT-Trader
  • Обычно находятся в папке logs/ или runtime/
  • Именуются по дате и времени запуска стратегии

Настройки логирования​

  • ARGS.isNoLogs = 1 - полное отключение логирования
  • ARGS.isDebug = true - включение debug режима
  • ARGS.isDebugStorage = true - детальное логирование операций storage

Обработка ошибок​

JT-LIB предоставляет мощную систему обработки ошибок, построенную вокруг класса BaseError. Эта система обеспечивает детальную диагностику, автоматическое логирование и интеграцию с компонентами библиотеки.

Основные возможности:

  • BaseError - расширенный класс ошибок с уникальной идентификацией
  • Автоматическая интеграция с BaseObject и системой логирования
  • Множественный контекст - накопление информации о состоянии системы
  • Отладочная поддержка - детальная информация в debug режиме

Подробная документация: Обработка ошибок (Error Handling)

Краткая сводка по выводу логов​

ПараметрRuntimeTesterФайл сервераПамятьОтчет
showInConsole = true✅ Консоль + Runtime✅ Консоль + Отчет✅ Да✅ Да✅ Да
showInConsole = false❌ Нет❌ Нет❌ Нет✅ Да✅ Да
error()✅ Всегда✅ Всегда✅ Всегда✅ Да✅ Да
warning()✅ Всегда✅ Всегда✅ Всегда✅ Да✅ Да

Рекомендации:

  • Для отладки - используйте showInConsole = true
  • Для сбора статистики - используйте showInConsole = false
  • Критичные события - используйте error() и warning() (всегда в консоль)
  • Обычная информация - используйте log() без консоли для отчетов

Автоматическое управление ошибками​

Система автоматически отслеживает количество ошибок и может остановить стратегию при превышении лимитов:

  • В тестере: остановка после 20 ошибок
  • В реальном времени: остановка после 10 ошибок
  • Автоматический сброс: счетчик ошибок сбрасывается каждый час

Архитектурные улучшения​

  • Упрощение доступа к скрипту - более интуитивный API через globals.script
  • Улучшенная персистентность - триггеры сохраняют свое состояние между запусками
  • Оптимизация производительности - уменьшено количество ненужных операций

Взаимодействие компонентов​

Все компоненты ядра тесно связаны между собой и образуют единую экосистему:

BaseObject использует globals для автоматической регистрации в глобальном хранилище. Это обеспечивает централизованное управление всеми объектами.

Storage наследуется от BaseObject, получая все возможности по управлению жизненным циклом и автоматической регистрации в системе.

Log использует globals для управления настройками логирования и доступа к глобальным параметрам.

Base предоставляет утилиты для всех компонентов, обеспечивая единообразную работу с аргументами и базовыми операциями.

Такая архитектура обеспечивает надежное управление ресурсами, предотвращает утечки памяти и гарантирует корректное завершение работы всех компонентов системы.