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

Куда двигаться дальше

Глава началась с потока JetStream и утверждения, что NATS предоставляет поверх него хранилище ключей и значений. Теперь у вас бакет INVENTORY: ключи-артикулы, значения-остатки, складская панель с наблюдением, безопасное уменьшение через сравнение с заменой, автоматически истекающий ключ и понятное устройство базового потока.

Здесь построенная модель собрана в одном месте со ссылками на главы и справочник для дальнейшего изучения.

Соответствие KV и JetStream​

Каждая страница возвращалась к одной идее: бакет — поток с интерфейсом ключей и значений. Важно помнить соответствие терминов KV и JetStream.

Бакет — поток. При создании INVENTORY появляется поток KV_INVENTORY с темами $KV.INVENTORY.>. Каждый лимит бакета — глубина истории, число байтов, размер значения — является лимитом потока.

Ключ — токен темы. widget-blue — последний токен $KV.INVENTORY.widget-blue. Фильтр ключей наблюдателя — фильтр тем, где * соответствует одному полному токену.

Put — сообщение. Каждое записанное значение добавляет сообщение в поток, а get читает последнее сообщение этой темы.

Ревизия — порядковый номер. Каждый put увеличивает ревизию ключа, поскольку сообщение получает следующий номер в потоке. История — прежние сообщения этой темы, ещё хранящиеся в потоке.

Watch — потребитель. Временный упорядоченный потребитель воспроизводит текущее значение каждого подходящего ключа, затем передаёт текущие изменения.

Бакет соответствует потоку, ключ — теме, put — сообщению, ревизия — порядковому номеру, watch — потребителю. Остальные возможности главы уточняют это соответствие.

Где искать подробности​

Глава не привязана к версии и прежде всего объясняет понятия. Точные флаги, значения по умолчанию и диапазоны приведены в полном справочнике с разделением по версиям. Там ищите точный тип поля или полный набор параметров бакета.

Поскольку бакет создаётся как поток, основной перечень настроек — справочник создания потока. Все параметры бакета описаны в разделе Справочник → Создание потока, а путь прямого чтения — в разделе Справочник → Получение сообщения потока.

Связанные подробные главы​

KV построено на JetStream, поэтому модель потока напрямую связывает его с соседними главами.

Углублённый курс JetStream описывает нижний слой. Когда здесь говорилось «это лимит потока» или «watch — потребитель», полное объяснение механизма находится там: зачем нужен поток, политики хранения и TTL сообщений, на котором построен TTL ключей.

Глава о хранилище объектов нужна, когда значение перерастает бакет. Значения KV небольшие и ограничены; хранилище объектов предназначено для крупных данных, собираемых при чтении из нескольких сообщений. Для файла, артефакта сборки или многомегабайтных данных начните с первого объекта.

Глава о кластеризации и репликации раскрывает поле Replicas, упомянутое при изучении устройства. Она объясняет, как бакет переживает отказ узла и какие механизмы репликации стоят за этим полем.

Есть и другое направление: бакет может получать данные из другого бакета или зеркалироваться. Например, региональный EU_INVENTORY получает данные из INVENTORY; одинаковые ключи поддерживаются преобразованием тем $KV.SRC.> в $KV.DST.>. Здесь это не создаётся, поскольку механизм относится к JetStream; см. Зеркала и источники.

Текущее состояние​

Глава завершена; нового состояния сценария здесь нет. Бакет INVENTORY, наблюдатель, история и ключ flash-sale остаются в сеансе, как на странице внутреннего устройства. Можно продолжать эксперименты или по завершении удалить бакет командой nats kv rm INVENTORY.

У вас есть основная модель: бакет — поток, ключ — токен темы, put — сообщение, ревизия — порядковый номер, watch — потребитель. На этом соответствии основаны все возможности KV.

Проверки перед эксплуатацией​

Каждая страница завершалась разделом с подводными камнями. Здесь собраны необходимые действия перед использованием бакета для настоящего складского учёта. Каждая группа ссылается на объяснение причин.

Первый бакет — см. Подводные камни​

  • Проверяйте наличие записи до чтения значения: отсутствие ключа отличается от пустого значения, а чтение несуществующей записи приводит к ошибке.
  • Используйте в именах бакетов только буквы, цифры, дефисы и подчёркивания: сервер отклоняет остальное.
  • Используйте в ключах только буквы, цифры и -/_=., без точки в начале или конце; идентификатор с : или начальной точкой отклоняется.

Наблюдение — см. Подводные камни​

  • Обрабатывайте nil завершения начальных данных: не завершайте цикл на границе снимка, иначе пропустите все текущие обновления.
  • Считайте наблюдение живым состоянием, а не запросом: временный потребитель заканчивается с процессом; для точечного чтения используйте get или history.

История и ревизии — см. Подводные камни​

  • Оборачивайте update циклом повторного чтения и попытки: обновление устаревшей ревизии отклоняется, а не ставится в очередь; без повтора запись теряется.
  • Для чтения, изменения и записи, например уменьшения остатка, используйте update со сравнением с заменой: безусловный put затирает одновременную запись.

TTL и лимиты — см. Подводные камни​

  • Задавайте TTL ключа только при create. Передача TTL в put или update его не меняет; для изменения удалите ключ и создайте заново.
  • Рассчитывайте бакет на рабочий набор, а не среднюю нагрузку: при достижении лимита байтов следующий put отклоняется с ошибкой, а не удаляет старые значения.

Внутреннее устройство — см. Подводные камни​

  • Для реального удаления прежних ревизий используйте purge: delete оставляет маркер и сохраняет историю.
  • Используйте KV API вместо прямой публикации nats pub в $KV.INVENTORY.> или ручных правок KV_INVENTORY: поток управляется API, заголовки свёртки и маркеров должны оставаться корректными.
  • Соблюдайте правила токенов тем: ключ становится последней частью $KV.INVENTORY.<key>; имя с : или двумя точками подряд отклоняется.

См. также​