Куда двигаться дальше
Глава началась с потока 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>; имя с:или двумя точками подряд отклоняется.
См. также
- Справочник — все поля, флаги, значения по умолчанию и коды ошибок, полно и с разделением по версиям.
- Глава о хранилище объектов — следующий шаг для значений, слишком больших для бакета.
- Углублённый курс JetStream — потоковая основа всех возможностей KV.