Конечные точки и группы
На предыдущей странице вы запустили сервис OrderInventory с одной конечной точкой check, отвечающей на orders.inventory.check. Это минимальная полезная структура: один сервис, один обработчик, один субъект.
Реальные сервисы редко остаются такими маленькими. Обычно сервис отвечает более чем на один вид запросов, и тогда субъекты хочется упорядочить. Эта страница добавляет две необходимые возможности: сервис может содержать несколько конечных точек, а группа задаёт набору конечных точек общий префикс субъектов.
К концу страницы рядом с OrderInventory появится второй сервис ShippingQuote, и вы научитесь размещать несколько конечных точек под одним префиксом.
Сервис может содержать несколько конечных точек
Конечная точка — именованный обработчик на субъекте. С одной вы познакомились на предыдущей странице; сервис может содержать несколько таких точек. Каждый вызов AddEndpoint(name, handler) регистрирует ещё один именованный обработчик, причём субъект конечной точки по умолчанию равен её имени.
Добавьте второй сервис так же, как первый. ShippingQuote превращает поставщиков ответов Core NATS на shipping.quote в именованный сервис. У него одна конечная точка quote; чтобы она отвечала на shipping.quote, а не просто на quote, задайте субъект явно:
- CLI
- C
#!/bin/bash
# Add a second service alongside OrderInventory.
#
# A service is created by your client library, not by the CLI: the
# library call is AddService(Name: "ShippingQuote", Version: "1.0.0")
# with one endpoint named "quote" whose subject is set to
# "shipping.quote". The CLI does not create endpoints; it talks to the
# services your code runs. This snippet shows the second service once it
# is running, the way every other language tab creates it.
# With ShippingQuote running, send a request to its endpoint. The
# service answers on shipping.quote, independent of OrderInventory.
nats service request ShippingQuote quote \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Confirm both services are now visible. Two independent services run
# against the same nats-server, each with its own name, version, and
# auto-generated service ID.
nats service list
// The quote handler: read the order, answer with a shipping quote.
static microError *
onQuote(microRequest *req)
{
const char *quote = "{\"carrier\":\"carrier-a\",\"quote_cents\":1500}";
return microRequest_Respond(req, quote, strlen(quote));
}
// A second service alongside OrderInventory. ShippingQuote promotes
// the Core NATS shipping.quote providers into a named service: one
// endpoint, "quote", answering on shipping.quote. Because the wire
// subject differs from the endpoint name, set the subject explicitly.
microServiceConfig svcConfig = {
.Name = "ShippingQuote",
.Version = "1.0.0",
.Description = "Quotes shipping for an order",
};
microEndpointConfig quoteConfig = {
.Name = "quote",
.Subject = "shipping.quote",
.Handler = onQuote,
};
if (err == NULL)
err = micro_AddService(&svc, conn, &svcConfig);
if (err == NULL)
err = microService_AddEndpoint(svc, "eConfig);
Теперь два сервиса работают с одним nats-server. OrderInventory отвечает на orders.inventory.check, а ShippingQuote — на shipping.quote. Они независимы: у каждого своё имя, версия и обнаружение. Фреймворк автоматически назначил каждому уникальный идентификатор сервиса.
Если субъект должен совпадать с именем конечной точки, его можно не задавать. Конечная точка quote без явного субъекта отвечает на quote. Явное значение нужно, когда сетевой субъект отличается от имени конечной точки; это обычная ситуация для структурированных субъектов вроде orders.inventory.check.
Контракт обработчика не изменился: запрос читается через req.Data(), ответ отправляется через req.Respond(). Добавление конечных точек не меняет обработку отдельного запроса; оно лишь добавляет именованные обработчики к тому же работающему сервису.
Группа — префикс субъекта
Когда у сервиса больше одной конечной точки, в субъектах появляются повторы. Две конечные точки проверки запасов естественно назвать orders.inventory.check и orders.inventory.reserve: основа orders.inventory повторяется. Группа позволяет задать её один раз.
AddGroup("orders.inventory") возвращает группу, и любая добавленная в неё конечная точка отвечает на {group}.{endpoint}. Точка check в группе orders.inventory отвечает на orders.inventory.check, а reserve — на orders.inventory.reserve. Вы задаёте префикс один раз, а фреймворк соединяет его с именем каждой точки.
- CLI
- C
#!/bin/bash
# Organize endpoints under a group subject prefix.
#
# Grouping is a library call: AddGroup("orders.inventory") returns a
# group, and an endpoint named "check" added to that group answers on
# {group}.{endpoint} = orders.inventory.check. The CLI does not build
# groups; it sends to the subject the group produced. This snippet shows
# that the grouped endpoint answers on the joined subject, exactly as the
# other language tabs construct it.
# The grouped "check" endpoint answers on orders.inventory.check — the
# group prefix joined to the endpoint name. A caller only needs the
# subject; it never sees whether a group built it.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Read back the service to see each endpoint's resolved subject. The
# subject column shows orders.inventory.check, the group prefix applied.
nats service info OrderInventory
// A group captures the shared subject prefix once. Every endpoint
// added to the group answers on {group}.{endpoint}, so "check" ends
// up on orders.inventory.check without repeating the stem.
microGroup *inventory = NULL;
microGroupConfig groupConfig = {
.Prefix = "orders.inventory",
};
microEndpointConfig checkConfig = {
.Name = "check",
.Handler = onCheck,
};
if (err == NULL)
err = microService_AddGroup(&inventory, svc, &groupConfig);
if (err == NULL)
err = microGroup_AddEndpoint(inventory, &checkConfig);
Вызывающая сторона всегда отправляет запрос на {group}.{endpoint}. Отдельного слоя маршрутизации нет: группа лишь помогает составить субъект. Клиенту, знающему субъект, не нужно знать, добавлена конечная точка напрямую или через группу. Сетевой обмен одинаков в обоих случаях.
Группы могут быть вложенными. Группа внутри другой группы объединяет оба префикса, и субъект становится {outer}.{inner}.{endpoint}. Для сервиса такого размера редко нужен более чем один уровень, но префиксы складываются ожидаемым образом.
Группа может задавать группу очереди
Каждая конечная точка входит в группу очереди — группу балансировки нагрузки, благодаря которой сервер доставляет каждый запрос ровно одному участнику. Имя по умолчанию — "q"; вы уже использовали его без явной настройки: все экземпляры OrderInventory входят в "q", поэтому запрос получает один из них. Сам механизм объясняется в Core NATS; здесь это уже действующее значение по умолчанию для конечной точки сервиса.
Группа очереди задаётся на трёх уровнях, и каждый переопределяет предыдущий. Сервис устанавливает значение по умолчанию. Группа может переопределить его для всех своих конечных точек. Отдельная конечная точка может переопределить его ещё раз. Если значение нигде не задано, используется "q".
Группа очереди конечной точки переопределяется одним параметром. Здесь check входит в пользовательскую группу вместо стандартной "q":
- CLI
- C
#!/bin/bash
# Override the queue group on one endpoint.
#
# The queue group is a library setting on the endpoint: the option
# WithEndpointQueueGroup("q-inventory") makes "check" load-balance in
# its own group instead of the service default "q". The CLI does not set
# queue groups; it sends requests that the server delivers to one member
# of whatever group the endpoint joined. This snippet shows the observable
# result, the way the other language tabs configure the override.
# Send a request to the check endpoint. Whether check uses the default
# "q" or a custom queue group, the caller behavior is identical: the
# server delivers the request to exactly one instance in that group and
# one reply comes back.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Inspect the endpoint to confirm its queue group. The info output lists
# each endpoint with its subject and queue group, so you can verify the
# override took effect.
nats service info OrderInventory
// Override the queue group on one endpoint. Instead of the service
// default "q", check load-balances in its own group "q-inventory":
// instances sharing that group split check requests among themselves,
// separately from any other endpoint.
microEndpointConfig checkConfig = {
.Name = "check",
.Subject = "orders.inventory.check",
.QueueGroup = "q-inventory",
.Handler = onCheck,
};
if (err == NULL)
err = microService_AddEndpoint(svc, &checkConfig);
Большинству сервисов это не требуется. Стандартная группа "q" уже распределяет нагрузку между всеми экземплярами сервиса, что почти всегда и нужно. Переопределение полезно, только если часть конечных точек должна балансироваться отдельно. Полный набор параметров конечных точек и групп описан в справочнике. Здесь достаточно поведения.
Анимация выделяет правило маршрутизации. Один сервис содержит две конечные точки: check на orders.inventory.check и сгруппированную quote на shipping.quote. Субъект запроса выбирает обработчик: запрос к orders.inventory.check запускает check, запрос к shipping.quote — quote; работает лишь точка с совпадающим субъектом. В этой главе эти субъекты принадлежат разным сервисам, OrderInventory и ShippingQuote, но правило выбора такое же, когда один сервис содержит несколько конечных точек.
Подводные камни
У конечных точек и групп есть две распространённые ловушки: одна связана с группой очереди, другая — с необратимыми изменениями.
Отключение группы очереди делает конечную точку широковещательной. Переопределение группы меняет, кто с кем балансирует нагрузку. Полное отключение меняет поведение сильнее: конечная точка становится обычной подпиской, поэтому каждый экземпляр получает каждый запрос. Для конечной точки запросов и ответов это означает по одному ответу от каждого экземпляра, из которых лишние создают шум. Не отключайте группу, чтобы «запрос точно обработали»: именно это уже обеспечивает стандартная "q", с одним обработчиком вместо N. Отключайте её, только когда действительно нужно действие всех экземпляров, что редко требуется отвечающему сервису.
Этим управляет один параметр. Переопределяйте группу очереди, если часть конечных точек должна балансироваться отдельно; не отключайте её на отвечающей конечной точке. Отправьте запрос и проверьте, в какую группу вошла точка: стандартную "q", переопределённую или никакую:
- CLI
- C
#!/bin/bash
# Override the queue group on one endpoint.
#
# The queue group is a library setting on the endpoint: the option
# WithEndpointQueueGroup("q-inventory") makes "check" load-balance in
# its own group instead of the service default "q". The CLI does not set
# queue groups; it sends requests that the server delivers to one member
# of whatever group the endpoint joined. This snippet shows the observable
# result, the way the other language tabs configure the override.
# Send a request to the check endpoint. Whether check uses the default
# "q" or a custom queue group, the caller behavior is identical: the
# server delivers the request to exactly one instance in that group and
# one reply comes back.
nats service request OrderInventory check \
'{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
# Inspect the endpoint to confirm its queue group. The info output lists
# each endpoint with its subject and queue group, so you can verify the
# override took effect.
nats service info OrderInventory
// Override the queue group on one endpoint. Instead of the service
// default "q", check load-balances in its own group "q-inventory":
// instances sharing that group split check requests among themselves,
// separately from any other endpoint.
microEndpointConfig checkConfig = {
.Name = "check",
.Subject = "orders.inventory.check",
.QueueGroup = "q-inventory",
.Handler = onCheck,
};
if (err == NULL)
err = microService_AddEndpoint(svc, &checkConfig);
После добавления конечные точки неизменяемы. Операции удаления нет. Нельзя отсоединить точку, переименовать её или изменить субъект работающего сервиса. То же относится к метаданным сервиса и конечной точки: они фиксируются при создании. Для изменения структуры нужно остановить сервис и запустить новый с другой конфигурацией. Выбирайте имена и субъекты до запуска сервиса осознанно и сразу, как имя потока в JetStream.
Здесь помогает просмотр структуры. Прочитайте сведения работающего сервиса, чтобы увидеть зарегистрированные конечные точки, субъекты и группы очередей; для изменения остановите сервис и запустите замену:
- CLI
- C
#!/bin/bash
# Endpoints are fixed once a service is running — inspect, then restart to change.
#
# There is no library call to remove, rename, or re-subject an endpoint:
# AddEndpoint only appends, and the subject, queue group, and metadata are
# set at creation. The CLI cannot detach an endpoint either; it can only
# read the shape your code registered. This snippet shows how to inspect
# the running layout and confirms there is no remove operation — the way
# every language tab treats endpoints as immutable.
# Read back the service to see the exact endpoints it registered: each name,
# its resolved subject, and its queue group. This is the layout your code
# fixed at AddEndpoint time; nothing here can be edited in place.
nats service info OrderInventory
# There is no "nats service remove-endpoint" — endpoints cannot be detached
# from a running service. To change the shape, stop the service in your code
# (svc.Stop()) and start a new one with the new endpoint names and subjects.
nats service list
// Endpoints are immutable once added: there is no remove, rename, or
// re-subject on a running service. Read the shape back to see exactly
// which endpoints, subjects, and queue groups it registered.
microServiceInfo *info = NULL;
if (err == NULL)
err = microService_GetInfo(&info, svc);
if (err == NULL)
{
for (int i = 0; i < info->EndpointsLen; i++)
printf("endpoint %s on %s (queue group %s)\n",
info->Endpoints[i].Name,
info->Endpoints[i].Subject,
info->Endpoints[i].QueueGroup);
microServiceInfo_Destroy(info);
}
// To change the layout, stop the service and start a replacement
// with the new shape -- here check plus a new reserve endpoint.
microEndpointConfig reserveConfig = {
.Name = "reserve",
.Subject = "orders.inventory.reserve",
.Handler = onReserve,
};
microService *replacement = NULL;
if (err == NULL)
err = microService_Stop(svc);
if (err == NULL)
err = micro_AddService(&replacement, conn, &svcConfig);
if (err == NULL)
err = microService_AddEndpoint(replacement, &checkConfig);
if (err == NULL)
err = microService_AddEndpoint(replacement, &reserveConfig);
Текущее состояние
Теперь у вас есть:
- Два сервиса с одним
nats-server:OrderInventoryотвечает наorders.inventory.check, аShippingQuote— наshipping.quote. - Возможность добавлять конечные точки к каждому из них с субъектами, по умолчанию равными имени точки.
- Группа для общего префикса связанных конечных точек и три уровня задания группы очереди.
Оба сервиса по-прежнему делают то же, что их обработчики Core NATS. Добавилась структура: имена, субъекты и балансировка нагрузки фреймворка по умолчанию.
Что дальше
Работают два сервиса, каждый со своим именем и конечными точками. На следующей странице мы спросим систему, что в ней есть: команды обнаружения $SRV позволяют любому клиенту узнать о существующих сервисах, их конечных точках и отвечающих экземплярах.
Переходите к странице Обнаружение.
См. также
- Группы очередей — как работает группа балансировки под каждой конечной точкой.
- Scatter-gather — схема запросов, которую использовали поставщики ответов
ShippingQuoteдо превращения в именованный сервис. - Справочник — все параметры конфигурации конечных точек и групп.