React, Next.js и генерируемые клиенты TypeScript#

Elang — серверная часть на PHP. Его официальный сайт документации остаётся на HTML, формируемом сервером, CSS и обычном JavaScript. Интерфейс вашего приложения может использовать React, Next.js, другой JavaScript-фреймворк, мобильный код или серверный клиент.

Создание полного проекта с интерфейсом и сервером#

Устанавливайте версии React и Next.js для разработки непосредственно из Packagist. Проверены установка обоих PHP-приложений, зависимости, doctor и тесты API. Пакеты остаются предварительными версиями для разработки, а не стабильными выпусками.

composer create-project elang/react my-react-app dev-main
# Alternatively:
composer create-project elang/next my-next-app dev-main

Настроенный глобальный установщик также принимает elang new my-app --starter=react или --starter=next. Composer подготавливает PHP-приложение. Исходный код интерфейса находится в frontend/; вручную скачивать ZIP не нужно. Требования: PHP 8.3+, Composer 2 и Node 22.12+ для этих стартовых проектов интерфейса.

cd my-react-app
php elang serve

Во втором терминале:

cd my-react-app/frontend
npm ci
npm run dev

Откройте URL интерфейса, выведенный Vite или Next. Оставьте серверную часть работающей по выведенному ею адресу. При изменении адреса серверной части скопируйте frontend/.env.example в описанный документацией локальный файл окружения интерфейса. ELANG_BACKEND_URL — серверная конфигурация прокси; она никогда не должна содержать секреты, открытые браузеру.

Как работает аутентификация#

Оба стартовых проекта используют прокси /api на том же источнике. Браузер хранит cookie сессии HttpOnly; bearer-токены не сохраняются в localStorage. GET /api/session возвращает текущего пользователя, токен CSRF, доступность регистрации, доступность почты и признак ожидания второго фактора. Небезопасные запросы включают X-CSRF-Token.

1. Загрузите сессию перед отправкой формы.
2. Зарегистрируйтесь или войдите через /api/session/register или /api/session/login.
3. Если mfaRequired равен true, отправьте код в /api/session/mfa; доступ к учётной записи остаётся ожидающим до успешного завершения.
4. Обновляйте состояние сессии после записи, поскольку вход и выход меняют сессию и токен CSRF.
5. Создавайте, изменяйте, просматривайте и удаляйте свои закрытые заметки.

Новые учётные записи должны подтвердить почту перед защищёнными операциями записи API. При локальной разработке откройте /_elang/studio/mail серверной части, чтобы просмотреть зашифрованный почтовый ящик разработки. Область действия cookie определяется хостом или доменом и путём, а не портом; использование разных имён хостов интерфейса и серверной части может потребовать отдельного входа в серверную часть. Страница /backend-account стартового проекта объясняет этот переход.

Границы прокси#

Прокси Next перенаправляет только явно разрешённые пути и методы API, ограничивает JSON-запросы 32 КиБ, использует ограниченный тайм-аут, отклоняет перенаправления от вышестоящего сервера и передаёт отдельные заголовки Set-Cookie. Небезопасные запросы браузера должны поступать с собственного источника интерфейса. Перед межсерверным запросом прокси удаляет браузерный Origin, чтобы серверная часть не путала трафик прокси с прямым запросом CORS.

Прокси разработки Vite применяет проверку совпадения источника для небезопасных вызовов. В рабочей среде развёртывайте проверенный обратный прокси или прокси приложения; сервер разработки Vite не является рабочим развёртыванием. Никогда не открывайте универсальный параметр URL вышестоящего сервера, не перенаправляйте произвольную браузерную авторизацию на посторонние хосты и не отключайте CSRF ради работы прокси.

Для браузера, напрямую обращающегося к другому источнику API, настройте явные источники CORS и проверенную политику учётных данных и cookie. CORS не является аутентификацией. Предоставленные стартовые проекты избегают межсайтовых cookie с помощью прокси на одном источнике. Серверные и мобильные клиенты могут вместо этого использовать bearer-токены с областями доступа.

Генерация контракта TypeScript#

Стартовый проект Notes публикует /openapi.json из resources/openapi.php. Сгенерируйте отдельный типизированный клиент из этой доверенной локальной схемы:

php elang api:types --schema=resources/openapi.php --output=frontend/src/lib/generated.ts
# Next.js starter:
php elang api:types --schema=resources/openapi.php --output=frontend/lib/generated.ts

Сгенерированный модуль содержит типы схемы, входные и выходные данные операций, маршруты и createApiClient(). Стартовый проект импортирует эти типы и использует сгенерированные операции для записи заметок. При изменении контракта серверной части отредактируйте документ OpenAPI, повторите генерацию, проверьте типы и просмотрите полученные изменения.

import { createApiClient } from './generated.ts';

const api = createApiClient();
const result = await api.request('createNote', {
  body: { title: 'First idea', body: 'A useful note' },
  headers: { 'X-CSRF-Token': csrfToken },
});

Генератор намеренно поддерживает ограниченное подмножество OpenAPI 3.1: локальные ссылки на компоненты, объекты, массивы, скалярные типы и null, перечисления, объединения, тела запросов JSON и схемы ответов JSON/SSE. Неподдерживаемые конструкции схемы явно приводят к ошибке. Типы TypeScript не проверяют недоверенный JSON во время выполнения. Операции SSE описывают контракт; для живого потока используйте EventSource или потоковую обработку вместо вспомогательного вызова, ориентированного на JSON.

Проверка и развёртывание#

cd frontend
npm run typecheck
npm test
npm run build

Next также предоставляет npm run test:proxy. Запустите набор тестов PHP и браузерный сценарий с реальной серверной частью: войдите, подтвердите адрес, завершите MFA, если она включена, создайте, измените и удалите данные, обновите страницу, выйдите и попытайтесь прочитать данные другого пользователя. Проверьте CSP, HTTPS, доверенные заголовки прокси, конфигурацию URL серверной части, домен cookie, тайм-ауты и доступность вышестоящего сервера в своём развёртывании.

Файлы фиксации зависимостей интерфейса закрепляют проверенное дерево зависимостей. Обновления безопасности по-прежнему требуют проверки и повторной валидации. См. аутентификацию API, безопасность учётной записи и тестирование.