Типизация API: тип на fetch — это обещание, а не доказательство

fetch отдаёт вам any, а as делает только хуже

response.json() возвращает Promise<any>. Этот any честен: на этапе компиляции TypeScript действительно не знает, какой JSON пришлёт сервер. В момент, когда вы пишете тип, вы утверждаете знание, которое компилятор проверить не может:

const res = await fetch("/api/user/42");
const user = await res.json(); // ^? any

// «Обещаю, что это User» — но это никто не проверяет
const typed = (await res.json()) as User; // ^? User

as User — это одностороннее утверждение. Оно заглушает any и даёт значение, которое остальная программа считает полностью типизированным, — но при этом не выполняет никакой работы в рантайме. Если сервер пришлёт { id: 42, profil: null } (заметьте опечатку, или переименованное поле, или null там, где вы ждали объект), typed.profile.name скомпилируется, уедет в прод и упадёт в рантайме. Каст был ложью, которую система типов поймать не могла.

as Response и граница доверия

Данные не заслуживают доверия, и их форма тоже. Представьте круговой рейс: ваш типизированный вызов уходит, возвращаются байты JSON, и тут развилка. Одна ветка кастит — быстро, бесплатно и несостоятельно. Другая валидирует — рантайм-проверка, которая реально осматривает байты и только потом пропускает типизированное значение.

Граница — самое важное понятие этого раздела: это линия, где гарантии этапа компиляции прекращаются. Всё слева от неё (ваши места вызовов, ваш код рендера) доказано проверщиком типов. Всё справа (фактический ответ) — рантайм-данные, которых проверщик не видел. Каст притворяется, что линии нет. Валидация — единственное, что зарабатывает тип.

Моделируйте ответ как размеченное объединение, а не как happy-path-форму

Ещё до валидации вы продвигаетесь дальше, если типизируете реальность. Реальные API возвращают ошибки, а не только успехи. Поле, которое «всегда есть» на счастливом пути, в ветке ошибки — undefined. Смоделируйте оба:

type ApiOk<T> = { ok: true; data: T };
type ApiErr = { ok: false; error: { code: string; message: string } };
type ApiResult<T> = ApiOk<T> | ApiErr;

declare function getUser(id: number): Promise<ApiResult<User>>;

const r = await getUser(42);
if (r.ok) {
  r.data; // ^? User  — сужено: data есть только в ok-ветке
} else {
  r.error.message; // ^? string  — error есть только здесь
  // r.data;  // Error: Property 'data' does not exist on type 'ApiErr'
}

Дискриминант ok: true | false (раздел 02) заставляет каждого вызывающего обработать ветку отказа — компилятор отказывается пускать к r.data, пока не доказано r.ok. Это строго лучше, чем возврат User | undefined, который потом затирают через !. Это не валидирует байты, но делает контракт честным в системе типов.

Result<T, E> проталкивает ошибки в значения

Та же идея, обобщённая: вместо того чтобы бросать исключение через границу, возвращайте Result и заставьте вызывающего разобраться с обеими ветками. Ошибки становятся обычными значениями, которые отслеживает проверщик типов:

type Result<T, E = Error> =
  | { kind: "ok"; value: T }
  | { kind: "err"; error: E };

function parseJson<T>(text: string): Result<T, SyntaxError> {
  try {
    return { kind: "ok", value: JSON.parse(text) as T };
  } catch (e) {
    return { kind: "err", error: e as SyntaxError };
  }
}
// Заметьте: `as T` внутри — ВСЁ ЕЩЁ ложь — JSON.parse возвращает any.
// Result честно моделирует развилку бросает/не бросает, но не
// проверяет форму успешного значения. Этот пробел закрывает урок 2.

Result делает поток управления типобезопасным. Он не делает типобезопасной полезную нагрузку — as T — это та же граничная ложь в более красивом пальто.

Разделение типов между клиентом и сервером

Когда вы обнаруживаете, что копируете серверный интерфейс в фронтенд-файл руками, спросите себя: что произойдёт, когда сервер добавит поле на следующей неделе? Самый чистый способ сделать аннотацию менее ложью — перестать писать её руками. Если клиент и сервер делят один источник истины, тип не сможет тихо разъехаться с байтами:

• Один монорепозиторий / общий пакет — экспортируйте тип ответа из одного модуля, который импортируют обе стороны. Zod-схемы следующего урока и tRPC из урока 3 — два способа сделать это; оба выводят тип из одного определения.
• Типы, сгенерированные из OpenAPI (стандарт описания REST API в машиночитаемом формате) — когда сервер публикует OpenAPI-спецификацию, шаг кодогенерации превращает её в клиентские типы (см. трек APIs про OpenAPI). Сгенерированный User механически привязан к задокументированному контракту, поэтому он расходится только когда расходится спека — а diff спеки можно отревьюить. Но в рантайме это всё равно не валидирует; баг сервера, нарушающий собственную спеку, проскочит. Генерация сужает пробел расхождения; она не закрывает пробел доверия.