Ваш первый поток
Здесь мы создадим ORDERS одной командой CLI, затем рассмотрим его другой.
Зачем нужен поток
Пример главы — небольшой интернет-магазин Acme ORDERS. Каждое событие заказа появляется сообщением в теме:
orders.created— поступил заказ.orders.shipped— заказ отправлен со склада.orders.canceled— заказ отменён.
Сервисы реагируют на сообщения:
- Склад упаковывает заказ при
orders.created. - Уведомления отправляют письмо при
orders.shipped. - Аналитика считает все события.
Core NATS теряет сообщения, если никто их не слушает. Поток сохраняет их: это серверное хранилище сообщений выбранных тем. Их можно прочитать снова через минуты или месяц.
Предварительные условия
Нужен nats-server с JetStream. Если его ещё нет:
nats-server -js
Флаг -js включает JetStream. Без него следующая команда не сработает.
Создайте поток
В другом терминале:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Create the ORDERS stream, capturing every subject under orders.>
# --defaults fills in the remaining config with sensible starting values.
nats stream add ORDERS --subjects "orders.>" --defaults
# Expected: output ending with
# Stream ORDERS was created
// Get a JetStream manager and create the ORDERS stream, which captures
// every Acme order subject under `orders.`
const jsm = await jetstreamManager(nc);
const info = await jsm.streams.add({
name: "ORDERS",
subjects: ["orders.>"],
});
console.log(`Created stream: ${info.config.name}`);
// Create the ORDERS stream, capturing every subject under 'orders.>'.
stream, err := js.CreateStream(ctx, jetstream.StreamConfig{
Name: "ORDERS",
Subjects: []string{"orders.>"},
})
if err != nil {
panic(err)
}
// Confirm the stream was created.
fmt.Printf("Created stream: %s\n", stream.CachedInfo().Config.Name)
# Create the "ORDERS" stream, capturing every subject under "orders.".
info = await js.add_stream(name="ORDERS", subjects=["orders.>"])
# Confirm success by printing the stream name the server returned.
print(f"Created stream: {info.config.name}")
// Create a stream named "ORDERS" that captures any subject under `orders.`
JetStreamManagement jsm = nc.jetStreamManagement();
StreamInfo streamInfo = jsm.addStream(StreamConfiguration.builder()
.name("ORDERS")
.subjects("orders.>")
.storageType(StorageType.File)
.build());
// Confirm the stream was created
System.out.println("Created stream: " + streamInfo.getConfiguration().getName());
// Create the ORDERS stream, capturing every subject under `orders.`.
let stream = js
.create_stream(jetstream::stream::Config {
name: "ORDERS".to_string(),
subjects: vec!["orders.>".to_string()],
storage: StorageType::File,
..Default::default()
})
.await?;
// Confirm success by printing the name the server assigned.
println!("Created stream: {}", stream.cached_info().config.name);
// Create the ORDERS stream, capturing every subject under `orders.`
var stream = await js.CreateStreamAsync(new StreamConfig(name: "ORDERS", subjects: ["orders.>"]));
// Confirm the stream was created
output.WriteLine($"Created stream: {stream.Info.Config.Name}");
// Create the ORDERS stream, capturing every subject under 'orders.>'.
jsStreamConfig cfg;
const char *subjects[] = {"orders.>"};
jsStreamConfig_Init(&cfg);
cfg.Name = "ORDERS";
cfg.Subjects = subjects;
cfg.SubjectsLen = 1;
s = js_AddStream(&si, js, &cfg, NULL, &jerr);
if (s == NATS_OK)
{
// Confirm the stream was created.
printf("Created stream: %s\n", si->Config->Name);
}
В команде важны две части.
Первая — имя потока ORDERS. Регистр учитывается. Точки, *, >, пробелы и косые черты запрещены, поэтому orders.created не подходит. Имя встретится во всех командах и ошибках главы.
Вторая — сохраняемые темы orders.>, фильтр с подстановочным знаком. Подходят все темы под orders.: orders.created, orders.shipped, orders.canceled и будущая orders.refunded без изменения потока.
--defaults отключает вопросы остальных настроек. Сервер заполняет стандартные значения; скоро мы их рассмотрим. Пока они подходят.
Вывод должен завершиться примерно так:
Stream ORDERS was created
Ошибка no responders available for request означает, что сервер запущен без -js: JetStream не отвечает. Перезапустите с флагом и повторите.
Проверка созданного потока
Посмотрите результат:
- CLI
- JavaScript/TypeScript
- Go
- Python
- Java
- Rust
- C#/.NET
- C
#!/bin/bash
# Inspect the stream: its configuration (what you asked for plus the
# defaults the server filled in) and its state (what's stored right now).
nats stream info ORDERS
// Get a JetStream manager and look up the ORDERS stream, then print the
// key fields from its configuration and current state
const jsm = await jetstreamManager(nc);
const info = await jsm.streams.info("ORDERS");
console.log(`Stream: ${info.config.name}`);
console.log(`Subjects: ${info.config.subjects?.join(", ")}`);
console.log(`Messages: ${info.state.messages}`);
// Look up the ORDERS stream and fetch its latest info from the server.
stream, err := js.Stream(ctx, "ORDERS")
if err != nil {
panic(err)
}
info, err := stream.Info(ctx)
if err != nil {
panic(err)
}
// Print key fields: name, captured subjects, and current message count.
fmt.Printf("Name: %s\n", info.Config.Name)
fmt.Printf("Subjects: %v\n", info.Config.Subjects)
fmt.Printf("Messages: %d\n", info.State.Msgs)
# Fetch the latest information about the "ORDERS" stream.
info = await js.stream_info("ORDERS")
# Print key fields: name and subjects come from the config,
# the live message count comes from the stream state.
print(f"Stream: {info.config.name}")
print(f"Subjects: {info.config.subjects}")
print(f"Messages: {info.state.messages}")
// Fetch info for the "ORDERS" stream and print key fields
StreamInfo streamInfo = jsm.getStreamInfo("ORDERS");
StreamConfiguration config = streamInfo.getConfiguration();
StreamState state = streamInfo.getStreamState();
System.out.println("Name: " + config.getName());
System.out.println("Subjects: " + config.getSubjects());
System.out.println("Messages: " + state.getMsgCount());
// Fetch the ORDERS stream and read its current info from the server.
let mut stream = js.get_stream("ORDERS").await?;
let info = stream.info().await?;
// Print the key fields: name, captured subjects, and message count.
println!("Stream name: {}", info.config.name);
println!("Subjects: {:?}", info.config.subjects);
println!("Message count: {}", info.state.messages);
// Fetch information about the ORDERS stream
var stream = await js.GetStreamAsync("ORDERS");
// Read key fields: name and subjects come from the config, the
// message count comes from the live stream state
var info = stream.Info;
var subjects = string.Join(", ", info.Config.Subjects ?? []);
output.WriteLine($"Name: {info.Config.Name}");
output.WriteLine($"Subjects: {subjects}");
output.WriteLine($"Messages: {info.State.Messages}");
// Look up the ORDERS stream and fetch its latest info from the server.
s = js_GetStreamInfo(&si, js, "ORDERS", NULL, &jerr);
if (s == NATS_OK)
{
int i;
// Print key fields: name, captured subjects, and current message count.
printf("Name: %s\n", si->Config->Name);
printf("Subjects:");
for (i = 0; i < si->Config->SubjectsLen; i++)
printf(" %s", si->Config->Subjects[i]);
printf("\n");
printf("Messages: %" PRIu64 "\n", si->State.Msgs);
}
Вывод состоит из двух частей.
Конфигурация содержит заданные и стандартные значения: заголовок, разделы Options и Limits:
Information for Stream ORDERS
Subjects: orders.>
Replicas: 1
Storage: File
Options:
Retention: Limits
Acknowledgments: true
Discard Policy: Old
Duplicate Window: 2m0s
Limits:
Maximum Messages: unlimited
Maximum Per Subject: unlimited
Maximum Bytes: unlimited
Maximum Age: unlimited
Maximum Message Size: unlimited
Maximum Consumers: unlimited
В Options также есть Direct Get и переключатели Allows …. CLI по умолчанию включает прямое чтение, библиотеки — только по явной настройке. Здесь строки сокращены; возможности будут разобраны далее.
Состояние показывает текущее содержимое:
State:
Messages: 0
Bytes: 0 B
First Sequence: 0
Last Sequence: 0
Active Consumers: 0
Новый поток пуст: ноль сообщений и байтов, нет потребителей. Первое сообщение получит номер 1.
Значения по умолчанию
Вы не задавали перечисленные параметры. Сервер заполнил их стандартными значениями для незаданных полей. Их смысл:
- Replicas: 1. Одна копия на одном сервере; его отказ делает поток недоступным. Для ноутбука подходит, для эксплуатации рискованно. См. Отказ узла.
- Storage: File. Запись на диск. Память быстрее, но теряется при перезапуске.
- Retention: Limits. Хранение до ограничений размера, возраста или количества.
InterestиWorkQueueудаляют сообщения по мере обработки потребителями; см. Политики хранения. - Discard Policy: Old. При достижении предела удаляются старые сообщения. Вариант
Newотклоняет новые. - Maximum Messages / Bytes / Age / Message Size: unlimited. Верхних пределов нет. При эксплуатации задавайте хотя бы один; см. Настройка потока.
- Duplicate Window: 2m0s. Две минуты после записи сервер не сохраняет повтор с тем же заголовком
Nats-Msg-Id. Это позволяет повторить публикацию без второй копии. См. Публикация.
Все настройки перечислены в Справочнике → Создание потока. Здесь используются стандартные.
Тема привязывается только к одному потоку
Одну тему может сохранять только один поток. Создание второго с пересечением orders.> отклоняется:
nats stream add ARCHIVE --subjects "orders.*" --defaults
nats: error: could not create Stream: subjects overlap with an existing stream (10065)
Проверяется любое пересечение: orders.* и даже одна orders.created тоже конфликтуют с ORDERS.
Так JetStream всегда однозначно определяет поток для поступившего сообщения.
Для перекрывающихся данных существуют зеркала и источники. Зеркало копирует другой поток, источники собирают несколько в один. Здесь они пока не нужны. Зеркала и источники создают оба варианта, а Справочник → Создание потока описывает mirror и sources.
Типичные ошибки
При создании первого потока учтите следующее.
Неограниченные значения допускают бесконечный рост. С --defaults ограничения Maximum Messages, Maximum Bytes и Maximum Age равны unlimited. ORDERS растёт до заполнения диска, что может остановить сервер. Для обучения это допустимо, но рабочему потоку нужен хотя бы один предел. Его настройка разобрана в Настройке потока; здесь границы намеренно не заданы.
Имя потока постоянно. Переименования нет: у nats stream edit отсутствует --name, изменение имени отклоняется с stream configuration name must match original. Удаление и пересоздание теряет сообщения. Выбирайте имя заранее. При необходимости перехода безопаснее создать новый поток с новыми темами, оставив старый до естественного удаления данных.
Что уже готово
Теперь у вас есть:
- Поток
ORDERSдляorders.>. - Ноль сообщений.
- Конфигурация со стандартными значениями.
Следующая страница, Публикация, отправляет первые сообщения и показывает ответ сервера.
См. также
- Справочник → Создание потока — все настройки и диапазоны.
- Справочник → API JetStream — операции потоков и потребителей.