re:re:actable
Урок 134 минуты чтения

Изоляция API от UI

На этой странице
Кратко

API-слой описывает обращение к серверу, а компонент — отображение данных и действия пользователя. Разделение уменьшает дублирование и упрощает изменения.

Вопрос

Зачем выносить fetch в отдельные функции и что должен возвращать API-слой?

Основная идея

Если три экрана показывают профиль, копировать URL, заголовки, проверку статуса и преобразование ответа в каждый компонент неудобно. При изменении API легко исправить два места и забыть третье. Функция getProfile собирает правила загрузки в одном месте.

Компоненту обычно нужны предметные данные, например { name }, а не низкоуровневый Response. API-функция должна вернуть данные или выбросить понятную ошибку, а также принять параметры вроде id и signal. Тогда её одинаково удобно вызывать из эффекта, loader или queryFn.

Это разделение не требует сложной архитектуры. Для маленького приложения достаточно файла api/users.js. Кеширование и состояние UI при этом остаются отдельными слоями. Замена REST на другой транспорт может потребовать изменений контрактов, но компоненты меньше зависят от технических деталей.

Пример

Пример состоит из двух файлов в клиентском React-проекте; /api/users/:id возвращает объект пользователя.

api/users.js

export async function getUser(id, signal) {
  const response = await fetch(`/api/users/${encodeURIComponent(id)}`, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

UserCard.jsx

import { useEffect, useState } from 'react';
import { getUser } from './api/users.js';
 
export default function UserCard({ id = 1 }) {
  const [name, setName] = useState('Загрузка...');
  useEffect(() => {
    const controller = new AbortController();
    let active = true;
    setName('Загрузка...');
    getUser(id, controller.signal).then(
      user => { if (active) setName(user.name); },
      () => { if (active) setName('Профиль недоступен'); },
    );
    return () => { active = false; controller.abort(); };
  }, [id]);
  return <p>{name}</p>;
}

API-файл ничего не знает о JSX. Компонент ничего не знает о конкретной проверке HTTP-статуса. Для теста функцию загрузки можно подменить тестовым ответом.

Слои и их ответственность

┌─ UI-компонент ──────────────┐  отображение, состояния loading/error, действия пользователя
│  useBook(id)                │
└──────────────┬──────────────┘
┌─ Хук данных ────────────────┐  кэш, повторы, инвалидация (TanStack Query / SWR / loader)
│  useQuery(bookQuery(id))    │
└──────────────┬──────────────┘
┌─ API-функции ───────────────┐  URL, метод, заголовки, проверка статуса, разбор и валидация ответа
│  getBook(id, signal)        │
└──────────────┬──────────────┘
┌─ HTTP-клиент ───────────────┐  базовый URL, токен, таймауты, единый формат ошибок
│  http.get(path, opts)       │
└─────────────────────────────┘

HTTP-клиент с единым форматом ошибок

// api/http.ts
export class ApiError extends Error {
  constructor(public status: number, message: string, public details?: unknown) {
    super(message);
  }
}
 
export async function http<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(`${import.meta.env.VITE_API_URL}${path}`, {
    ...init,
    headers: { "Content-Type": "application/json", ...init.headers },
    credentials: "include",
  });
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new ApiError(res.status, body?.message ?? `HTTP ${res.status}`, body);
  }
  return res.status === 204 ? (undefined as T) : res.json();
}
// api/books.ts — валидация ответа схемой: TypeScript не проверяет JSON в рантайме
import { z } from "zod";
import { http } from "./http";
 
const Book = z.object({ id: z.string(), title: z.string(), price: z.number() });
export type Book = z.infer<typeof Book>;
 
export async function getBook(id: string, signal?: AbortSignal): Promise<Book> {
  return Book.parse(await http(`/books/${encodeURIComponent(id)}`, { signal }));
}
// UI знает только про Book и ApiError
function BookPage({ id }: { id: string }) {
  const { data, error } = useQuery({ queryKey: ["book", id], queryFn: ({ signal }) => getBook(id, signal) });
  if (error instanceof ApiError && error.status === 404) return <p>Книга не найдена</p>;
  // ...
}

Плюсы: смена бэкенда, авторизации или формата ошибок затрагивает один файл; в тестах API легко подменить (например, MSW на уровне сети).

Что важно помнить

  • TypeScript-тип не проверяет JSON во время выполнения: недоверенный ответ при необходимости валидируют схемой.
  • Не помещайте секретные серверные ключи в клиентский API-слой: его код доступен браузеру.
  • Сохраняйте отмену и исходную причину ошибки при оборачивании запросов.

Мини-шпаргалка

API → транспорт, статус, данные. Query/loader → жизненный цикл загрузки. Компонент → представление.

Документация

useEffect: загрузка данных.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам