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

Публикация

Поток ORDERS пуст. Заполним его. Публикация похожа на Core NATS, но сервер подтверждает сохранение сообщения. Разберём подтверждение PubAck и безопасные повторные попытки.

Публикация через CLI​

Обычный nats pub отправляет сообщение без ответа. Для подтверждения записи добавьте --jetstream:

nats pub --jetstream orders.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

Сервер добавляет сообщение в ORDERS, захватывающий orders.>, и отвечает в том же вызове:

Stored in Stream: ORDERS Sequence: 1

Это PubAck: имя потока и присвоенный порядковый номер. Номера начинаются с 1, только растут и не используются повторно.

Опубликуйте ещё два сообщения. Подтверждения получат номера 2 и 3:

nats pub --jetstream orders.created '{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}'
nats pub --jetstream orders.shipped '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}'

nats stream info ORDERS теперь показывает три сообщения:

State:

Messages: 3
Bytes: 404 B
First Sequence: 1 @ 2026-05-22 10:14:22
Last Sequence: 3 @ 2026-05-22 10:14:31
Active Consumers: 0
Number of Subjects: 2

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

Публикация через клиентскую библиотеку​

CLI печатает PubAck, а библиотека возвращает его объектом. Это основное значение, с которым работает код публикации JetStream. Далее рассмотрены его поля.

Те же три публикации через библиотеку:

// Publish three orders and read each PubAck, which confirms the stream that
// stored the message and the sequence it was assigned
const orders = [
{
subject: "orders.created",
data:
`{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`,
},
{
subject: "orders.created",
data:
`{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}`,
},
{
subject: "orders.shipped",
data:
`{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}`,
},
];

for (const order of orders) {
const pa = await js.publish(order.subject, order.data);
console.log(`Stored in ${pa.stream}, sequence ${pa.seq}`);
}

Во всех примерах два общих свойства:

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

Содержимое PubAck​

Три часто используемых поля:

  • stream — сохранивший поток; полезен в тестах и журналах.
  • sequence — порядковый номер сообщения, видимый и в nats stream info. Сохранив его с бизнес-записью, можно позже начать воспроизведение отсюда.
  • duplicate — false для нового, true для распознанного повтора; см. Предотвращение повторной записи.

Возможны дополнительные поля, например domain для нескольких арендаторов или листовых узлов. Полный список — в справочнике; обычно нужны три перечисленных.

Предыдущие примеры уже возвращают этот объект: остаётся прочитать поля.

Правило: только PubAck доказывает сохранение. Ошибка «нет отвечающих» для темы без потока означает отсутствие записи. Но сетевой тайм-аут означает отсутствие подтверждения: сообщение могло сохраниться, а ответ — потеряться. Повторите попытку или сообщите об ошибке; для безопасного повтора задайте Nats-Msg-Id, как показано ниже.

Сохранение и доставка​

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

В Core NATS доставка и завершение публикации почти совпадают. В JetStream:

  1. Издатель публикует; сервер сохраняет и возвращает PubAck.
  2. Позже — через минуты, часы или дни — клиент читает через потребителя.
  3. После обработки клиент подтверждает. Только тогда сообщение считается обработанным.

Здесь выполнен первый шаг, остальные рассматриваются далее.

Предотвращение повторной записи​

Тайм-аут может наступить после сохранения при потерянном ответе. Простой повтор создаст вторую копию. Заголовок Nats-Msg-Id позволяет серверу не сохранять тот же идентификатор повторно в пределах окна дедупликации, по умолчанию двух минут. Для подавленного повтора PubAck содержит duplicate: true.

В CLI используйте --header вместе с nats pub --jetstream:

nats pub --jetstream orders.created \
--header "Nats-Msg-Id:ord_8w2k-created" \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'

Выполните дважды. Первый вызов сохраняет сообщение и выводит Stored in Stream: ORDERS Sequence: …. Второй возвращает тот же номер с Duplicate: true, ничего не добавляя. Через библиотеку:

// Publish the same order twice with a stable msgID. Within the stream's
// duplicate window the server stores it once: the second PubAck reports the
// same sequence and `duplicate: true`
const data =
`{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`;

const first = await js.publish("orders.created", data, {
msgID: "ord_8w2k-created",
});
console.log(`First: sequence ${first.seq}, duplicate ${first.duplicate}`);

const second = await js.publish("orders.created", data, {
msgID: "ord_8w2k-created",
});
console.log(`Second: sequence ${second.seq}, duplicate ${second.duplicate}`);

Каждой повторяемой публикации задавайте стабильный Nats-Msg-Id, воспроизводимый издателем: номер заказа, запроса или хеш содержимого. Все заголовки описаны в Справочнике → Заголовки JetStream. Окно задаётся потоком, не заголовком: это Duplicate Window со страницы потока. Здесь нужен только Nats-Msg-Id.

Что осталось за рамками​

Другие режимы будут разобраны отдельно; остальное находится в справочнике:

  • Асинхронная публикация — несколько отправок с последующим сбором PubAcks; см. Расширенная публикация.
  • Атомарная пакетная публикация — вся группа или ничего, сервер 2.12+; см. Расширенная публикация.
  • Скоростная пакетная публикация — высокая пропускная способность с управлением потоком, без атомарности, сервер 2.14+; см. Расширенная публикация.
  • Заголовки ожидаемого потока и номера — оптимистическая конкуренция: отказ при несовпадении состояния; см. Заголовки JetStream.

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

При первой публикации часто встречаются три ошибки.

Игнорирование PubAck. Без него нельзя отличить сохранение от потери. Обычный CLI nats pub печатает Published N bytes, даже если поток не захватывает тему. Это не доказательство записи. В коде проверяйте результат, в CLI используйте nats pub --jetstream с именем потока и номером.

#!/bin/bash
# Plain `nats pub` is a core NATS publish: it reports "Published" whether
# or not a stream stored the message. Publish to a subject nothing
# captures and it still looks fine:
nats pub invoices.created "test"
# 17:31:21 Published 4 bytes to "invoices.created"

# The same publish with --jetstream reads the PubAck -- and now the miss
# is visible, because no stream captured the subject:
nats pub --jetstream invoices.created "test"
# 17:31:21 Published 4 bytes to "invoices.created"
# nats: error: nats: no responders available for request

# On a captured subject, the PubAck confirms the write with the stream
# name and the assigned sequence:
nats pub --jetstream orders.created \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# 17:31:21 Published 91 bytes to "orders.created"
# 17:31:21 Stored in Stream: ORDERS Sequence: 4

Обычная публикация выводит Published даже для темы без потока. --jetstream выявляет это ошибкой «нет отвечающих», а успешную запись подтверждает Stored in Stream … Sequence ….

Повторы без Nats-Msg-Id. После тайм-аута сообщение могло сохраниться. Повтор без того же идентификатора создаёт дубликат. Даже с ним повтор позже стандартных двух минут окна даст новую копию. Каждой повторяемой публикации нужен стабильный идентификатор; см. Предотвращение повторной записи.

Приравнивание публикации к доставке. PubAck не означает обработку потребителем. Помечать заказ отправленным сразу после него неверно: логика отправки ещё могла его не видеть. Бизнес-результат отделяйте от записи. Доставка и подтверждение рассмотрены на следующей странице и в доставке и подтверждении.

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

ORDERS содержит три сообщения с PubAck, а повторная публикация больше не создаёт вторую копию.

Потребители их пока не читали. Чтение потока займётся этим.

См. также​