6. Хранение состояния в Key-Value
Вы создадите бакет Key-Value, запишете значение, прочитаете его, а затем включите наблюдение за бакетом во втором терминале, чтобы видеть изменения сразу после их появления. В результате у вас будет небольшое хранилище актуального состояния, доступное для чтения, записи и наблюдения.
Что понадобится
- Установленные
nats-serverи CLInats(см. 1. Привет, NATS). - Бакет Key-Value работает поверх потока JetStream, поэтому на шаге 1 вы запустите сервер с включённым JetStream.
Шаг 1: запустите сервер с JetStream
Бакет Key-Value хранится в JetStream, поэтому запустите сервер с флагом -js.
nats-server -js
В журнале запуска должна появиться строка, подтверждающая включение JetStream:
[INF] Starting JetStream
[INF] Server is ready
Оставьте сервер работающим и откройте новый терминал для следующих шагов.
Шаг 2: создайте бакет
Создайте бакет profiles. В нём будут храниться ваши значения.
- CLI
- C
#!/bin/bash
# Создайте хранилище ключей и значений profiles. В нём будут храниться
# ваши значения.
nats kv add profiles
# Появится подтверждение с именем хранилища и его настройками:
#
# Information for Key-Value Store Bucket profiles created 2026-06-09 10:13:41
#
# Configuration:
#
# Bucket Name: profiles
# History Kept: 1
# ...
# Backing Store Kind: JetStream
// Create a Key-Value bucket called profiles. A bucket is where your
// values live.
kvConfig cfg;
kvConfig_Init(&cfg);
cfg.Bucket = "profiles";
s = js_CreateKeyValue(&kv, js, &cfg);
if (s == NATS_OK)
printf("Created bucket %s\n", kvStore_Bucket(kv));
Должно появиться подтверждение с конфигурацией бакета:
Information for Key-Value Store Bucket profiles created 2026-06-09 10:13:41
Configuration:
Bucket Name: profiles
History Kept: 1
...
Backing Store Kind: JetStream
Шаг 3: запишите и прочитайте значение
Сохраните значение по ключу, затем прочитайте его. Ключ — sue.color, значение — blue.
- CLI
- C
#!/bin/bash
# Запишите значение: ключ sue.color, значение blue.
nats kv put profiles sue.color blue
# Будут выведены записанное значение и его ревизия:
#
# blue
# Получите значение по ключу.
nats kv get profiles sue.color
# Будет выведена полная запись, включая значение:
#
# profiles > sue.color revision: 1 created @ ...
#
# blue
// Put a value: the key is sue.color, the value is blue. The bucket
// assigns the write a revision; the first write lands at 1.
uint64_t rev = 0;
kvEntry *e = NULL;
s = kvStore_PutString(&rev, kv, "sue.color", "blue");
if (s == NATS_OK)
printf("stored sue.color at revision %llu\n",
(unsigned long long) rev);
// Get the value back out by its key. A get returns the full entry:
// the value together with its revision.
if (s == NATS_OK)
s = kvStore_Get(&e, kv, "sue.color");
if (s == NATS_OK)
{
printf("sue.color revision: %llu value: %.*s\n",
(unsigned long long) kvEntry_Revision(e),
kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));
kvEntry_Destroy(e);
}
Операция записи выводит записанное значение, а чтение возвращает полную запись:
blue
profiles > sue.color revision: 1 created @ ...
blue
Теперь у вас есть одно сохранённое и проверенное значение.
Шаг 4: наблюдайте за бакетом из второго терминала
Наблюдение (watch) передаёт каждое изменение бакета по мере его появления. Откройте второй терминал и начните наблюдать за profiles.
- CLI
- C
#!/bin/bash
# Наблюдайте за всем хранилищем profiles. При запуске выводится текущее значение
# каждого ключа, затем команда ожидает изменения и выводит их до остановки
# сочетанием Ctrl-C. Запустите её в отдельном терминале.
nats kv watch profiles
# Сначала появится текущее значение, затем команда будет ожидать изменений:
#
# [2026-06-09 10:14:22] PUT profiles > sue.color: blue
// Watch the whole profiles bucket. The watch first replays the
// current value of every key, then delivers each change live the
// moment it lands.
kvEntry *e = NULL;
s = kvStore_WatchAll(&w, kv, NULL);
while (s == NATS_OK)
{
s = kvWatcher_Next(&e, w, 60000);
if (s != NATS_OK)
break;
// A NULL entry marks the end of the initial replay. Skip it
// and keep reading: everything after it is a live change.
if (e == NULL)
continue;
printf("PUT %s: %.*s\n", kvEntry_Key(e),
kvEntry_ValueLen(e), (const char*) kvEntry_Value(e));
kvEntry_Destroy(e);
e = NULL;
}
Сначала наблюдатель выводит текущее значение, затем ожидает:
[2026-06-09 10:14:22] PUT profiles > sue.color: blue
Оставьте наблюдение работающим. Вы настроили такую схему: приложение записывает значение, а наблюдатель сразу получает его.
Шаг 5: обновите значение и проверьте уведомление
Вернитесь в первый терминал и запишите новое значение по тому же ключу.
- CLI
- C
#!/bin/bash
# Запишите новое значение того же ключа. Обычная операция put перезаписывает
# предыдущее значение.
nats kv put profiles sue.color green
# Будет выведено новое значение:
#
# green
#
# В терминале с наблюдателем новая строка появится сразу после
# записи:
#
# [2026-06-09 10:15:03] PUT profiles > sue.color: green
// Put a new value for the same key. This is a normal put: it
// overwrites whatever was there, and the watcher in the other
// terminal sees the change the instant it lands.
uint64_t rev = 0;
s = kvStore_PutString(&rev, kv, "sue.color", "green");
if (s == NATS_OK)
printf("stored sue.color at revision %llu\n",
(unsigned long long) rev);
Операция записи возвращает новое значение:
green
Переключитесь в терминал наблюдения. Новая строка появляется сразу после изменения:
[2026-06-09 10:15:03] PUT profiles > sue.color: green
Когда закончите, остановите наблюдение с помощью Ctrl-C.
Что вы создали
У вас есть бакет Key-Value с актуальным состоянием: вы записали и прочитали значение, а наблюдатель во втором терминале получал каждое изменение сразу после его появления.
Дальше
- Итоговая работа: 7. Создание приложения — объедините публикацию и подписку, запрос и ответ и поток в одной программе.
- Узнайте, как это работает: углублённый курс Key-Value объясняет бакеты, ревизии, наблюдение и лежащий в основе поток.