# Ваш первый поток

Здесь мы создадим `ORDERS` одной командой CLI, затем рассмотрим его другой.

## Зачем нужен поток

Пример главы — небольшой интернет-магазин Acme `ORDERS`. Каждое событие заказа появляется сообщением в [теме](/concepts/subjects.md):

* `orders.created` — поступил заказ.
* `orders.shipped` — заказ отправлен со склада.
* `orders.canceled` — заказ отменён.

Сервисы реагируют на сообщения:

* Склад упаковывает заказ при `orders.created`.
* Уведомления отправляют письмо при `orders.shipped`.
* Аналитика считает все события.

Core NATS теряет сообщения, если никто их не слушает. **Поток** сохраняет их: это серверное хранилище сообщений выбранных тем. Их можно прочитать снова через минуты или месяц.

## Предварительные условия

Нужен `nats-server` с JetStream. Если его ещё нет:

```
nats-server -js
```

Флаг `-js` включает JetStream. Без него следующая команда не сработает.

## Создайте поток

В другом терминале:

#### CLI

```
#!/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
```

#### JavaScript/TypeScript

```
// 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}`);
```

#### Go

```
// 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)
```

#### Python

```
# 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}")
```

#### Java

```
// 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());
```

#### Rust

```
// 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);
```

#### C#/.NET

```
// 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}");
```

#### C

```
// 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.>`, фильтр с [подстановочным знаком](/concepts/subjects.md#wildcards). Подходят все темы под `orders.`: `orders.created`, `orders.shipped`, `orders.canceled` и будущая `orders.refunded` без изменения потока.

`--defaults` отключает вопросы остальных настроек. Сервер заполняет стандартные значения; скоро мы их рассмотрим. Пока они подходят.

Вывод должен завершиться примерно так:

```
Stream ORDERS was created
```

Ошибка `no responders available for request` означает, что сервер запущен без `-js`: JetStream не отвечает. Перезапустите с флагом и повторите.

## Проверка созданного потока

Посмотрите результат:

#### CLI

```
#!/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
```

#### JavaScript/TypeScript

```
// 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}`);
```

#### Go

```
// 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)
```

#### Python

```
# 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}")
```

#### Java

```
// 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());
```

#### Rust

```
// 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);
```

#### C#/.NET

```
// 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}");
```

#### C

```
// 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**. Одна копия на одном сервере; его отказ делает поток недоступным. Для ноутбука подходит, для эксплуатации рискованно. См. [Отказ узла](/learn/jetstream/surviving-node-loss.md).
* **Storage: File**. Запись на диск. Память быстрее, но теряется при перезапуске.
* **Retention: Limits**. Хранение до ограничений размера, возраста или количества. `Interest` и `WorkQueue` удаляют сообщения по мере обработки потребителями; см. [Политики хранения](/learn/jetstream/retention-policies.md).
* **Discard Policy: Old**. При достижении предела удаляются старые сообщения. Вариант `New` отклоняет новые.
* **Maximum Messages / Bytes / Age / Message Size: unlimited**. Верхних пределов нет. При эксплуатации задавайте хотя бы один; см. [Настройка потока](/learn/jetstream/shaping-the-stream.md).
* **Duplicate Window: 2m0s**. Две минуты после записи сервер не сохраняет повтор с тем же заголовком [`Nats-Msg-Id`](/reference/jetstream/api/headers.md). Это позволяет повторить публикацию без второй копии. См. [Публикация](/learn/jetstream/publishing.md).

Все настройки перечислены в [Справочнике → Создание потока](/reference/jetstream/api/stream/create.md). Здесь используются стандартные.

## Тема привязывается только к одному потоку

Одну тему может сохранять только один поток. Создание второго с пересечением `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 всегда однозначно определяет поток для поступившего сообщения.

Для перекрывающихся данных существуют **зеркала** и **источники**. Зеркало копирует другой поток, источники собирают несколько в один. Здесь они пока не нужны. [Зеркала и источники](/learn/jetstream/mirrors-and-sources.md) создают оба варианта, а [Справочник → Создание потока](/reference/jetstream/api/stream/create.md) описывает `mirror` и `sources`.

## Типичные ошибки

При создании первого потока учтите следующее.

**Неограниченные значения допускают бесконечный рост.** С `--defaults` ограничения `Maximum Messages`, `Maximum Bytes` и `Maximum Age` равны `unlimited`. ORDERS растёт до заполнения диска, что может остановить сервер. Для обучения это допустимо, но рабочему потоку нужен хотя бы один предел. Его настройка разобрана в [Настройке потока](/learn/jetstream/shaping-the-stream.md); здесь границы намеренно не заданы.

**Имя потока постоянно.** Переименования нет: у `nats stream edit` отсутствует `--name`, изменение имени отклоняется с `stream configuration name must match original`. Удаление и пересоздание теряет сообщения. Выбирайте имя заранее. При необходимости перехода безопаснее создать новый поток с новыми темами, оставив старый до естественного удаления данных.

## Что уже готово

Теперь у вас есть:

* Поток `ORDERS` для `orders.>`.
* Ноль сообщений.
* Конфигурация со стандартными значениями.

Следующая страница, [Публикация](/learn/jetstream/publishing.md), отправляет первые сообщения и показывает ответ сервера.

## См. также

* [Справочник → Создание потока](/reference/jetstream/api/stream/create.md) — все настройки и диапазоны.
* [Справочник → API JetStream](/reference/jetstream/api/.md) — операции потоков и потребителей.
