nextjs-fetch-data-example/ai/nextjs-style-guide/applied/rest-client/setup/index.md

title, description, keywords

title	description	keywords
Настройка REST-клиента	Подготовка REST-клиента сервиса к использованию.	rest клиент infra методы openapi get-хуки swr

Настройка REST-клиента

Подготовка REST-клиента сервиса к использованию.

Что настраиваем

REST-клиент — это infra-модуль, через который проект работает с внешним REST API.

На этапе настройки нужно подготовить клиент сервиса: оболочку клиента, методы API и GET-хуки для клиентских компонентов.

Из чего состоит клиент

REST-клиент состоит из трёх основных частей:

1. Клиент — самописная оболочка над транспортом.
2. Методы — сгенерированные из OpenAPI или написанные вручную вызовы API.
3. GET-хуки — SWR-обёртки для GET-запросов.

Эти части живут в одном REST-модуле, потому что относятся к одному внешнему сервису.

Клиент

Клиент — ручной слой, который настраивает работу с API: baseUrl, заголовки, авторизацию, обработку ошибок и создание инстанса сервиса.

Даже если методы генерируются из OpenAPI, client.ts остаётся ручным файлом проекта.

client.ts — только сборочная точка клиента. В нём не размещаются DTO, declare module, Extended-типы, GET-хуки и бизнес-логика.

baseUrl API задаётся обязательной env-переменной без fallback-значения в коде. Не используйте записи вроде process.env.NEXT_PUBLIC_PET_STORE_API_BASE_URL ?? 'http://localhost:8080/api/v3' или ?? '': локальный URL должен лежать в .env.local, а отсутствие переменной должно приводить к явной ошибке конфигурации.

Методы

Методы описывают конкретные запросы к API.

Они появляются одним из двух способов:

• генерируются из OpenAPI в generated/;
• создаются вручную в methods/.

Подробности:

• Автогенерация из OpenAPI
• Ручное создание

GET-хуки

Для GET-запросов добавляются GET-хуки REST-клиента.

Это прозрачные SWR-обёртки над GET-методами клиента. Они живут в hooks/ этого же REST-модуля и нужны для использования данных в Client Components.

GET-хуки именуются с префиксом useGet: useGetPetList, useGetPetDetail, useGetCurrentUser.

Каждый GET-хук имеет экспортируемую key-функцию. SWR-ключ всегда имеет формат [serviceName, endpoint]: например ['pet-store-api', '/pet/10'].

Хук принимает generated-параметры метода и SWR-настройки: params?: GetPetByIdParams | null, config?: SWRConfiguration<Pet>.

Подробности:

• GET-хуки REST-клиента

Структура модуля

src/infra/{service-name}/
├── client.ts                 # самописная оболочка и инстанс клиента
├── generated/ или methods/   # методы API
├── hooks/                    # GET-хуки REST-клиента
├── types/                    # DTO, именованные response-типы и расширения типов
├── errors/                   # ошибки API, если нужны
└── index.ts                  # публичный API

index.ts — единственная точка входа в REST-модуль для внешнего кода.

Если generated-метод возвращает безымянный тип вроде Record<string, number>, а этот тип нужен снаружи, вынесите его в types/. Не объявляйте DTO внутри hooks/use-get-*.hook.ts.

Что делаем дальше

1. Создайте методы клиента: Автогенерация из OpenAPI или Ручное создание.
2. Добавьте GET-хуки для GET-запросов: GET-хуки REST-клиента.
3. Проверьте прямые вызовы клиента: Использование REST-клиента.
4. После настройки клиента переходите к Получению данных.