Record (Запросы API) / Базовые настройки

Record — это встроенный класс в Nuxoblivius, отвечающий за работу с запросами. Он выполняет ту же роль, что и популярные клиенты вроде axios, но с учётом особенностей самого фреймворка.

Вместо того чтобы быть универсальной HTTP-библиотекой, Record тесно интегрирован с архитектурой Nuxoblivius:

упрощает работу с запросами и ответами внутри приложения;

поддерживает собственные механизмы обработки ошибок и статусов;

позволяет использовать единый стиль взаимодействия с данными, не выходя за рамки фреймворка.

Построение запроса

В Nuxoblivius запросы создаются через конструктор класса Record.new(). Метод принимает два аргумента:

Ссылка — адрес API, по которому будет выполняться запрос.

Значение по умолчанию — данные, которые будут возвращены в случае ошибки или при сбросе состояния.

Таким образом, Record всегда гарантирует наличие корректного значения:

если запрос завершился с ошибкой, будет подставлено значение по умолчанию;

если требуется очистить данные, они также сбрасываются в это значение.

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

Отправка запроса (Request)

Для выполнения HTTP-запросов в Nuxoblivius у объекта Record предусмотрены пять методов: .get(), .post(), .put(), .delete(), .patch().

Каждый из этих методов выполняет запрос и возвращает ответ сервера (Body Response).

Важно

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

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

const response = await posts.get();

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

const response = await posts.post();

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

const response = await posts.put();

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

const response = await posts.patch();

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

const response = await posts.delete();

Особенности методов

Каждый метод имеет сокращённые варианты передачи данных:

import { Record } from "nuxoblivius";

const post = Record.new("/api/posts/{id}", []);

// — может принимать id в качестве аргумента. Аналогично pathParam("id", value).
const response = await post.get(1);
// /api/post/1

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

// — принимает тело запроса. Аналогично вызову body(value).
const response = await posts.post({ message: "hello" });

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

// — принимает тело запроса. Аналогично вызову body(value).
const response = await posts.put({ message: "hello" });

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

// — принимает тело запроса. Аналогично вызову body(value).
const response = await posts.patch({ message: "hello" });

import { Record } from "nuxoblivius";

const post = Record.new("/api/posts/{id}", []);

// — может принимать id в качестве аргумента. Аналогично pathParam("id", value).
const response = await post.delete(1);
// /api/post/1

Обработка ответа от сервера (Response)

В Nuxoblivius результат запроса (Body Response) можно обрабатывать этими способами:

Непосредственно через возвращаемое значение функции — когда результат запроса используется сразу в месте вызова.

Через отдельную реактивную переменную response — когда требуется сохранить результат для дальнейшей работы.

Хук .onFinish() — позволяет задать обработчик, который сработает после успешного выполнения запроса. Больше информации о хуке onFinish

Через функцию вызоваЧерез свойствоЧерез хук

import { Record } from "nuxoblivius";

const posts = await Record.new("/api/posts", []).get();

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

await posts.get();

posts.response;

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.onFinish((posts, meta) => {
  console.log(posts);
});

Обработка ожидания ответа

У каждого Record в Nuxoblivius есть реактивное свойство loading, которое отражает текущее состояние запроса:

true — запрос выполняется;

false — запрос завершён (успешно или с ошибкой).

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

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

if (posts.loading) {
  console.log("В процессе");
}

Обработка ошибок

В Nuxoblivius ошибки можно отлавливать как во время выполнения запроса, так и после него. Для этого предусмотрены два механизма:

Хук .onFailure() — позволяет задать обработчик, который сработает при ошибке во время выполнения запроса. Больше информации о хуке onFailure;

Свойство error — указывает этот запрос произошёл с ошибкой, после выполнения запроса;

Общий обработчик SetRequestFailure - Аналог метода .onFailure() у Record. Больше информации о хуке SetRequestFailure

Через хукЧерез свойствоЧерез глобальный хук

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.onFailure((info, retry) => {
  console.error(info.response, "Ошибка");
  // Если нужно перезапустить запрос:
  return retry();
});

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

await posts.get();

if (posts.error) {
  console.error(posts.response);
}

import { Record, SetRequestFailure } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

SetRequestFailure((info, retry) => {
  console.error(info.response, "Ошибка");
  // Если нужно перезапустить запрос:
  return retry();
});

Чтение (Response Headers)

В Nuxoblivius прочитать заголовки ответа, можно через свойство headers:

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

// `headers` имеет тип Header
posts.headers.get("Content-Type");

Сброс тела ответа

В Record можно одной коммандой .clearResponse(), выставить значение по умолчанию, для переменной response

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.clearResponse();

Настройка Search Params (Query)

После создания объекта Record его можно модифицировать, добавляя search params к запросу. Для этого используется метод .query().

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.query({ name: "Greatest news!" });
// /api/posts?name=Greatest news!

