Dart Stream

Stream — это механизм в Dart для обработки последовательностей непрерывных асинхронных событий.

Если Future — это одноразовый асинхронный результат, то Stream — это повторяющийся, непрерывный асинхронный поток данных.

В этой главе представлено понятие Stream, прослушивание с помощью await for, создание StreamController и различия между потоками с одной подпиской (single-subscription) и широковещательными (broadcast) потоками.


Stream-потоки и последовательности событий

Stream похож на конвейерную ленту; данные поступают по одному с течением времени.

Вам не нужно ждать все данные сразу; вместо этого вы обрабатываете каждый фрагмент по мере его поступления.

Типичные сценарии использования Stream-потоков:

СценарииПример
События пользовательского вводаНажатия кнопок, движение мыши, ввод с клавиатуры
Чтение файловЧтение больших файлов построчно
Сетевые данныеСообщения WebSocket, API в реальном времени
ТаймерСобытия таймера, срабатывающие раз в секунду
Изменения состоянияПотоки управления состоянием в Flutter.

Пример

Базовое использование Stream — прослушивание с помощью listen:

void main() {
  // Создать Stream: выдавать число каждую 1 секунду
  var stream = Stream<int>.periodic(
    Duration(seconds: 1),
    (count) => count + 1,  // count начинается с 0
  );

  print('Начинаем прослушивание Stream...');

  // listen подписывается на Stream
  var subscription = stream.listen(
    (data) {
      // Вызывается при поступлении новых данных
      print('ПРИМЕР полученные данные: $data');
    },
    onError: (error) {
      // Вызывается, когда Stream сталкивается с ошибкой
      print('Ошибка: $error');
    },
    onDone: () {
      // Вызывается, когда Stream закрывается
      print('Stream закрыт');
    },
  );

  // Отменить подписку через 5 секунд
  Future.delayed(Duration(seconds: 5), () {
    subscription.cancel();
    print('Подписка отменена');
  });
}
开始监听 Stream...
EXAMPLE 收到数据: 1
EXAMPLE 收到数据: 2
EXAMPLE 收到数据: 3
EXAMPLE 收到数据: 4
EXAMPLE 收到数据: 5
已取消订阅

listen() возвращает объект StreamSubscription, который можно использовать для управления подпиской:

МетодыФункция
subscription.pause()Приостановить получение данных
subscription.resume()Возобновить получение данных
subscription.cancel()Отменить подписку
subscription.isPausedНаходится ли она в приостановленном состоянии

Прослушивание с помощью await for

Помимо подхода с обратным вызовом listen(), можно также использовать цикл await for для обработки Stream.

await for делает логику обработки Stream такой же понятной, как обычный цикл for.

Пример

// Сгенерировать конечный поток данных
Stream<int> countStream(int max) async* {
  for (int i = 1; i <= max; i++) {
    await Future.delayed(Duration(milliseconds: 300));
    yield i;  // yield передаёт данные в Stream
  }
}

Future<void> main() async {
  print('Начать потребление Stream с помощью await for...');

  // await for: ожидать поступления каждого элемента данных и обрабатывать их по одному
  await for (var value in countStream(5)) {
    print('ПРИМЕР количество: $value');
  }

  print('Потребление Stream завершено');
}
开始用 await for 消费 Stream...
EXAMPLE 计数: 1
EXAMPLE 计数: 2
EXAMPLE 计数: 3
EXAMPLE 计数: 4
EXAMPLE 计数: 5
Stream 消费完毕

Характеристики await for:

  • Синтаксис похож на обычный цикл for, но каждая итерация ожидает поступления следующего элемента данных.
  • Когда Stream закрывается, цикл завершается автоматически.
  • Его можно использовать только в async-функциях.
  • Если нужно выйти досрочно, используйте break (так же, как в обычном цикле for).

await for подходит для сценариев, где нужно обрабатывать все данные последовательно, например чтение всех строк из файла. listen() подходит для сценариев, где нужно непрерывно реагировать на события, например на нажатия кнопок. Они могут заменять друг друга, но у каждого есть свои сильные стороны.


