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

Публикация и подписка

У 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:

#!/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"}'

Вызов публикации сразу возвращает управление. Он не ждёт подписчика и не сообщает, сколько подписчиков получили сообщение и получил ли его кто-нибудь вообще. Это fire-and-forget: издатель передаёт сообщение серверу и продолжает работу.

Издатель всегда указывает полностью заданную тему. orders.created — конкретная тема, а не шаблон. Подстановочные символы используются подписчиками и разбираются на следующей странице.

Подписка на тему​

Подписчик — клиент, регистрирующий интерес к теме и получающий копию каждого подходящего сообщения. Запустите складской сервис как подписчика orders.created:

#!/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

Теперь снова опубликуйте сообщение предыдущим примером. Склад его получит. Запустите второго подписчика для notifications и третьего для analytics, всех на orders.created: каждый получит собственную копию следующей публикации.

Копии независимы: подписка не извлекает сообщения из очереди, и получение сообщения одним подписчиком ничего не отнимает у другого.

Чтобы один подписчик видел все темы заказов, подпишите его на orders.> вместо отдельной темы. Символ > — подстановочный; его работа объясняется на следующей странице.

Отписка​

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

Подписка также может завершаться после заданного числа сообщений, без самостоятельного подсчёта в приложении. Это автоматическая отписка: клиент вызывает соответствующий метод (AutoUnsubscribe(N) в Go), сообщая серверу завершить подписку после доставки N сообщений. CLI nats sub --count N получает тот же результат, самостоятельно считая сообщения и отписываясь при достижении лимита. Это удобно для сценария «получить ровно N», например прочитать следующие три заказа и остановиться.

#!/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

Граф интереса​

Сервер отслеживает подписки в структуре данных в памяти — графе интереса. Каждая подписка добавляет запись; отписка или отключение удаляет её.

Когда приходит сообщение, сервер находит в графе интереса тему и подходящих подписчиков, затем отправляет каждому копию. Если на 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 до отправки; соединение остаётся открытым. Соблюдайте лимит, а для больших данных передавайте ссылку.

#!/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.

Завершение до отправки сообщения из клиента приводит к его потере. Вызов публикации сразу возвращает управление, поскольку клиент буферизует сообщение и отправляет его в фоне. Короткоживущий издатель может завершиться до доставки буфера серверу, и сообщение будет потеряно. Перед выходом выполняйте 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.

См. также​