89 lines
5.3 KiB
Markdown
89 lines
5.3 KiB
Markdown
|
---
|
|||
|
|
title: Настройка REST-клиента
|
|||
|
|
description: Подготовка REST-клиента сервиса к использованию.
|
|||
|
|
keywords: [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](/docs/applied/rest-client/setup/auto)
|
|||
|
|
- [Ручное создание](/docs/applied/rest-client/setup/manual)
|
|||
|
|
|
|||
|
|
## 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-клиента](/docs/applied/rest-client/setup/hooks)
|
|||
|
|
|
|||
|
|
## Структура модуля
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
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](/docs/applied/rest-client/setup/auto) или [Ручное создание](/docs/applied/rest-client/setup/manual).
|
|||
|
|
2. Добавьте GET-хуки для GET-запросов: [GET-хуки REST-клиента](/docs/applied/rest-client/setup/hooks).
|
|||
|
|
3. Проверьте прямые вызовы клиента: [Использование REST-клиента](/docs/applied/rest-client/usage).
|
|||
|
|
4. После настройки клиента переходите к [Получению данных](/docs/applied/data-fetch/).
|