Публикация
Поток 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. Далее рассмотрены его поля.
Те же три публикации через библиотеку:
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
// 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}`);
}
// Publish three order messages into the ORDERS stream. Each Publish blocks
// until the server replies with a PubAck confirming where it was stored.
orders := []struct {
subject string
payload string
}{
{"orders.created", `{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`},
{"orders.created", `{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}`},
{"orders.shipped", `{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}`},
}
for _, order := range orders {
ack, err := js.Publish(ctx, order.subject, []byte(order.payload))
if err != nil {
panic(err)
}
fmt.Printf("Stored in %s, sequence %d\n", ack.Stream, ack.Sequence)
}
# Publish three orders. Each publish waits for the server's acknowledgement,
# which carries the stream name and the assigned sequence number.
ack = await js.publish(
"orders.created",
b'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}',
)
print(f"Stored in {ack.stream}, sequence {ack.seq}")
ack = await js.publish(
"orders.created",
b'{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}',
)
print(f"Stored in {ack.stream}, sequence {ack.seq}")
ack = await js.publish(
"orders.shipped",
b'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}',
)
print(f"Stored in {ack.stream}, sequence {ack.seq}")
// Publish three orders to the "ORDERS" stream and read each ack
PublishAck ack1 = js.publish("orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}".getBytes(StandardCharsets.UTF_8));
System.out.printf("Stored in %s at sequence %d%n", ack1.getStream(), ack1.getSeqno());
PublishAck ack2 = js.publish("orders.created",
"{\"order_id\":\"ord_2zr9\",\"customer\":\"globex\",\"total_cents\":7800,\"ts\":\"2026-05-22T10:14:25Z\"}".getBytes(StandardCharsets.UTF_8));
System.out.printf("Stored in %s at sequence %d%n", ack2.getStream(), ack2.getSeqno());
PublishAck ack3 = js.publish("orders.shipped",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:31Z\"}".getBytes(StandardCharsets.UTF_8));
System.out.printf("Stored in %s at sequence %d%n", ack3.getStream(), ack3.getSeqno());
// Publish three orders into the ORDERS stream, reading each ack as it returns.
let messages = [
(
"orders.created",
r#"{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}"#,
),
(
"orders.created",
r#"{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}"#,
),
(
"orders.shipped",
r#"{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:31Z"}"#,
),
];
for (subject, payload) in messages {
// The first await sends the message; the second waits for the server ack.
let ack = js.publish(subject, payload.into()).await?.await?;
println!("Stored in {} at sequence {}", ack.stream, ack.sequence);
}
// Publish each order and read the ack the stream returns
var ack1 = await js.PublishAsync<Order>(
subject: "orders.created",
data: new Order(OrderId: "ord_8w2k", Customer: "acme-co", TotalCents: 4200, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:22Z", CultureInfo.InvariantCulture)));
output.WriteLine($"Stored in {ack1.Stream} at sequence {ack1.Seq}");
var ack2 = await js.PublishAsync<Order>(
subject: "orders.created",
data: new Order(OrderId: "ord_2zr9", Customer: "globex", TotalCents: 7800, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:25Z", CultureInfo.InvariantCulture)));
output.WriteLine($"Stored in {ack2.Stream} at sequence {ack2.Seq}");
var ack3 = await js.PublishAsync<Order>(
subject: "orders.shipped",
data: new Order(OrderId: "ord_8w2k", Customer: "acme-co", TotalCents: 4200, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:31Z", CultureInfo.InvariantCulture)));
output.WriteLine($"Stored in {ack3.Stream} at sequence {ack3.Seq}");
// Publish three order messages into the ORDERS stream. Each js_Publish
// blocks until the server replies with an ack confirming where it was
// stored.
const char *subjects[] = {"orders.created", "orders.created", "orders.shipped"};
const char *payloads[] = {
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}",
"{\"order_id\":\"ord_2zr9\",\"customer\":\"globex\",\"total_cents\":7800,\"ts\":\"2026-05-22T10:14:25Z\"}",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:31Z\"}"};
for (int i = 0; (i < 3) && (s == NATS_OK); i++)
{
jsPubAck *ack = NULL;
s = js_Publish(&ack, js, subjects[i],
payloads[i], (int) strlen(payloads[i]),
NULL, &jerr);
if (s == NATS_OK)
{
printf("Stored in %s, sequence %" PRIu64 "\n", ack->Stream, ack->Sequence);
jsPubAck_Destroy(ack);
}
}
Во всех примерах два общих свойства:
- Публикация идёт в тему; сервер сам находит захватывающий её поток. Код не обязан знать привязки.
- Вызов возвращает
PubAck: доказательство достижения потока. Далее прочитаем его.
Содержимое PubAck
Три часто используемых поля:
- stream — сохранивший поток; полезен в тестах и журналах.
- sequence — порядковый номер сообщения, видимый и в
nats stream info. Сохранив его с бизнес-записью, можно позже начать воспроизведение отсюда. - duplicate —
falseдля нового,trueдля распознанного повтора; см. Предотвращение повторной записи.
Возможны дополнительные поля, например domain для нескольких арендаторов или листовых узлов. Полный список — в справочнике; обычно нужны три перечисленных.
Предыдущие примеры уже возвращают этот объект: остаётся прочитать поля.
Правило: только PubAck доказывает сохранение. Ошибка «нет отвечающих» для темы без потока означает отсутствие записи. Но сетевой тайм-аут означает отсутствие подтверждения: сообщение могло сохраниться, а ответ — потеряться. Повторите попытку или сообщите об ошибке; для безопасного повтора задайте Nats-Msg-Id, как показано ниже.
Сохранение и доставка
PubAck подтверждает сохранение, но не получение потребителем. Это отдельные операции.
В Core NATS доставка и завершение публикации почти совпадают. В JetStream:
- Издатель публикует; сервер сохраняет и возвращает
PubAck. - Позже — через минуты, часы или дни — клиент читает через потребителя.
- После обработки клиент подтверждает. Только тогда сообщение считается обработанным.
Здесь выполнен первый шаг, остальные рассматриваются далее.
Предотвращение повторной записи
Тайм-аут может наступить после сохранения при потерянном ответе. Простой повтор создаст вторую копию. Заголовок 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, ничего не добавляя. Через библиотеку:
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
// 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}`);
// Publish the same message twice with a message ID. The stream uses the ID
// to detect duplicates within its dedupe window.
first, err := js.Publish(ctx, "orders.created", []byte(payload), jetstream.WithMsgID("ord_8w2k-created"))
if err != nil {
panic(err)
}
fmt.Printf("First: sequence %d, duplicate %t\n", first.Sequence, first.Duplicate)
// Re-publish with the same ID. The server recognizes it and reports the
// original sequence instead of storing the message again.
second, err := js.Publish(ctx, "orders.created", []byte(payload), jetstream.WithMsgID("ord_8w2k-created"))
if err != nil {
panic(err)
}
fmt.Printf("Second: sequence %d, duplicate %t\n", second.Sequence, second.Duplicate)
# Set "Nats-Msg-Id" so the server can detect duplicates within the stream's
# duplicate window.
payload = b'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
headers = {"Nats-Msg-Id": "ord_8w2k-created"}
# Publish the same message twice with the same id.
first = await js.publish("orders.created", payload, headers=headers)
print(f"First: sequence {first.seq}, duplicate {first.duplicate}")
second = await js.publish("orders.created", payload, headers=headers)
print(f"Second: sequence {second.seq}, duplicate {second.duplicate}")
// Tag the message with a stable id so a retry is deduplicated
PublishOptions options = PublishOptions.builder()
.messageId("ord_8w2k-created")
.build();
// First publish stores the message
PublishAck first = js.publish("orders.created", body, options);
System.out.printf("First: seq=%d duplicate=%b%n", first.getSeqno(), first.isDuplicate());
// Re-publishing the same id returns the original sequence, marked duplicate
PublishAck second = js.publish("orders.created", body, options);
System.out.printf("Second: seq=%d duplicate=%b%n", second.getSeqno(), second.isDuplicate());
// Publish the same order twice, tagging both with the same message id.
// The server stores the first and detects the second as a duplicate.
let first = js
.send_publish(
"orders.created",
PublishMessage::build()
.payload(payload.into())
.message_id("ord_8w2k-created"),
)
.await?
.await?;
println!(
"First: sequence {}, duplicate {}",
first.sequence, first.duplicate
);
let second = js
.send_publish(
"orders.created",
PublishMessage::build()
.payload(payload.into())
.message_id("ord_8w2k-created"),
)
.await?
.await?;
println!(
"Second: sequence {}, duplicate {}",
second.sequence, second.duplicate
);
var order = new Order(OrderId: "ord_8w2k", Customer: "acme-co", TotalCents: 4200, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:22Z", CultureInfo.InvariantCulture));
// Tag the message with a unique id. The stream uses it to detect duplicates.
var opts = new NatsJSPubOpts { MsgId = "ord_8w2k-created" };
// First publish: the stream stores the message
var ack1 = await js.PublishAsync<Order>(subject: "orders.created", data: order, opts: opts);
output.WriteLine($"First: seq={ack1.Seq} duplicate={ack1.Duplicate}");
// Republish with the same id: the stream recognizes it and stores nothing new
var ack2 = await js.PublishAsync<Order>(subject: "orders.created", data: order, opts: opts);
output.WriteLine($"Second: seq={ack2.Seq} duplicate={ack2.Duplicate}");
// Publish the same message twice with a message ID. The stream uses
// the ID to detect duplicates within its dedupe window.
jsPubAck *first = NULL;
jsPubAck *second = NULL;
jsPubOptions po;
const char *payload = "{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}";
jsPubOptions_Init(&po);
po.MsgId = "ord_8w2k-created";
s = js_Publish(&first, js, "orders.created",
payload, (int) strlen(payload),
&po, &jerr);
if (s == NATS_OK)
{
printf("First: sequence %" PRIu64 ", duplicate %s\n",
first->Sequence, first->Duplicate ? "true" : "false");
jsPubAck_Destroy(first);
// Re-publish with the same ID. The server recognizes it and
// reports the original sequence instead of storing the message
// again.
s = js_Publish(&second, js, "orders.created",
payload, (int) strlen(payload),
&po, &jerr);
}
if (s == NATS_OK)
{
printf("Second: sequence %" PRIu64 ", duplicate %s\n",
second->Sequence, second->Duplicate ? "true" : "false");
jsPubAck_Destroy(second);
}
Каждой повторяемой публикации задавайте стабильный 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 с именем потока и номером.
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/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
// `publish` resolves only once the server has persisted the message. Awaiting
// the PubAck and reading its stream and sequence confirms the order is stored
const data =
`{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`;
const pa = await js.publish("orders.created", data);
console.log(`Stored in ${pa.stream} at sequence ${pa.seq}`);
// Publish one order and confirm it was stored. A failed publish returns an
// error rather than losing the message silently, so check err first.
ack, err := js.Publish(ctx, "orders.created", []byte(payload))
if err != nil {
panic(err)
}
// The returned PubAck is proof the message is on disk in the stream.
fmt.Printf("Stored in %s at sequence %d\n", ack.Stream, ack.Sequence)
# Publish one order. The publish only resolves once the server has stored
# the message, so reading the acknowledgement confirms it is durable.
ack = await js.publish(
"orders.created",
b'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}',
)
# The stream name and sequence number prove the message is stored.
print(f"Confirmed stored in {ack.stream} at sequence {ack.seq}")
// Publish one order; the returned ack confirms it was stored
PublishAck ack = js.publish("orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}".getBytes(StandardCharsets.UTF_8));
// A non-null ack means the server persisted the message
System.out.printf("Confirmed stored in %s at sequence %d%n", ack.getStream(), ack.getSeqno());
// Publish, then await the ack. The `?` turns a failed store into an error
// instead of letting the program continue as if the message was saved.
let ack = js.publish("orders.created", payload.into()).await?.await?;
// Reaching this line means the server persisted the message.
println!(
"Confirmed stored in {} at sequence {}",
ack.stream, ack.sequence
);
// Publish an order and read the ack
var ack = await js.PublishAsync<Order>(
subject: "orders.created",
data: new Order(OrderId: "ord_8w2k", Customer: "acme-co", TotalCents: 4200, Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:22Z", CultureInfo.InvariantCulture)));
// Throw if the stream rejected the message; otherwise the ack confirms storage
ack.EnsureSuccess();
output.WriteLine($"Confirmed: stored in {ack.Stream} at sequence {ack.Seq}");
// Publish one order and confirm it was stored. A failed publish
// returns an error status rather than losing the message silently,
// so check s first.
jsPubAck *ack = NULL;
const char *payload = "{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\",\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}";
s = js_Publish(&ack, js, "orders.created",
payload, (int) strlen(payload),
NULL, &jerr);
if (s == NATS_OK)
{
// The returned ack is proof the message is on disk in the stream.
printf("Stored in %s at sequence %" PRIu64 "\n", ack->Stream, ack->Sequence);
jsPubAck_Destroy(ack);
}
Обычная публикация выводит Published даже для темы без потока. --jetstream выявляет это ошибкой «нет отвечающих», а успешную запись подтверждает Stored in Stream … Sequence ….
Повторы без Nats-Msg-Id. После тайм-аута сообщение могло сохраниться. Повтор без того же идентификатора создаёт дубликат. Даже с ним повтор позже стандартных двух минут окна даст новую копию. Каждой повторяемой публикации нужен стабильный идентификатор; см. Предотвращение повторной записи.
Приравнивание публикации к доставке. PubAck не означает обработку потребителем. Помечать заказ отправленным сразу после него неверно: логика отправки ещё могла его не видеть. Бизнес-результат отделяйте от записи. Доставка и подтверждение рассмотрены на следующей странице и в доставке и подтверждении.
Что уже готово
ORDERS содержит три сообщения с PubAck, а повторная публикация больше не создаёт вторую копию.
Потребители их пока не читали. Чтение потока займётся этим.
См. также
- Справочник → Заголовки JetStream — дедупликация, ожидаемое состояние, пакеты.
- Справочник → Подтверждение публикации — точные поля ответа.