Перейти к основному содержимому

Чтение потока

ORDERS хранит опубликованные заказы. Пока вы видели лишь их количество через nats stream info, но не содержимое.

Прочитаем их сервисом billing Acme. Он обрабатывает каждый заказ: выставляет платёж при создании, списывает при отправке, возвращает при отмене. После первого запуска или простоя ему нужно пройти весь журнал без пропусков. Для этого создадим долговременного потребителя с номера 1. Сначала разберём три составляющие пути сообщения.

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

Издатель, поток и потребитель​

Сообщение проходит три составляющие:

  • Издатель публикует в тему, читает PubAck, повторяет при ошибке.
  • Поток хранит по порядку, назначая номер в потоке — позицию сообщения.
  • Потребитель — серверный курсор потока. Клиент подключается к нему для получения сообщений. Потребитель отслеживает продвижение и выдаёт следующее. Его номер доставки увеличивается при каждой выдаче, включая повторную, поэтому считает доставки, а не уникальные сообщения.

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

Потоки сохраняют сообщения​

В Core NATS сообщение живёт лишь до доставки текущим подписчикам. Почему этого мало заказам, разобрано в Зачем нужен поток.

Поток сохраняет сообщения как долговременные записи с неизменными номерами. Чтение не перемещает и не удаляет запись: сообщение 1 остаётся следующим читателям. Новый потребитель через месяц может начать с того же номера 1.

Потребитель — серверный объект​

Для чтения создаётся потребитель. Он расположен на сервере рядом с потоком; приложение является клиентом. Данные и позиция остаются на сервере, поэтому клиент отключается и возвращается без потери места и собственного учёта номеров.

Создайте billing:

#!/bin/bash

# Create a named, durable consumer on the ORDERS stream.
# A durable consumer has a name you choose. The server keeps its position on
# disk under that name, so a reader resumes where it left off after a
# disconnect or a server restart instead of starting over.
# --deliver all start at the first message in the stream (sequence 1)
# --pull the reader asks for messages when it's ready
# --ack explicit acknowledge each message; the position advances only once
# a message is acked (the default for a pull consumer)
nats consumer add ORDERS billing \
--deliver all \
--pull \
--ack explicit \
--defaults

Три настройки определяют чтение:

  • Deliver all — начать с первого сообщения, номера 1, и прочитать журнал.
  • Pull — клиент запрашивает сообщения по готовности. Это стандарт для новых потребителей; существует и прежняя push-модель, но здесь используется pull.
  • Ack explicit — подтверждать каждое обработанное сообщение. Позиция подтверждения продвигается по ack. Это стандарт для pull. Здесь успешный путь; далее рассмотрен цикл повторной доставки.

Посмотрите потребителя до чтения:

nats consumer info ORDERS billing
State:

Last Delivered Message: Consumer sequence: 0 Stream sequence: 0
Acknowledgment Floor: Consumer sequence: 0 Stream sequence: 0
Outstanding Acks: 0 out of maximum 1,000
Redelivered Messages: 0
Unprocessed Messages: 3
Waiting Pulls: 0 of maximum 512

Unprocessed Messages — число ещё не доставленных записей, сейчас весь поток. Оно соответствует вашим публикациям. Поля подтверждений остаются нулевыми до начала доставки и обработки.

Прочитайте сохранённые сообщения​

Привязка к существующему потребителю использует его позицию, доставляет оставшееся и подтверждает по мере чтения:

#!/bin/bash

# Read every message the stream currently holds, in order, then stop.
# Binding 'nats sub' to the durable consumer reuses its on-disk position.
# --stream ORDERS --durable billing bind to the durable consumer
# --terminate-at-end stop once all stored messages are read
# --ack acknowledge each message it delivers
#
# This makes no assumption about how many messages are stored: it reads
# whatever is there and stops when 'pending' reaches 0.
nats sub --stream ORDERS --durable billing --terminate-at-end --ack

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

[#1] Received JetStream message: stream: ORDERS seq: 1 / pending: 2 / subject: orders.created / time: 2026-05-22 10:14:22
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}

