Публикация и подписка
У Core NATS одна базовая операция: клиент публикует сообщение в тему, и каждый клиент, подписанный на неё прямо сейчас, получает копию. Эта страница показывает, как это работает на уровне протокола: откуда берутся копии, что происходит без подписчиков и какие гарантии доставки даёт Core NATS.
Сценарий
Acme использует платформу заказов. С заказом происходят три события, каждое из которых передаётся сообщением в собственной теме:
orders.created
orders.shipped
orders.canceled
Каждое сообщение этой главы содержит одинаковую небольшую полезную нагрузку JSON:
{
"order_id": "ord_8w2k",
"customer": "acme-co",
"total_cents": 4200,
"ts": "2026-05-22T10:14:22Z"
}
Этими сообщениями интересуются три сервиса. warehouse упаковывает заказ после его создания. notifications отправляет письмо покупателю. analytics подсчитывает всё. Ни один из них не знает о существовании остальных.
В разделе Подключение уже запущен один локальный nats-server. Оставьте его работающим до конца главы. Если вы сразу открыли эту страницу, запустите сервер сейчас:
nats-server
Это всё развёртывание: без флагов, долговременного хранения и кластера. Добавляйте сервисы по мере прохождения главы.
Публикация сообщения
Издатель — клиент, отправляющий сообщение в тему. Склад ещё ни на что не подписан, поэтому начните с публикации одного сообщения orders.created:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Publish one order to the orders.created subject. The publish is
# fire-and-forget: nats pub hands the message to the server and exits.
# It does not wait for, or report, any subscriber.
nats pub orders.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the server and returns.
const order =
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}';
nc.publish("orders.created", order);
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the server and returns.
order := `{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}`
nc.Publish("orders.created", []byte(order))
# Publish one order to the orders.created subject. Publishing is
# fire-and-forget: the call hands the message to the server and returns.
order = '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
await client.publish("orders.created", order.encode())
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the server and returns.
byte[] order = ("{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
+ "\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}").getBytes(StandardCharsets.UTF_8);
nc.publish("orders.created", order);
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the server and returns.
let order = r#"{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}"#;
client.publish("orders.created", order.into()).await?;
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the server and returns.
// The client serializes the Order record to JSON by default.
var order = new Order(
OrderId: "ord_8w2k",
Customer: "acme-co",
TotalCents: 4200,
Timestamp: DateTimeOffset.Parse("2026-05-22T10:14:22Z", CultureInfo.InvariantCulture));
await client.PublishAsync<Order>("orders.created", order);
// Publish one order to the orders.created subject. Publishing is
// fire-and-forget: the call hands the message to the client and
// returns. It does not wait for, or report, any subscriber.
if (s == NATS_OK)
s = natsConnection_PublishString(conn, "orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}");
Вызов публикации сразу возвращает управление. Он не ждёт подписчика и не сообщает, сколько подписчиков получили сообщение и получил ли его кто-нибудь вообще. Это fire-and-forget: издатель передаёт сообщение серверу и продолжает работу.
Издатель всегда указывает полностью заданную тему. orders.created — конкретная тема, а не шаблон. Подстановочные символы используются подписчиками и разбираются на следующей странице.
Подписка на тему
Подписчик — клиент, регистрирующий интерес к теме и получающий копию каждого подходящего сообщения. Запустите складской сервис как подписчика orders.created:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Subscribe as the warehouse service to orders.created. Each matching
# message is printed as it arrives; Ctrl-C to stop. To receive every
# order subject at once instead, subscribe to the wildcard orders.>
nats sub orders.created
// Subscribe as the warehouse service to orders.created. Each matching
// message is delivered to this subscription as it is published.
const sub = nc.subscribe("orders.created");
for await (const msg of sub) {
console.log(`warehouse received: ${msg.string()}`);
}
// Subscribe as the warehouse service to orders.created. The callback runs
// for each matching message as it is published.
nc.Subscribe("orders.created", func(m *nats.Msg) {
fmt.Printf("warehouse received: %s\n", string(m.Data))
})
# Subscribe as the warehouse service to orders.created. Each matching
# message is delivered to this subscription as it is published.
async with await client.subscribe("orders.created") as subscription:
async for message in subscription:
print(f"warehouse received: {message.data.decode()}")
// Subscribe as the warehouse service to orders.created. Each matching
// message is delivered to this dispatcher as it is published.
nc.createDispatcher(msg ->
System.out.println("warehouse received: " + new String(msg.getData(), StandardCharsets.UTF_8))
).subscribe("orders.created");
// Subscribe as the warehouse service to orders.created. Each matching
// message is delivered to this subscription as it is published.
let mut sub = client.subscribe("orders.created").await?;
while let Some(msg) = sub.next().await {
println!(
"warehouse received: {}",
String::from_utf8_lossy(&msg.payload)
);
}
// Subscribe as the warehouse service to orders.created. Each matching
// message is delivered to this subscription as it is published and
// deserialized from JSON into an Order record.
await foreach (var msg in client.SubscribeAsync<Order>("orders.created"))
{
output.WriteLine($"warehouse received: {msg.Data}");
}
// The callback runs for each matching message as it is published.
static void
onMsg(natsConnection *nc, natsSubscription *sub, natsMsg *msg, void *closure)
{
printf("warehouse received: %.*s\n",
natsMsg_GetDataLength(msg), natsMsg_GetData(msg));
natsMsg_Destroy(msg);
}
// Subscribe as the warehouse service to orders.created.
if (s == NATS_OK)
s = natsConnection_Subscribe(&sub, conn, "orders.created", onMsg, NULL);
Теперь снова опубликуйте сообщение предыдущим примером. Склад его получит. Запустите второго подписчика для notifications и третьего для analytics, всех на orders.created: каждый получит собственную копию следующей публикации.
Копии независимы: подписка не извлекает сообщения из очереди, и получение сообщения одним подписчиком ничего не отнимает у другого.
Чтобы один подписчик видел все темы заказов, подпишите его на orders.> вместо отдельной темы. Символ > — подстановочный; его работа объясняется на следующей странице.
Отписка
Когда подписчик отписывается, сервер удаляет его интерес к теме после обработки запроса. Последующие публикации ему не доставляются, а на стороне сервера не остаётся ничего, что нужно очищать.
Подписка также может завершаться после заданного числа сообщений, без самостоятельного подсчёта в приложении. Это автоматическая отписка: клиент вызывает соответствующий метод (AutoUnsubscribe(N) в Go), сообщая серверу завершить подписку после доставки N сообщений. CLI nats sub --count N получает тот же результат, самостоятельно считая сообщения и отписываясь при достижении лимита. Это удобно для сценария «получить ровно N», например прочитать следующие три заказа и остановиться.
- CLI
- C
#!/bin/bash
# Subscribe to orders.created and stop automatically after three messages.
# --count makes nats sub quit once it has received that many, giving a
# take-exactly-N read instead of an open-ended subscription you Ctrl-C.
nats sub orders.created --count 3
// Subscribe to orders.created and stop automatically after three
// messages. AutoUnsubscribe tells the client to remove the
// subscription once that many have been delivered, giving a
// take-exactly-N read instead of an open-ended subscription.
if (s == NATS_OK)
s = natsConnection_SubscribeSync(&sub, conn, "orders.created");
if (s == NATS_OK)
s = natsSubscription_AutoUnsubscribe(sub, 3);
// Read the three orders, waiting up to 10 seconds for each.
if (s == NATS_OK)
{
int i;
for (i = 0; (s == NATS_OK) && (i < 3); i++)
{
natsMsg *msg = NULL;
s = natsSubscription_NextMsg(&msg, sub, 10000);
if (s == NATS_OK)
{
printf("warehouse received: %.*s\n",
natsMsg_GetDataLength(msg), natsMsg_GetData(msg));
natsMsg_Destroy(msg);
}
}
}
Граф интереса
Сервер отслеживает подписки в структуре данных в памяти — графе интереса. Каждая подписка добавляет запись; отписка или отключение удаляет её.
Когда приходит сообщение, сервер находит в графе интереса тему и подходящих подписчиков, затем отправляет каждому копию. Если на orders.created подписаны три сервиса, одна публикация приводит к трём доставкам. Издатель ничего не менял: веерная рассылка выполнена целиком сервером.
Граф интереса обеспечивает независимость компонентов. Издатель не хранит список подписчиков. Он публикует в тему, а сервер определяет получателей в момент поступления сообщения.
Поэтому сервисы могут свободно подключаться и отключаться. Запустите четвёртого подписчика — он войдёт в граф и получит следующую публикацию. Остановите подписчика — запись исчезнет и следующая публикация его пропустит. Согласование не требуется, издатель не меняется.
Если никто не слушает
Опубликуйте сообщение в orders.created, когда сервисы не подписаны. Публикация всё равно завершится успешно, а сообщение будет отброшено. Сервер не найдёт подходящей записи в графе интереса: доставлять некому, поэтому сообщение удаляется.
Публикация без интереса — незаметная операция без результата: ни ошибки, ни сохранённой очереди. Издатель не отличает «доставлено трём подписчикам» от «не доставлено никому»: оба случая выглядят как успешная публикация. Если склад перезапускается в момент публикации orders.created, сообщение теряется.
Доставка не более одного раза
Core NATS доставляет каждое сообщение не более одного раза. Подключённый и заинтересованный в момент публикации подписчик получает его один раз. Отсутствующий, медленный или отключённый в этот момент — ни разу. Второй попытки нет.
Core NATS не повторяет пропущенную доставку, не обнаруживает и не подавляет дубликаты и не гарантирует, что под нагрузкой два подписчика увидят сообщения в одном порядке. Такие свойства добавляются с помощью JetStream, а не предоставляются базовым слоем.
Доставка не более одного раза подходит большому классу сообщений: выборочной телеметрии, уведомлениям об устаревании кеша и данным для онлайн-панелей. Пропуск здесь несущественен, поскольку следующее сообщение уже в пути. Для заказа, который необходимо упаковать ровно один раз, этого недостаточно. Здесь проходит граница Core NATS.
Лимит полезной нагрузки 1 МБ
Размер полезной нагрузки ограничен. По умолчанию сервер допускает 1 МБ (max_payload, 1048576 байт). При установлении соединения сервер сообщает лимит каждому клиенту, поэтому тот знает ограничение ещё до первой публикации.
Клиент знает лимит и проверяет размер перед отправкой. Официальный клиент завершает публикацию ошибкой nats: maximum payload exceeded, сохраняя соединение, а сообщение остаётся на стороне клиента. Сервер служит последней защитой от клиента, всё же отправившего слишком большое сообщение: он отвечает -ERR 'Maximum Payload Violation' и закрывает соединение. Заказ Acme занимает несколько сотен байт и укладывается в лимит, но попытка передать большой двоичный объект в сообщении его превысит.
Для больших данных публикуйте ссылку (ключ объектного хранилища или URL), а получатель пусть загружает содержимое отдельно.
Попробуйте в двух терминалах
Проверьте публикацию без ожидания и доставку не более одного раза напрямую. Откройте два терминала, подключённых к работающему серверу.
# Terminal 1 — the warehouse subscribes
nats sub orders.created
# Terminal 2 — publish three orders
nats pub orders.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
nats pub orders.created '{"order_id":"ord_2zr9","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}'
nats pub orders.created '{"order_id":"ord_5kq1","customer":"initech","total_cents":1500,"ts":"2026-05-22T10:14:29Z"}'
Первый терминал выводит каждое сообщение сразу после публикации. Теперь остановите в нём подписчика с помощью Ctrl-C, опубликуйте четвёртое сообщение и запустите подписчика снова. Четвёртое сообщение не появится: оно было опубликовано при пустом графе интереса и отброшено. Так проявляется доставка не более одного раза.
Подводные камни
Превышение лимита приводит к ошибке публикации. Официальный клиент сверяет нагрузку с max_payload и возвращает nats: maximum payload exceeded до отправки; соединение остаётся открытым. Соблюдайте лимит, а для больших данных передавайте ссылку.
- CLI
- C
#!/bin/bash
# Ask your connection for its limits before sizing a message. The
# "Maximum Payload" row comes from the INFO the server sends at connect
# (1 MB by default), so a plain no-auth connection can read it. An
# official client checks this ceiling and fails an oversized publish
# locally; the server rejects and closes the connection of any client
# that sends a larger PUB anyway.
nats account info
# A safe order publish stays far under the ceiling.
nats pub orders.created '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Publishing over the ceiling fails immediately, client-side, before the
# message reaches the server. Try a 2 MB payload:
#
# head -c 2000000 /dev/zero | tr '\0' x | nats pub orders.created --force-stdin
# nats: error: nats: maximum payload exceeded
#
# So keep payloads small and pass a reference (an object-store key or a URL)
# for anything large, rather than discovering the limit the hard way.
// Ask the connection for its limit before sizing a message. The value
// comes from the INFO the server sent at connect (1 MB by default).
if (s == NATS_OK)
printf("maximum payload: %d bytes\n",
(int) natsConnection_GetMaxPayload(conn));
// A safe order publish stays far under the ceiling.
if (s == NATS_OK)
s = natsConnection_PublishString(conn, "orders.created",
"{\"order_id\":\"ord_8w2k\",\"customer\":\"acme-co\","
"\"total_cents\":4200,\"ts\":\"2026-05-22T10:14:22Z\"}");
// Publishing over the ceiling fails immediately, client-side, before
// the message reaches the server. Try a 2 MB payload:
if (s == NATS_OK)
{
int bigLen = 2 * 1024 * 1024;
char *big = malloc(bigLen);
memset(big, 'x', bigLen);
s = natsConnection_Publish(conn, "orders.created", big, bigLen);
if (s == NATS_MAX_PAYLOAD)
{
printf("oversized publish rejected: %s\n", natsStatus_GetText(s));
s = NATS_OK;
}
free(big);
}
Завершение до отправки сообщения из клиента приводит к его потере. Вызов публикации сразу возвращает управление, поскольку клиент буферизует сообщение и отправляет его в фоне. Короткоживущий издатель может завершиться до доставки буфера серверу, и сообщение будет потеряно. Перед выходом выполняйте flush или drain. Клиент дожидается обмена с сервером, к этому моменту весь предыдущий буфер уже доставлен:
nc.Publish("orders.created", payload)
nc.Flush() // wait until the server has the message, then exit
nc.Close()
Соединение получает опубликованные им сообщения. Если одно соединение и публикует, и подписывается на тему, оно получает копию собственных сообщений: echo по умолчанию включён. Сервис, публикующий обновления состояния и подписанный на них, может зациклить обработку своих обновлений. Отключение описано в разделе Подключение.
Медленного подписчика отключают. Если подписчик не успевает за потоком подходящих сообщений, на сервере растёт очередь. После порога сервер перестаёт защищать его, записывает Slow Consumer Detected и закрывает соединение. Остальные подписчики не затрагиваются. Исправление нужно на клиенте: обрабатывайте сообщения достаточно быстро или передавайте обработчику. Настройки и восстановление разобраны в Устойчивые клиенты → Медленные потребители.
Что уже сделано
У вас работает один локальный nats-server, а сервисы заказов Acme обмениваются сообщениями через базовую публикацию и подписку:
- Издатель отправляет сообщения
orders.createdбез ожидания. - Подписчики
warehouse,notificationsиanalyticsполучают каждый свою копию. - Сообщение без заинтересованных подписчиков отбрасывается, доставка выполняется не более одного раза.
Что дальше
Пока каждый сервис подписан на одну точную тему. Следующая страница, Темы и подстановочные символы, показывает иерархию тем и использование * и > для подписки на множество тем, включая региональные заказы вроде orders.us.created.
См. также
- Основные понятия → Публикация и подписка — пятиминутный обзор шаблона.
- Изучение → JetStream → Зачем нужен поток — слой, сохраняющий сообщения, которые Core NATS отбрасывает.
- Справочник → Клиентский протокол — протокольные детали
PUB/SUB/MSG.