StreamController создаёт Stream

StreamController — это инструмент для ручного создания и управления Streams.

Вы можете добавлять данные, ошибки или закрыть его в любой момент.

Пример

import 'dart:async';

// Использование StreamController для реализации простого таймера обратного отсчёта
class CountdownTimer {
  final StreamController<int> _controller = StreamController<int>();
  Timer? _timer;
  int _remaining = 0;

  // Предоставить Stream для внешней подписки
  Stream<int> get tickStream => _controller.stream;

  // Начать обратный отсчёт
  void start(int seconds) {
    _remaining = seconds;

    // Немедленно отправить начальное значение
    _controller.add(_remaining);

    _timer = Timer.periodic(Duration(seconds: 1), (timer) {
      _remaining--;

      if (_remaining > 0) {
        _controller.add(_remaining);  // Отправить данные
      } else {
        _controller.add(0);           // Отправить финальный 0
        _controller.close();          // Закрыть поток
        timer.cancel();
      }
    });
  }

  // Отменить обратный отсчет
  void cancel() {
    _timer?.cancel();
    _controller.addError('Обратный отсчет отменен');  // Отправить ошибку
    _controller.close();
  }

  // Освободить ресурсы
  void dispose() {
    _controller.close();
  }
}

Future<void> main() async {
  var timer = CountdownTimer();

  // Подписаться на событие обратного отсчета
  timer.tickStream.listen(
    (remaining) {
      print('ПРИМЕР обратного отсчета: $remaining секунд');
    },
    onError: (error) {
      print('Ошибка: $error');
    },
    onDone: () {
      print('Обратный отсчет завершен!');
    },
  );

  timer.start(5);

  // Дождитесь завершения обратного отсчета
  await Future.delayed(Duration(seconds: 6));
  timer.dispose();
}
EXAMPLE 倒计时: 5 秒
EXAMPLE 倒计时: 4 秒
EXAMPLE 倒计时: 3 秒
EXAMPLE 倒计时: 2 秒
EXAMPLE 倒计时: 1 秒
EXAMPLE 倒计时: 0 秒
倒计时结束!

async* функции-генераторы

Если вам нужно просто сгенерировать последовательность данных, async* удобнее, чем StreamController.

Пример

// async* помечает это как асинхронную функцию-генератор
// Тип возвращаемого значения должен быть Stream
Stream<String> readLinesAsync() async* {
  var lines = ['Первая строка', 'Вторая строка', 'Третья строка', 'ПРИМЕР'];

  for (var line in lines) {
    await Future.delayed(Duration(milliseconds: 500));
    yield line;  // yield отправляет данные в Stream
  }
  // Stream автоматически закрывается, когда функция завершается
}

// Асинхронный генератор с обработкой ошибок
Stream<int> generateNumbersWithError() async* {
  for (int i = 1; i <= 5; i++) {
    await Future.delayed(Duration(milliseconds: 300));

    if (i == 3) {
      throw Exception('У числа 3 произошла ошибка!');
    }
    yield i;
  }
}

