Куда двигаться дальше
Вы начали главу с обработчика запросов и ответов, написанного вручную: подписчик на orders.inventory.check читал запрос и публиковал ответ. Теперь у вас OrderInventory — именованный сервис с версией, отвечающий на тот же субъект, объявляющий себя через $SRV, считающий запросы и распределяющий нагрузку между любым числом экземпляров. Сетевое поведение не изменилось; фреймворк добавил всё вокруг него.
Эта страница не вводит новых понятий. Она собирает построенную модель в одном месте и направляет к главам и справочнику для дальнейшего изучения.
Основная идея
Каждая страница главы возвращалась к одной идее; повторим её отдельно.
Сервис — обработчик запросов и ответов, оформленный средствами фреймворка. Вы передаёте имя и версию, а он генерирует уникальный идентификатор сервиса, подписывается на команды обнаружения и ведёт статистику. Знакомый обработчик теперь обладает идентичностью.
Конечная точка — именованный обработчик на субъекте, а группа — пространство имён с префиксом субъектов, упорядочивающее конечные точки. Один сервис может предоставлять много точек; группа заставляет их отвечать на {prefix}.{endpoint}. Так один работающий сервис обслуживает несколько субъектов.
Три команды обнаружения под $SRV (PING, INFO и STATS) обеспечивают обнаружение и наблюдение без дополнительной настройки. Запросите $SRV.INFO, и каждый подходящий экземпляр сообщит конечные точки; запросите $SRV.STATS — получите его счётчики.
Стандартная группа очереди "q" масштабирует сервис. Запустите больше экземпляров с тем же именем и версией, и сервер доставит каждый запрос ровно одному. Координатор и конфигурация не нужны: масштаб увеличивается запуском экземпляров.
Это четыре составляющие: сервис, конечные точки и группы, обнаружение и группа очереди. Остальное в главе уточняет их работу.
Где искать справочные подробности
Эта глава не привязана к версии и прежде всего объясняет понятия. Точные поля конфигурации, допустимые диапазоны и сетевой формат команд обнаружения находятся в полном справочнике, разделённом по версиям. Там ищите точный тип поля конфигурации сервиса, полный список параметров конечной точки или схему JSON ответа INFO.
Начните с корня справочника. Ссылки по всей главе вроде «полный набор полей конфигурации сервиса приведён в справочнике» ведут туда. Сетевой формат $SRV и схемы ответов PING, INFO и STATS находятся в справочнике сервисов.
Связанные подробные главы
Сервис построен на механизмах, полностью описанных в других главах, и оставляет задачи, которые решаются там. Выберите главу под текущий вопрос.
Подробная глава о Core NATS описывает нижний слой. Запросы и ответы используются каждой конечной точкой, а группы очередей обеспечивают ту самую балансировку стандартной группы "q". Если здесь какой-то шаг казался пропущенным, он рассмотрен там.
Подробная глава о JetStream нужна, когда сервис должен что-то помнить. Сервис использует запросы и ответы с доставкой не более одного раза: он ничего не хранит, и при остановке экземпляра незавершённая работа теряется. Как только обработчику требуется долговременное состояние, например заказ, переживающий перезапуск, его место в потоке, а не в сервисе.
Глава об устойчивых клиентах рассматривает соединение каждого экземпляра: переподключение, drain помимо Stop() фреймворка, обработку медленных потребителей и обратные вызовы ошибок. Здесь предполагалось исправное локальное соединение; в эксплуатации оно не всегда исправно.
Глава о безопасности объясняет изоляцию субъектов $SRV, управление доступом аккаунтов и размещение сервисов между аккаунтами.
Глава о мониторинге переходит от статистики конечных точек к представлению на стороне сервера: экспорту метрик в Prometheus и панелям, сообщающим о замедлении сервиса до жалобы клиента. Схема уведомления о задержке сервиса находится в справочнике.
Глава о топологиях рассматривает сервисы на нескольких серверах: распространение $SRV и субъектов сервисов через листовые узлы и шлюзы, а также размещение экземпляров в разных регионах.
Текущее состояние
Глава завершена; новых изменений в сценарии здесь нет. Ваш OrderInventory с конечной точкой check на orders.inventory.check и ShippingQuote с точкой quote на shipping.quote по-прежнему работают в сеансе, как на предыдущей странице, и балансируют нагрузку между запущенными экземплярами. Продолжайте эксперименты или корректно остановите их по завершении: каждый Stop() завершает текущие запросы и отменяет подписки обнаружения.
У вас есть основная модель: сервис — именованный обработчик запросов и ответов с версией и обнаружением; конечные точки и группы задают его структуру; команды $SRV обеспечивают обнаружение и наблюдение; группа очереди — масштабирование. На этой модели строится дальнейшая работа с фреймворком.
Проверки перед эксплуатацией
Каждая страница завершалась разделом с подводными камнями. Здесь собраны необходимые действия перед тем, как доверить сервису реальные заказы. Каждая группа ссылается на страницу с объяснением причин.
Первый сервис — см. Подводные камни
- Разбирайте
req.Data()внутри обработчика и возвращайте ошибку сервиса при неверных данных, не допуская сбоя обработчика из-за некорректного запроса. - Выберите
Nameс допустимыми символами иVersionв формате SemVer: неверное значение сразу препятствует созданию сервиса.
Конечные точки и группы — см. Подводные камни
- Переопределяйте группу очереди точки, только если намерены изменить состав участников балансировки: изменение происходит незаметно, и ошибиться легко.
- Помните, что отключение группы очереди включает широковещательную доставку (отвечают все экземпляры) вместо балансировки.
- Считайте конечные точки и метаданные неизменяемыми после добавления: удаления нет, поэтому сразу выбирайте имена и структуру осознанно.
Обнаружение — см. Подводные камни
- Собирайте ответы обнаружения в цикле до заданного срока или числа ответов: обнаружение широковещательное, а обычный одиночный запрос вернёт только один экземпляр.
- Считайте
$SRVзарезервированным префиксом субъектов; не публикуйте туда собственные сообщения, чтобы не мешать управляющему обмену фреймворка.
Наблюдаемость — см. Подводные камни
- Проверяйте
Nats-Service-Error-Codeв каждом ответе: ошибка сервиса передаётся в заголовках, а не как транспортный сбой, поэтому без проверки ошибочный вызов выглядит успешным. - Самостоятельно агрегируйте статистику разных идентификаторов экземпляров; счётчики ведутся отдельно, а
Reset()обнуляет их.
Масштабирование — см. Подводные камни
- Защищайте внешнее состояние, общее для экземпляров (базу данных или поток), и не предполагайте единственность экземпляра: фреймворк не предоставляет общей памяти.
- Делайте обработчики неблокирующими или запускайте больше экземпляров: блокирующий обработчик задерживает все другие запросы своего экземпляра.
См. также
- Справочник — все поля конфигурации сервисов, параметры конечных точек и сетевые схемы
$SRV, полно и с разделением по версиям. - Подробная глава о Core NATS — запросы и ответы и группы очередей, на которых построена эта глава.
- Подробная глава о JetStream — хранение состояния сервиса, которое должно пережить перезапуск.