[#2] Received JetStream message: stream: ORDERS seq: 2 / pending: 1 / subject: orders.created / time: 2026-05-22 10:14:25
{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}

[#3] Received JetStream message: stream: ORDERS seq: 3 / pending: 0 / subject: orders.shipped / time: 2026-05-22 10:14:31
{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}

pending уменьшается на единицу при каждой доставке; чтение прекращается при 0 независимо от размера потока. seq: 1, 2, 3 — те же номера из nats stream info. Это последовательное чтение журнала добавления.

Номер сообщения и номер доставки​

Повторно запросите догнавшего потребителя:

nats consumer info ORDERS billing
State:

Last Delivered Message: Consumer sequence: 3 Stream sequence: 3
Acknowledgment Floor: Consumer sequence: 3 Stream sequence: 3
Unprocessed Messages: 0

Last Delivered Message содержит рядом два номера:

  • Номер в потоке — неизменная позиция, назначенная при публикации; тот же номер в PubAck и nats stream info.
  • Номер доставки потребителя — его собственный счётчик выдач, включая повторы, а не уникальных сообщений.

Оба равны 3, поскольку billing читал с начала без пропусков. При старте с середины, фильтрации или повторной доставке они расходятся. Номер потока закреплён за сообщением, счётчик потребителя — за доставкой.

В обработчике обычно не нужен отдельный nats consumer info: метаданные каждого сообщения уже содержат оба номера, остаток и число доставок. Они приходят бесплатно с сообщением; отдельный запрос годится для разовой проверки, но дорог на каждом сообщении. Пример выше читает номера прямо из доставки.

Потребитель помнит остановку​

Позиция сохранена на диске. Опубликуйте ещё заказ:

nats pub --jetstream orders.created \
'{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}'

Повторите чтение той же командой: придёт только новое сообщение.

[#1] Received JetStream message: stream: ORDERS seq: 4 / pending: 0 / subject: orders.created / time: 2026-05-22 11:02:00
{"order_id":"ord_5xk1","customer":"initech","total_cents":1500,"ts":"2026-05-22T11:02:00Z"}

Отключение или перезапуск сервера не изменит позицию, привязанную к имени billing. Безымянный читатель такой долговременной позиции не имеет.

Однократное чтение без именованного потребителя​

Долговременный потребитель нужен возвращающемуся читателю. Для разового просмотра nats sub --all переключается с живой Core-подписки на чтение потока. CLI создаёт временного потребителя, читает накопленное и удаляет его при выходе:

#!/bin/bash

# Replay every message stored in the ORDERS stream, from sequence 1.
# 'nats sub' against a stream-bound subject uses an ephemeral consumer
# with no ack by default.
# --all start at the beginning of the stream
# --terminate-at-end stop once all stored messages have been read
nats sub "orders.>" --all --terminate-at-end

К временному потребителю нельзя надёжно вернуться: после бездействия он удаляется, а новое подключение начинает сначала. Для возобновляемой работы используйте долговременный вариант. Специальная форма однократного чтения в библиотеках рассмотрена в Упорядоченных потребителях.

Поток не изменился​

nats stream info ORDERS показывает прежнее количество и номера плюс новый заказ. Чтение не забирает элементы из очереди: данные остаются другим читателям.

Типичные ошибки​

При первом чтении реальных данных учтите несколько особенностей.

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

Чтение огромной истории с начала. Deliver all проходит весь журнал. Для миллионов заказов это время и трафик. Если история не нужна, выбирайте старт: последнее (--deliver last), час назад (--deliver 1h) или номер (--deliver 1000). Все варианты — в Создании потребителя.

Политика доставки задаёт начало, а политика воспроизведения — скорость. Стандартная instant отдаёт максимально быстро. original сохраняет промежутки исходных временных меток, воспроизводя реальную скорость. Здесь используется instant; обе описаны в справочнике.

Повторное имя с другой конфигурацией. Имя определяет долговременного потребителя. Повторное создание billing с другими настройками возвращает consumer already exists, не меняя работающего читателя. Используйте nats consumer edit или новое имя.

Что уже готово​

Чтение не изменило ORDERS. Теперь есть:

  • Поток ORDERS с orders.> и опубликованными сообщениями.
  • Долговременный billing с серверной позицией.
  • Различие номера сообщения в потоке и счётчика доставок потребителя.

Что дальше​

Добавим второго потребителя с фильтром: несколько независимых представлений одного потока, каждое со своей позицией.

См. также​