Future<void> main() async {
  print('Чтение построчно:');
  await for (var line in readLinesAsync()) {
    print(' $line');
  }

  print('\n'Генератор с ошибками:');
  try {
    await for (var num in generateNumbersWithError()) {
      print(' Число: $num');
    }
  } catch (e) {
    print(' Перехвачена ошибка: $e');
  }
}
逐行读取:
  第一行
  第二行
  第三行
  EXAMPLE

带错误的生成器:
  数字: 1
  数字: 2
  捕获错误: Exception: 数字 3 出错了!

Потоки с одной подпиской против широковещательных потоков

Потоки Dart делятся на два типа: потоки с одной подпиской и широковещательные потоки.

Поток с одной подпиской

Это тип Stream по умолчанию.

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

Пример

void main() {
  // Поток с одной подпиской (по умолчанию)
  var stream = Stream.fromIterable([1, 2, 3]);

  // Первая подписка: OK
  stream.listen((data) => print('Подписчик 1: $data'));

  // Вторая подписка: Ошибка! На поток с одной подпиской нельзя подписаться несколько раз
  // stream.listen((data) => print('Subscriber 2: $data')); // ошибка во время выполнения
}

Широковещательный поток

Широковещательные потоки позволяют нескольким слушателям подписываться одновременно, что подходит для сценариев широковещательной рассылки событий.

Пример

import 'dart:async';

void main() {
  // Создать широковещательный поток
  var controller = StreamController<int>.broadcast();

  // Несколько подписчиков могут слушать одновременно
  controller.stream.listen(
    (data) => print('EXAMPLE Subscriber A: received $data'),
  );

  controller.stream.listen(
    (data) => print('EXAMPLE Subscriber B: received $data'),
  );

  // Отправить данные, оба подписчика их получат
  controller.add(1);
  controller.add(2);
  controller.add(3);

  // Поздняя подписка всё ещё может получать последующие данные (но не предыдущие данные)
  Future.delayed(Duration(seconds: 1), () {
    controller.stream.listen(
      (data) => print('ПРИМЕР Late Subscriber C: получено $data'),
    );
    controller.add(4);
    controller.close();
  });
}
EXAMPLE 订阅者A: 收到 1
EXAMPLE 订阅者B: 收到 1
EXAMPLE 订阅者A: 收到 2
EXAMPLE 订阅者B: 收到 2
EXAMPLE 订阅者A: 收到 3
EXAMPLE 订阅者B: 收到 3
EXAMPLE 订阅者A: 收到 4
EXAMPLE 订阅者B: 收到 4
EXAMPLE 迟到的订阅者C: 收到 4

Сравнение двух типов Streams:

ОсобенностиStream с одной подпискойШироковещательный поток
Число подписчиковТолько одинMultiple
Воспроизведение данныхПотребление с началаПолучает данные только после подписки
Типичные сценарииЧтение файлов, HTTP-ответыНажатия кнопок, уведомления о статусе
Метод созданияStreamController()StreamController.broadcast()

«Поздний подписчик» широковещательного потока может получать события только после подписки; предыдущие события уже пропущены. Это самое важное различие в поведении между широковещательными потоками и потоками с одиночной подпиской.


Общие методы преобразования Stream

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

Пример

void main() async {
  var numbers = Stream.fromIterable([1, 2, 3, 4, 5, 6]);

  // map: преобразовать каждый элемент данных
  var doubled = numbers.map((n) => n * 2);
  print('Doubled:');
  await for (var n in doubled) {
    print('  $n');
  }

  // where: фильтровать данные
  var source = Stream.fromIterable([10, 15, 20, 25, 30]);
  var even = source.where((n) => n % 2 == 0);
  print('Чётное:');
  await for (var n in even) {
    print('  $n');
  }

  // take: взять только первые N элементов
  var infinite = Stream.periodic(
    Duration(milliseconds: 100),
    (i) => i + 1,
  );
  print('Взять только первые 3:');
  await for (var n in infinite.take(3)) {
    print(' ПРИМЕР: $n');
  }

  // skip: пропустить первые N элементов
  var data = Stream.fromIterable([1, 2, 3, 4, 5]);
  print('Пропустить первые 2:');
  await for (var n in data.skip(2)) {
    print('  $n');
  }

  // distinct: удалить дубликаты
  var duplicates = Stream.fromIterable([1, 2, 2, 3, 3, 3]);
  print('Distinct:');
  await for (var n in duplicates.distinct()) {
    print('  $n');
  }
}
翻倍:
  2
  4
  6
  8
  10
  12
偶数:
  10
  20
  30
只取前 3 个:
  EXAMPLE: 1
  EXAMPLE: 2
  EXAMPLE: 3
跳过前 2 个:
  3
  4
  5
去重:
  1
  2
  3
Другие расширения