Преобразование тем
До сих пор сообщение сохраняло тему издателя: клиент публиковал orders.created, сервер направлял его подписчикам orders.created. Преобразование тем нарушает эту прямую связь. По собственной конфигурации сервер переписывает тему сразу при поступлении сообщения, до поиска заинтересованных подписчиков. Издатель отправляет прежнюю команду и не видит изменений.
Acme уже нужен такой механизм. Старое мобильное приложение публикует заказы в orders.placed, а сервисы перешли на orders.created. Вместо новой сборки приложения Acme настраивает соответствие orders.placed → orders.created. Приложение продолжает публиковать orders.placed, упаковщики и аналитика подписываются на orders.created, сервер связывает обе стороны.
Это преобразование на уровне учётной записи, на которое ссылается глава JetStream. Оно отличается от преобразования темы потока и republish: те меняют тему при входе в поток JetStream или выходе из него и настраиваются в потоке. Серверное преобразование выполняется раньше, на обычных темах Core NATS. Возможности потоков см. в Преобразовании тем и трансформациях; здесь речь о конфигурации сервера.
Переименование темы
Преобразование темы (subject mapping) — правило серверной конфигурации, заменяющее одну тему другой. Задайте исходную и целевую темы: при получении сообщения сервер доставит его так, будто издатель указал целевую.
Правило находится в конфигурационном файле, который впервые требуется в этой главе. Раньше сервер запускался просто как nats-server; теперь создайте небольшой файл и запустите nats-server -c server.conf. Переименование старой темы Acme выглядит так:
# server.conf
mappings {
orders.placed: orders.created
}
nats-server -c server.conf
Теперь публикация в orders.placed достигает всех подписчиков orders.created. Команда издателя не меняется, уведомления о преобразовании нет: оно выполняется на сервере при входе.
Верхнеуровневый блок mappings относится к встроенной учётной записи сервера, поэтому без отдельных учётных записей и аутентификации действует для всех клиентов. Преобразования всегда ограничены учётной записью: при нескольких записях у каждой свои правила, не пересекающие границу.
Блок mappings поддерживает перезагрузку. Измените server.conf и выполните nats-server --signal reload: сервер перечитает конфигурацию без перезапуска, а открытые соединения сохранятся.
Предварительная проверка преобразования
Для проверки не нужно менять работающий сервер. nats server mappings принимает исходный шаблон, назначение и тему, применяет серверный код преобразования и выводит результат без сервера и соединения.
- CLI
#!/bin/bash
# Check a mapping without a running server. `nats server mappings` takes a
# source pattern, a destination pattern, and a subject, runs the same
# transform code the server uses, and prints the result. It opens no
# connection, so you can try a mapping before you ever put it in config.
# A literal rename: orders.placed always maps to orders.created.
nats server mappings "orders.placed" "orders.created" orders.placed
# A token reference: {{wildcard(1)}} pulls the token the first * matched into
# the destination, so orders.legacy.us becomes orders.us.created.
nats server mappings "orders.legacy.*" "orders.{{wildcard(1)}}.created" orders.legacy.us
orders.created
orders.us.created
Вторая команда показывает ссылку на сегмент: {{wildcard(1)}} в назначении означает сегмент, совпавший с первой одиночной подстановкой источника. В orders.legacy.* совпал us, поэтому orders.{{wildcard(1)}}.created стало orders.us.created. Подстановки нумеруются слева направо: {{wildcard(2)}} обозначает второй *.
Взвешенное разделение трафика
Преобразование может направлять часть сообщений в другую тему. Взвешенное правило перечисляет назначения с весами от 0 до 100. Для каждого сообщения сервер случайно выбирает назначение пропорционально весу.
Acme испытывает новую сборку упаковщика: десятая часть заказов должна идти на пробный экземпляр, остальные — как обычно. Для orders.created задаётся пробное назначение с весом 10:
# server.conf
mappings {
orders.created: [
{ destination: orders.created.canary, weight: 10 }
]
}
Сумма указанных весов равна 10, а не 100. Остальные 90 сообщений из 100 сервер оставляет в исходной теме. Прежние упаковщики на orders.created обрабатывают большинство, пробный на orders.created.canary — остальное. Если сумма меньше 100, остаток сохраняется в исходной теме.
Чтобы разделить трафик между двумя новыми темами, перечислите обе с суммой 100 — например, 50 и 50 для равного A/B-теста без сообщений в исходной теме. Если остаток нужно отбрасывать для проверки потерь, укажите саму исходную тему одним из назначений: сервер сочтёт веса окончательными и не дополнит их. Это работает, поскольку источник здесь — конкретная тема.
Выбор случаен для каждого сообщения, как в группе очереди: на малой выборке возможна неравномерность, на тысячах распределение приближается к весам. Каждый вес и их сумма для одного источника должны быть не больше 100, иначе конфигурация отклоняется.
Секционирование по сегменту
Веса распределяют сообщения случайно. Секционирование делает это детерминированно: хеширует сегмент и выбирает фиксированную секцию, поэтому одно значение всегда попадает в одну секцию. В назначении {{partition(n, 1)}} обозначает номер секции: сегмент первой одиночной подстановки хешируется в одну из n секций от 0 до n-1.
Acme хочет закрепить заказ за определённым пулом, чтобы все его данные оставались в одном кеше без согласования между пулами. Пул определяется идентификатором заказа, поэтому идентификатор должен войти в тему. Приложение публикует новые заказы с ним в последнем сегменте, например orders.created.ord_8w2k, а Acme распределяет их хешированием по трём секциям:
# server.conf
mappings {
"orders.created.*": "orders.created.{{partition(3, 1)}}.{{wildcard(1)}}"
}
Источник orders.created.* соответствует любому идентификатору в последнем сегменте. Назначение строит новую тему: {{partition(3, 1)}} даёт секцию, а {{wildcard(1)}} переносит сам идентификатор. Так orders.created.ord_8w2k становится orders.created.0.ord_8w2k.
Выбор детерминирован, поэтому nats server mappings показывает секцию идентификатора ещё до применения конфигурации:
nats server mappings "orders.created.*" "orders.created.{{partition(3, 1)}}.{{wildcard(1)}}" orders.created.ord_8w2k
orders.created.0.ord_8w2k
При другом идентификаторе меняется секция: ord_7mn3 попадает в orders.created.1.ord_7mn3, ord_2zr9 — в orders.created.2.ord_2zr9. Повтор одного идентификатора даёт ту же секцию, что делает такую маршрутизацию надёжной.
Каждый пул подписывается на свою секцию. Упаковщики секции 0 — на orders.created.0.* с общей группой очереди; пулы секций 1 и 2 — на orders.created.1.* и orders.created.2.*. Группы очередей распределяют работу внутри секции, преобразование выбирает секцию. Поскольку перезапись происходит до маршрутизации, пулы подписываются на темы секций, а не orders.created.*. Подписчик старой orders.created.ord_8w2k ничего не получит: тема уже изменена до сопоставления интереса.
partition и wildcard покрывают почти все преобразования Core NATS. В языке есть и другие функции — split, slicefromleft и прочие меняют отдельный сегмент. Потоки используют тот же набор; полный список см. в языке преобразований.
Назначения с областью действия кластера
Назначение может содержать cluster. Тогда правило действует только для публикаций через сервер указанного кластера; при отсутствии подходящего варианта сервер использует правило без ограничения. Так одна исходная тема преобразуется по-разному в регионах. Это нужно лишь при нескольких кластерах — см. Суперкластеры. Одному серверу такое ограничение не требуется.
Попробуйте
Примените секционирование к реальному серверу. Сохраните конфигурацию и запустите его с ней:
# server.conf
mappings {
"orders.created.*": "orders.created.{{partition(3, 1)}}.{{wildcard(1)}}"
}
nats-server -c server.conf
Откройте по подписчику на секцию и опубликуйте три заказа:
- CLI
#!/bin/bash
# Deterministic partitioning across three packer pools.
#
# The server (server.conf) maps:
# orders.created.* -> orders.created.{{partition(3, 1)}}.{{wildcard(1)}}
# so every order id hashes to a fixed bucket: 0, 1, or 2. The same id always
# lands in the same bucket.
#
# Open one subscriber per bucket, each in its own terminal. A real pool would
# add --queue to share a bucket across several packers; one subscriber per
# bucket is enough to see the split.
# Terminal 1 — bucket 0
nats sub "orders.created.0.*"
# Terminal 2 — bucket 1
nats sub "orders.created.1.*"
# Terminal 3 — bucket 2
nats sub "orders.created.2.*"
# Terminal 4 — publish three orders with the id as the last token.
# ord_8w2k hashes to bucket 0, ord_7mn3 to bucket 1, ord_2zr9 to bucket 2.
nats pub orders.created.ord_8w2k '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
nats pub orders.created.ord_7mn3 '{"order_id":"ord_7mn3","customer":"globex","total_cents":7800,"ts":"2026-05-22T10:14:25Z"}'
nats pub orders.created.ord_2zr9 '{"order_id":"ord_2zr9","customer":"initech","total_cents":1500,"ts":"2026-05-22T10:14:29Z"}'
Каждый попадёт ровно в одну секцию: ord_8w2k — в 0, ord_7mn3 — в 1, ord_2zr9 — в 2. Повторная публикация orders.created.ord_8w2k снова попадёт в 0: хеш стабилен.
Подводные камни
Правило незаметно меняет получателей. Сервер переписывает тему до проверки интереса, поэтому подписчики исходной темы могут перестать получать сообщения. Полностью преобразуйте orders.created в новую тему — упаковщики orders.created замолчат без ошибок и предупреждений. Сначала выясните, кто уже подписан, и при необходимости оставьте долю трафика в исходной теме, например через остаток весов.
Сумма весов меньше 100 сохраняет остаток. Вес 10 для одного назначения не отбрасывает остальные 90 процентов: сервер отправляет их в исходную тему. Для реального отбрасывания укажите исходную тему назначением, чтобы веса считались окончательными. Это работает только с конкретным источником, например orders.created.
Число секций — часть контракта темы. Номер зависит от n в partition(n, ...). Если заменить partition(3, ...) на partition(4, ...), тот же идентификатор может попасть в другую секцию, а фильтр пула незаметно охватит другой набор заказов. Выбирайте число секций заранее, как для любой секционированной системы.
Что уже сделано
В текущем сеансе появился первый конфигурационный файл:
- Локальный
nats-serverзапускается черезnats-server -c server.confи перечитывает настройки черезnats-server --signal reload. - Правило связывает старого издателя
orders.placedсorders.createdбез изменения приложения. - Сервер может разделять трафик по весам или фиксированным секциям по хешу сегмента до выбора подписчика.
Тема издателя теперь не всегда совпадает с темой, по которой подписчик получает сообщение: между ними действует конфигурация сервера.
Что дальше
Все предыдущие операции предполагали готовое соединение с сервером. На странице Жизненный цикл соединения рассматривается оно само: последствия разрыва для клиента и сообщений в пути и наблюдение за восстановлением.
См. также
- Преобразование тем и трансформации — возможности потока: изменение тем на входе и повторная публикация на выходе.
- Справочник → mappings — ключи
destination,weight,clusterи точные правила. - Группы очередей — пулы, распределяющие работу внутри секции.
- Суперкластеры — назначения с ограничением по кластеру между регионами.