# Преобразование тем

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

Acme уже нужен такой механизм. Старое мобильное приложение публикует заказы в `orders.placed`, а сервисы перешли на `orders.created`. Вместо новой сборки приложения Acme настраивает соответствие `orders.placed` → `orders.created`. Приложение продолжает публиковать `orders.placed`, упаковщики и аналитика подписываются на `orders.created`, сервер связывает обе стороны.

Это преобразование на уровне учётной записи, на которое ссылается глава JetStream. Оно отличается от преобразования темы потока и republish: те меняют тему при входе в поток JetStream или выходе из него и настраиваются в потоке. Серверное преобразование выполняется раньше, на обычных темах Core NATS. Возможности потоков см. в [Преобразовании тем и трансформациях](/learn/jetstream/subject-mapping.md); здесь речь о конфигурации сервера.

## Переименование темы

**Преобразование темы (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.*`. [Группы очередей](/learn/core-nats/queue-groups.md) распределяют работу внутри секции, преобразование выбирает секцию. Поскольку перезапись происходит до маршрутизации, пулы подписываются на темы секций, а не `orders.created.*`. Подписчик старой `orders.created.ord_8w2k` ничего не получит: тема уже изменена до сопоставления интереса.

`partition` и `wildcard` покрывают почти все преобразования Core NATS. В языке есть и другие функции — `split`, `slicefromleft` и прочие меняют отдельный сегмент. Потоки используют тот же набор; полный список см. в [языке преобразований](/learn/jetstream/subject-mapping.md#the-transform-language).

## Назначения с областью действия кластера

Назначение может содержать `cluster`. Тогда правило действует только для публикаций через сервер указанного кластера; при отсутствии подходящего варианта сервер использует правило без ограничения. Так одна исходная тема преобразуется по-разному в регионах. Это нужно лишь при нескольких кластерах — см. [Суперкластеры](/learn/topologies/super-clusters.md). Одному серверу такое ограничение не требуется.

## Попробуйте

Примените секционирование к реальному серверу. Сохраните конфигурацию и запустите его с ней:

```
# 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` без изменения приложения.
* Сервер может разделять трафик по весам или фиксированным секциям по хешу сегмента до выбора подписчика.

Тема издателя теперь не всегда совпадает с темой, по которой подписчик получает сообщение: между ними действует конфигурация сервера.

## Что дальше

Все предыдущие операции предполагали готовое соединение с сервером. На странице [Жизненный цикл соединения](/learn/core-nats/connection-lifecycle.md) рассматривается оно само: последствия разрыва для клиента и сообщений в пути и наблюдение за восстановлением.

## См. также

* [Преобразование тем и трансформации](/learn/jetstream/subject-mapping.md) — возможности потока: изменение тем на входе и повторная публикация на выходе.
* [Справочник → mappings](/reference/config/mappings/.md) — ключи `destination`, `weight`, `cluster` и точные правила.
* [Группы очередей](/learn/core-nats/queue-groups.md) — пулы, распределяющие работу внутри секции.
* [Суперкластеры](/learn/topologies/super-clusters.md) — назначения с ограничением по кластеру между регионами.
