9.6 KiB
Фронтенд
Ви можете обслуговувати статичні фронтенд-застосунки за допомогою app.frontend() (або router.frontend()).
Це корисно для фронтенд-інструментів, які генерують статичні файли, як-от React з Vite, TanStack Router, Astro, Vue, Svelte, Angular, Solid та інші.
З такими інструментами зазвичай є крок, який збирає фронтенд, командою на кшталт:
npm run build
Це згенерує директорію на кшталт ./dist/ з вашими фронтенд-файлами.
Ви можете використати app.frontend(), щоб обслуговувати цю директорію відповідно до конвенцій, потрібних цим фронтенд-фреймворкам.
FastAPI спочатку перевіряє операції шляху. Фронтенд-файли перевіряються лише тоді, коли жоден звичайний маршрут не збігся, тому ваш API не буде зачеплено.
Обслуговування фронтенду
Після збірки вашого фронтенду, наприклад за допомогою npm run build, помістіть згенеровані файли в директорію, наприклад dist.
Структура вашого проєкту може виглядати так:
.
├── pyproject.toml
├── app
│ ├── __init__.py
│ └── main.py
└── dist
├── index.html
└── assets
└── app.js
Потім обслуговуйте її за допомогою app.frontend():
{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}
З цим запит до /assets/app.js може обслуговувати dist/assets/app.js.
Якщо у вас також є операція шляху FastAPI, операція шляху має пріоритет.
Маршрутизація на боці клієнта
Багато фронтенд-застосунків, включно з односторінковими застосунками (SPA), використовують маршрутизацію на боці клієнта. Шлях на кшталт /dashboard/settings може не бути реальним файлом, але фреймворк подбає про його обробку.
Тому, якщо звертатися до цієї URL-адреси напряму (замість навігації через застосунок), бекенд має обслуговувати фронтенд-застосунок з index.html, щоб фронтенд-фреймворк потім міг обробити маршрутизацію на боці клієнта.
Для цього використовуйте fallback="index.html":
{* ../../docs_src/frontend/tutorial002_py310.py hl[5] *}
FastAPI використовує цей fallback лише для запитів GET і HEAD, які виглядають як навігація браузера. Відсутні файли, як-от JavaScript, CSS і зображення, все ще повертають 404.
Запити з іншими методами, як-от POST або PUT, до шляхів, що збігаються лише з frontend fallback, також повертають 404. Звичайні операції шляху FastAPI все ще мають вищий пріоритет, ніж фронтенд-маршрути.
/// tip | Порада
За замовчуванням fallback має значення fallback="auto". У більшості випадків вам не потрібно вказувати fallback. Деталі читайте нижче.
///
Саме це потрібно для багатьох фронтенд-застосунків, які використовують маршрутизацію на боці клієнта, наприклад React з TanStack Router, Vue, Angular, SvelteKit або Solid.
Користувацька сторінка 404
Ви також можете обслуговувати статичну сторінку 404.html для відсутніх фронтенд-шляхів:
{* ../../docs_src/frontend/tutorial003_py310.py hl[5] *}
Ця відповідь зберігає код статусу 404.
У цьому випадку FastAPI не буде обслуговувати index.html для відсутніх фронтенд-шляхів. Натомість він поверне файл 404.html.
/// tip | Порада
За замовчуванням fallback має значення fallback="auto". З ним, якщо файл 404.html знайдено, він буде використаний як fallback автоматично.
Тому зазвичай ви можете не вказувати аргумент fallback.
///
Це корисно з фронтенд-інструментами, які генерують статичні HTML-файли для кожної сторінки, як-от Astro.
Автоматичний fallback
За замовчуванням app.frontend() використовує fallback="auto".
Якщо в директорії фронтенду є файл 404.html, відсутні фронтенд-шляхи обслуговують цей файл з кодом статусу 404.
Інакше, якщо є файл index.html, відсутні шляхи навігації браузера обслуговують index.html, що й очікують багато фронтенд-застосунків з маршрутизацією на боці клієнта.
Отже, у більшості випадків ви можете використовувати app.frontend("/", directory="dist") без вказання аргументу fallback.
{* ../../docs_src/frontend/tutorial001_py310.py hl[5] *}
Вимкнення fallback
Якщо ви не хочете обслуговувати fallback-файл для відсутніх фронтенд-шляхів, використовуйте fallback=None:
{* ../../docs_src/frontend/tutorial005_py310.py hl[5] *}
Тоді відсутні фронтенд-шляхи повертають звичайний 404.
Перевірка директорії
За замовчуванням app.frontend() перевіряє, що директорія існує, коли застосунок створюється.
Це допомагає виявити помилки конфігурації завчасно. Наприклад, якщо директорія вихідних файлів збірки фронтенду відсутня, FastAPI викличе помилку під час запуску.
Якщо ваші фронтенд-файли створюються пізніше, наприклад окремим кроком збірки після створення об'єкта застосунку, встановіть check_dir=False:
{* ../../docs_src/frontend/tutorial006_py310.py hl[5] *}
З check_dir=False FastAPI не перевірятиме директорію під час створення застосунку. Якщо налаштована директорія все ще відсутня під час обробки запиту, FastAPI викличе помилку тоді.
Використання з APIRouter
Ви також можете додати фронтенд-файли до APIRouter і включити його з префіксом:
{* ../../docs_src/frontend/tutorial004_py310.py hl[6,7] *}
У цьому прикладі фронтенд-шляхи обслуговуються під /app.
Будь-які звичайні операції шляху в застосунку все ще матимуть перевагу, включно з операціями в інших роутерах.
Залежності та проміжне програмне забезпечення
Фронтенд-відповіді виконуються всередині звичайного застосунку FastAPI, тому HTTP-проміжне програмне забезпечення застосовується до них.
Залежності із застосунку, з APIRouter і з include_router() також застосовуються до фронтенд-відповідей. Це може бути корисно для захисту фронтенду за допомогою автентифікації на основі кукі або подібного.
Лише статичний результат збірки
app.frontend() обслуговує файли, вже згенеровані вашою фронтенд-збіркою.
Він не виконує рендеринг на боці сервера. Він призначений для фронтенд-фреймворків, які генерують статичні файли, а не для фреймворків, що потребують динамічного рендерингу на сервері для кожного запиту.