Запекание параметров (значения по умолчанию)

Вторым аргументом метода .query() можно передать true. В этом случае параметры будут "запечены" — то есть они сохранятся даже после очистки данных и будут использоваться по умолчанию. При необходимости их можно перезаписать новыми значениями.

Нужно помнить

Последующие перезапекание, отменяют прошлые

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

// Указываем параметр по умолчанию
posts.query({ nsfw: "false" }, true);
// /api/posts?nsfw=false

// Перезаписываем значение
posts.query({ nsfw: "allow" });
// /api/posts?nsfw=allow

Очистка параметров

Запросы поддерживают сброс динамических параметров через метод .clearDynamicQuery(). При этом:

обычные параметры будут удалены,

"запечённые" параметры вернутся к своим исходным значениям.

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.query({ nsfw: "false" }, true);
// /api/posts?nsfw=false

posts.query({ nsfw: "allow", name: "Test 1" });
// /api/posts?nsfw=allow&name=Test 1

posts.clearDynamicQuery();
// /api/posts?nsfw=false

Динамические параметры

Если данные могут изменяться, их можно указать один раз, и при каждом запросе они будут обновлятся.

Через функциюRef объектReactive форма

import { Record } from "nuxoblivius";

var postRating = 5;

const posts = Record.new("/api/posts", []);

posts.query({
  rating: () => postRating,
});
// /api/posts?rating=5

postRating = 4;
// /api/posts?rating=4

import { Record } from "nuxoblivius";
import { shallowRef } from "vue";

var postRating = shallowRef(5);

const posts = Record.new("/api/posts", []);

posts.query({
  rating: postRating,
});
// /api/posts?rating=5

postRating.value = 4;
// /api/posts?rating=4

import { Record } from "nuxoblivius";
import { reactive } from "vue";

var postQuery = reactive({
  rating: 5,
});

const posts = Record.new("/api/posts", []);

posts.query(postQuery);
// /api/posts?rating=5

postQuery.rating = 4;
// /api/posts?rating=4

Настройка Path params (Динамический Path)

Помимо query-параметров, в Nuxoblivius можно использовать динамические сегменты пути (path params). Это позволяет гибко подставлять значения в URL без ручной конкатенации строк.

Чтобы задать динамический параметр, в шаблоне маршрута используйте фигурные скобки {}. Затем подставьте значение через метод .pathParam():

import { Record } from "nuxoblivius";

const post = Record.new("/api/posts/{id}", {});

post.pathParam("id", 1);
// Результат: /api/posts/1

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

Динамические параметры

Если данные могут изменяться, их можно указать один раз, и при каждом запросе они будут обновлятся.

Через функциюRef объект

import { Record } from "nuxoblivius";

var postId = 1;

const post = Record.new("/api/posts/{id}", {});

post.pathParam("id", () => postId);
// /api/posts/1

postId = 2;
// /api/posts/2

import { Record } from "nuxoblivius";
import { shallowRef } from "vue";

var postId = shallowRef(5);

const post = Record.new("/api/posts/{id}", {});

post.pathParam("id", postId);
// /api/posts/1

postId.value = 2;
// /api/posts/2

Настройка (Request Headers)

Для работы с заголовками в Nuxoblivius у объекта Record есть метод .header(). Он позволяет задавать или изменять значения HTTP-заголовков для запроса.

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.header("Language", "RU");
// Результат: Language: RU

Очистка заголовков

Чтобы удалить заголовок, достаточно передать null в качестве второго аргумента:

posts.header("Language", null);
// Заголовок "Language" удалён

Динамические параметры

Если данные могут изменяться, их можно указать один раз, и при каждом запросе они будут обновлятся.

Через функциюRef объект

import { Record } from "nuxoblivius";

var language = "RU";

const posts = Record.new("/api/posts", []);

posts.header("Language", () => language);
// Language: RU

language = "EN";
// Language: EN

import { Record } from "nuxoblivius";
import { shallowRef } from "vue";

var language = shallowRef("RU");

const posts = Record.new("/api/posts", []);

posts.header("Language", language);
// Language: RU

language.value = "EN";
// Language: EN

Глобальный хук `SetDefaultHeader()`

Так-же есть возможность выставить заголовок для всех Record, это полный аналог функции .header() у Record.

import { SetDefaultHeader } from "nuxoblivius";

SetDefaultHeader("Accept", "application/json");

Настройка Тела запроса (Request Body)

Для работы с телом запроса в Nuxoblivius у объекта Record есть метод .body(). Он позволяет задавать или изменять тело для запроса.

JSONFormData

import { Record } from "nuxoblivius";

const post = Record.new("/api/posts", []);

post.body({ title: "New post", content: "Some content" });
post.header("Content-Type", "application/json");

