|
| 1 | +--- |
| 2 | +sidebar_position: 4 |
| 3 | +--- |
| 4 | + |
| 5 | +import Tabs from '@theme/Tabs'; |
| 6 | +import TabItem from '@theme/TabItem'; |
| 7 | + |
| 8 | +# Обработка API-запросов {#handling-api-requests} |
| 9 | + |
| 10 | +## API-запросы в `shared` {#shared-api-requests} |
| 11 | + |
| 12 | +Начните с размещения общей логики API-запросов в каталоге `shared/api`. Это упрощает повторное использование запросов во всем приложении, что ускоряет разработку. Для многих проектов этого будет достаточно. |
| 13 | + |
| 14 | +Типичная структура файлов будет такой: |
| 15 | +- 📂 shared |
| 16 | + - 📂 api |
| 17 | + - 📄 client.ts |
| 18 | + - 📄 index.ts |
| 19 | + - 📂 endpoints |
| 20 | + - 📄 login.ts |
| 21 | + |
| 22 | +Файл `client.ts` централизует настройку HTTP-запросов. Он оборачивает выбранный вами подход (например, `fetch()` или экземпляр `axios`) и обрабатывает общие конфигурации, такие как: |
| 23 | + |
| 24 | +- Базовый URL бэкенда. |
| 25 | +- Заголовки по умолчанию (например, для аутентификации). |
| 26 | +- Сериализация данных. |
| 27 | + |
| 28 | +Вот примеры для `axios` и `fetch`: |
| 29 | + |
| 30 | +<Tabs> |
| 31 | + |
| 32 | +<TabItem value="axios" label="Axios"> |
| 33 | +```ts title="shared/api/client.ts" |
| 34 | +// Example using axios |
| 35 | +import axios from 'axios'; |
| 36 | + |
| 37 | +export const client = axios.create({ |
| 38 | + baseURL: 'https://your-api-domain.com/api/', |
| 39 | + timeout: 5000, |
| 40 | + headers: { 'X-Custom-Header': 'my-custom-value' } |
| 41 | +}); |
| 42 | +``` |
| 43 | +</TabItem> |
| 44 | + |
| 45 | +<TabItem value="fetch" label="Fetch"> |
| 46 | +```ts title="shared/api/client.ts" |
| 47 | +export const client = { |
| 48 | + async post(endpoint: string, body: any, options?: RequestInit) { |
| 49 | + const response = await fetch(`https://your-api-domain.com/api${endpoint}`, { |
| 50 | + method: 'POST', |
| 51 | + body: JSON.stringify(body), |
| 52 | + ...options, |
| 53 | + headers: { |
| 54 | + 'Content-Type': 'application/json', |
| 55 | + 'X-Custom-Header': 'my-custom-value', |
| 56 | + ...options?.headers, |
| 57 | + }, |
| 58 | + }); |
| 59 | + return response.json(); |
| 60 | + } |
| 61 | + // ... другие методы put, delete, и т.д. |
| 62 | +}; |
| 63 | +``` |
| 64 | +</TabItem> |
| 65 | + |
| 66 | +</Tabs> |
| 67 | + |
| 68 | +Организуйте свои отдельные функции API-запросов в shared/api/endpoints, группируя их по API эндпоинтам. |
| 69 | + |
| 70 | +:::note |
| 71 | + |
| 72 | +Для простоты, в примерах ниже мы опускаем взаимодействие с формами и валидацию. Для получения подробной информации о том, как работать с такими библиотеками как Zod или Valibot, обратитесь к секции [Проверка типов и схемы](/docs/guides/examples/types#type-validation-schemas-and-zod). |
| 73 | + |
| 74 | +::: |
| 75 | + |
| 76 | +```ts title="shared/api/endpoints/login.ts" |
| 77 | +import { client } from '../client'; |
| 78 | + |
| 79 | +export interface LoginCredentials { |
| 80 | + email: string; |
| 81 | + password: string; |
| 82 | +} |
| 83 | + |
| 84 | +export function login(credentials: LoginCredentials) { |
| 85 | + return client.post('/login', credentials); |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +Используйте файл `index.ts` в `shared/api` для экспорта ваших функций запросов. |
| 90 | + |
| 91 | +```ts title="shared/api/index.ts" |
| 92 | +export { client } from './client'; // Если нужно экспортировать клиент |
| 93 | +export { login } from './endpoints/login'; |
| 94 | +export type { LoginCredentials } from './endpoints/login'; |
| 95 | +``` |
| 96 | + |
| 97 | +## API-запросы, специфичные для слайса {#slice-specific-api-requests} |
| 98 | + |
| 99 | +Если API-запрос используется только определенным слайсом (например, одной страницей или фичей) и не будет использоваться повторно, поместите его в сегмент `api` этого слайса. Это позволит аккуратно отделить логику, специфичную для слайса, от всего остального приложения. |
| 100 | + |
| 101 | +- 📂 pages |
| 102 | + - 📂 login |
| 103 | + - 📄 index.ts |
| 104 | + - 📂 api |
| 105 | + - 📄 login.ts |
| 106 | + - 📂 ui |
| 107 | + - 📄 LoginPage.tsx |
| 108 | + |
| 109 | +```ts title="pages/login/api/login.ts" |
| 110 | +import { client } from 'shared/api'; |
| 111 | + |
| 112 | +interface LoginCredentials { |
| 113 | + email: string; |
| 114 | + password: string; |
| 115 | +} |
| 116 | + |
| 117 | +export function login(credentials: LoginCredentials) { |
| 118 | + return client.post('/login', credentials); |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +Вам не нужно экспортировать функцию `login()` через публичный API страницы, потому что маловероятно, что какое-либо другое место в приложении будет нуждаться в этом запросе. |
| 123 | + |
| 124 | +:::note |
| 125 | + |
| 126 | +Избегайте преждевременного размещения API-запросов и типов ответов бэкенда в слое `entities`. Ответы бэкенда могут отличаться от того, что нужно вашим сущностям фронтенда. Логика API в `shared/api` или сегменте `api` слайса позволяет вам преобразовывать данные при необходимости, сохраняя фокус сущностей на проблемах фронтенда. |
| 127 | + |
| 128 | +::: |
| 129 | + |
| 130 | +## Использование генераторов клиентов {#client-generators} |
| 131 | + |
| 132 | +Если ваш бэкенд предоставляет OpenAPI спецификацию, инструменты как [orval](https://orval.dev/) или [openapi-typescript](https://openapi-ts.dev/), могут генерировать типы API и функции запросов. Разместите сгенерированный код, например, в `shared/api/openapi`. Обязательно включите `README.md` для документирования того, что это за типы и как их генерировать. |
| 133 | + |
| 134 | +## Интеграция с библиотеками состояния сервера {#server-state-libraries} |
| 135 | + |
| 136 | +При использовании библиотек состояния сервера, таких как [TanStack Query (React Query)](https://tanstack.com/query/latest) или [Pinia Colada](https://pinia-colada.esm.dev/) вам может потребоваться совместное использование типов или ключей кеша между срезами. Используйте общий слой `shared` для таких вещей, как: |
| 137 | + |
| 138 | +- Типы данных API |
| 139 | +- Ключи кеша |
| 140 | +- Общие параметры запросов и мутаций |
| 141 | + |
| 142 | +Подробнее о том, как работать с server state библиотеками, читайте в статье [React Query](/docs/guides/tech/with-react-query) |
0 commit comments