import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/functional-basic/Classes/Api - Управление запросами (Static)'/>

# Класс Api

Класс `Api` является **основным классом (статическим)** и служит главной точкой входа для управления HTTP-запросами. Он представляет собой статическую обертку над глобально управляемым `ApiInstance`, предоставляя чистый интерфейс на основе синглтона для стандартных сетевых операций.

## Ключевые особенности

- **Статический интерфейс** — выполнение стандартных HTTP-операций (`GET`, `POST` и т. д.) без необходимости ручного создания экземпляров.
- **Глобальные хуки жизненного цикла** — настройте подготовку и анализ запросов один раз для всего приложения.
- **Изоляция в SSR** — использует `ServerStorage` для управления изоляцией отдельных экземпляров во время рендеринга на стороне сервера.
- **Упрощенная настройка** — предоставляет унифицированный метод `setConfig` для одновременного применения нескольких слоев конфигурации.

## Методы

### Действие

Методы для выполнения физических сетевых запросов.

- `request<T>(pathRequest: string | ApiFetch): Promise<T>` — Основной исполнитель; принимает строку пути или объект конфигурации.
- `get<T>(request: ApiFetch): Promise<T>` — Отправляет GET-запрос.
- `post<T>(request: ApiFetch): Promise<T>` — Отправляет POST-запрос.
- `put<T>(request: ApiFetch): Promise<T>` — Отправляет PUT-запрос.
- `patch<T>(request: ApiFetch): Promise<T>` — Отправляет PATCH-запрос.
- `delete<T>(request: ApiFetch): Promise<T>` — Отправляет DELETE-запрос.

### Проверка

- `isLocalhost(): boolean` — Проверяет, запущена ли среда на локальном сервере разработки.

### Конфигурация

- `setUrl(url: string): void` — Изменяет базовый URL API.
- `setHeaders(headers: Record<string, string>): void` — Устанавливает заголовки запроса по умолчанию.
- `setRequestDefault(request: Record<string, any>): void` — Устанавливает данные тела запроса по умолчанию.
- `setPreparation(callback): void` — Регистрирует хук, запускаемый перед каждым включенным запросом.
- `setEnd(callback): void` — Регистрирует хук, запускаемый после каждого включенного ответа.
- `setTimeout(timeout: number): void` — Изменяет глобальный таймаут запроса.
- `setOrigin(origin: string): void` — Изменяет источник (протокол и домен) для базового URL.
- `setConfig(config?: ApiConfig): void` — Применяет полный объект конфигурации.

### Вспомогательные

- `getStatus(): ApiStatus` — Доступ к менеджеру статуса последнего запроса.
- `getResponse(): ApiResponse` — Доступ к менеджеру ответов/эмуляции.
- `getHydration(): ApiHydration` — Доступ к менеджеру гидратации.
- `getHydrationScript(): string` — Возвращает блок скрипта для гидратации SSR-клиент.
- `getOrigin(): string` — Возвращает базовый URL источника, объединенный с путем API.
- `getUrl(path: string, api?: boolean): string` — Возвращает полностью разрешенный URL с подстановкой плейсхолдеров `{locale}`, `{country}`, `{language}`.
- `getBody(request?, method?): string | FormData | undefined` — Подготавливает тело запроса.
- `getBodyForGet(request, path?, method?): string` — Подготавливает строку запроса.
- `getItem(): ApiInstance` — Возвращает базовый объект `ApiInstance`.

## Типы

### ApiConfig

- `urlRoot: string` — базовый URL для API.
- `origin: string` — протокол и домен для формирования базового URL.
- `headers: Record<string, string>` — заголовки запроса по умолчанию.
- `requestDefault: Record<string, any>` — данные запроса по умолчанию.
- `preparation: (apiFetch: ApiFetch) => Promise<void>` — входной хук.
- `end: (query: Response, apiFetch: ApiFetch) => Promise<ApiPreparationEnd>` — выходной хук.
- `timeout: number` — глобальный таймаут в миллисекундах.

## Прокси-архитектура

Класс `Api` работает как **статический прокси**. Все вызовы методов перенаправляются на внутренний `ApiInstance`.

### Управление экземпляром

Внутренний менеджер хранится в `ServerStorage` под уникальным ключом (`__dxt_api_instance__`). Эта архитектура решает две основные проблемы:

1.  **Потокобезопасность в SSR**: Во время рендеринга на стороне сервера `ServerStorage` гарантирует, что каждый входящий запрос имеет свою собственную изолированную конфигурацию и состояние API, предотвращая утечку данных между пользователями.
2.  **Простота синглтона на клиенте**: На стороне клиента он ведет себя как настоящий синглтон, позволяя настроить API в точке входа и использовать его где угодно без передачи экземпляров.

### Делегирование

Хотя `Api` является предпочтительным интерфейсом для стандартной логики приложения, основная логика (повторы, гидратация, джиттер) находится внутри `ApiInstance`. Для сложных сценариев, включающих несколько базовых URL-адресов или разные наборы заголовков одновременно, вы можете создавать экземпляры `ApiInstance` напрямую.