import { Record } from "nuxoblivius";

const post = Record.new("/api/posts", []);

post.body(new FormData());

Ожидать ответ типа Blob

В Record предусмотрен метод .isBlob(), который указывает, что от запроса следует ожидать ответ в формате Blob. Это удобно при работе с файлами (например, изображениями, документами или бинарными данными).

ВключитьВыключить

import { Record } from "nuxoblivius";

const file = await Record.new("/api/download", null);

file.isBlob();

import { Record } from "nuxoblivius";

const file = await Record.new("/api/download", null);

file.isBlob(false);

API хуков

Подробная информация о хука Record.

Хук `onFinish`

В Record доступен хук .onFinish(), который позволяет выполнить дополнительную логику после успешного завершения запроса.

Метод принимает функцию-обработчик с двумя аргументами:

responseBody — тело ответа.

meta — объект с дополнительной информацией:
2.1 fromCache — показывает, были ли данные получены из кэша;
2.2 oldResponse — предыдущее тело ответа (если оно существовало).

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.onFinish((responseBody, { fromCache, oldResponse }) => {
  console.log("Ответ:", responseBody);
  console.log("Из кэша:", fromCache);
  console.log("Предыдущий ответ:", oldResponse);
});

Хук `onFailure` / `SetRequestFailure`

В Record предусмотрен хук .onFailure() / SetRequestFailure(), который вызывается при возникновении ошибки во время выполнения запроса.

Метод принимает функцию-обработчик с двумя аргументами:

info — объект с информацией об ошибке:
1.1 text — текстовое описание или сообщение статуса;
1.2 code — код ответа (например, HTTP-статус);
1.3 response — тело ответа с ошибкой;
1.4 isAbort - является ли абортом;
1.5 abortCode - код аборта. (По умолчанию всегда -1)

retry — функция для повторного запуска запроса.

RecordГлобальный хук

import { Record } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

posts.onFailure(({ text, code, response }, retry) => {
  console.error("Ошибка:", text, "Код:", code);
  console.log("Ответ:", response);

  // Пример повторного запроса
  if (code === 500) {
    return retry();
  }
});

import { Record, SetRequestFailure } from "nuxoblivius";

const posts = Record.new("/api/posts", []);

SetRequestFailure(({ text, code, response }, retry) => {
  console.error("Ошибка:", text, "Код:", code);
  console.log("Ответ:", response);

  // Пример повторного запроса
  if (code === 500) {
    return retry();
  }
});

Установка

Store

Record (Запросы API) / Базовые настройки

Построение запроса

Отправка запроса (Request)

Особенности методов

Обработка ответа от сервера (Response)

Обработка ожидания ответа

Обработка ошибок

Чтение (Response Headers)

Сброс тела ответа

Настройка Search Params (Query)

Запекание параметров (значения по умолчанию)

Очистка параметров

Динамические параметры

Настройка Path params (Динамический Path)

Динамические параметры

Настройка (Request Headers)

Очистка заголовков

Динамические параметры

Глобальный хук `SetDefaultHeader()`

Настройка Тела запроса (Request Body)

Ожидать ответ типа Blob

API хуков

Хук `onFinish`

Хук `onFailure` / `SetRequestFailure`

Record (Запросы API) / Базовые настройки ​

Построение запроса ​

Отправка запроса (Request) ​

Особенности методов ​

Обработка ответа от сервера (Response) ​

Обработка ожидания ответа ​

Обработка ошибок ​

Чтение (Response Headers) ​

Сброс тела ответа ​

Настройка Search Params (Query) ​

Запекание параметров (значения по умолчанию) ​

Очистка параметров ​

Динамические параметры ​

Настройка Path params (Динамический Path) ​

Динамические параметры ​

Настройка (Request Headers) ​

Очистка заголовков ​

Динамические параметры ​

Глобальный хук SetDefaultHeader() ​

Настройка Тела запроса (Request Body) ​

Ожидать ответ типа Blob ​

API хуков ​

Хук onFinish ​

Хук onFailure / SetRequestFailure ​

Record (Запросы API) / Базовые настройки

Построение запроса

Отправка запроса (Request)

Особенности методов

Обработка ответа от сервера (Response)

Обработка ожидания ответа

Обработка ошибок

Чтение (Response Headers)

Сброс тела ответа

Настройка Search Params (Query)

Запекание параметров (значения по умолчанию)

Очистка параметров

Динамические параметры

Настройка Path params (Динамический Path)

Динамические параметры

Настройка (Request Headers)

Очистка заголовков

Динамические параметры

Глобальный хук `SetDefaultHeader()`

Настройка Тела запроса (Request Body)

Ожидать ответ типа Blob

API хуков

Хук `onFinish`

Хук `onFailure` / `SetRequestFailure`