Фронтенд¶
🌐 Переклад ШІ та людьми
Цей переклад виконано ШІ під керівництвом людей. 🤝
Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖
Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.
Ви можете обслуговувати статичні фронтенд-застосунки за допомогою 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():
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist")
З цим запит до /assets/app.js може обслуговувати dist/assets/app.js.
Якщо у вас також є операція шляху FastAPI, операція шляху має пріоритет.
Маршрутизація на боці клієнта¶
Багато фронтенд-застосунків, включно з односторінковими застосунками (SPA), використовують маршрутизацію на боці клієнта. Шлях на кшталт /dashboard/settings може не бути реальним файлом, але фреймворк подбає про його обробку.
Тому, якщо звертатися до цієї URL-адреси напряму (замість навігації через застосунок), бекенд має обслуговувати фронтенд-застосунок з index.html, щоб фронтенд-фреймворк потім міг обробити маршрутизацію на боці клієнта.
Для цього використовуйте fallback="index.html":
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="index.html")
FastAPI використовує цей fallback лише для запитів GET і HEAD, які явно приймають HTML з Accept: text/html або Accept: application/xhtml+xml, як зазвичай роблять запити навігації браузера. Відсутні файли, як-от JavaScript, CSS і зображення, все ще повертають 404.
Запити з іншими методами, як-от POST або PUT, до шляхів, що збігаються лише з frontend fallback, також повертають 404. Звичайні FastAPI операції шляху все ще мають вищий пріоритет, ніж фронтенд-маршрути.
Порада
За замовчуванням fallback має значення fallback="auto". У більшості випадків вам не потрібно вказувати fallback. Деталі читайте нижче.
Саме це потрібно для багатьох фронтенд-застосунків, які використовують маршрутизацію на боці клієнта, наприклад React з TanStack Router, Vue, Angular, SvelteKit або Solid.
Користувацька сторінка 404¶
Ви також можете обслуговувати статичну сторінку 404.html для відсутніх фронтенд-шляхів:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback="404.html")
Ця відповідь зберігає код статусу 404.
У цьому випадку FastAPI не буде обслуговувати index.html для відсутніх фронтенд-шляхів. Натомість він поверне файл 404.html.
Порада
За замовчуванням 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.
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist")
Вимкнення fallback¶
Якщо ви не хочете обслуговувати fallback-файл для відсутніх фронтенд-шляхів, використовуйте fallback=None:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", fallback=None)
Тоді відсутні фронтенд-шляхи повертають звичайний 404.
Перевірка директорії¶
За замовчуванням app.frontend() використовує check_dir="auto".
Коли змінна оточення FASTAPI_ENV має значення development, FastAPI лише показує попередження, якщо директорія вихідних файлів збірки фронтенду відсутня. Команда fastapi dev встановлює цю змінну оточення для вас, якщо її ще не встановлено. Це дає змогу запустити бекенд перед збіркою або запуском фронтенду під час розробки.
У будь-якому іншому оточенні FastAPI викликає помилку, коли застосунок створюється. Це допомагає виявити помилки конфігурації завчасно перед розгортанням застосунку без його фронтенд-файлів.
Ви також можете встановити check_dir=True, щоб завжди перевіряти директорію під час створення застосунку.
Якщо ваші фронтенд-файли створюються пізніше, наприклад окремим кроком збірки після створення об'єкта застосунку, встановіть check_dir=False:
from fastapi import FastAPI
app = FastAPI()
app.frontend("/", directory="dist", check_dir=False)
З check_dir=False FastAPI не перевірятиме директорію під час створення застосунку. Якщо налаштована директорія все ще відсутня під час обробки запиту, FastAPI викличе помилку тоді.
Використання з APIRouter¶
Ви також можете додати фронтенд-файли до APIRouter і включити його з префіксом:
from fastapi import APIRouter, FastAPI
app = FastAPI()
router = APIRouter()
router.frontend("/", directory="dist", fallback="index.html")
app.include_router(router, prefix="/app")
У цьому прикладі фронтенд-шляхи обслуговуються під /app.
Будь-які звичайні операції шляху в застосунку все ще матимуть перевагу, включно з операціями в інших роутерах.
Залежності та проміжне програмне забезпечення¶
Фронтенд-відповіді виконуються всередині звичайного застосунку FastAPI, тому HTTP-проміжне програмне забезпечення застосовується до них.
Залежності із застосунку, з APIRouter і з include_router() також застосовуються до фронтенд-відповідей. Це може бути корисно для захисту фронтенду за допомогою автентифікації на основі кукі або подібного.
Залежності також можуть змінювати заголовки відповіді та додавати фонові завдання, як і зі звичайними операціями шляху.
Лише статичний результат збірки¶
app.frontend() обслуговує файли, вже згенеровані вашою фронтенд-збіркою.
Він не виконує рендеринг на боці сервера. Він призначений для фронтенд-фреймворків, які генерують статичні файли, а не для фреймворків, що потребують динамічного рендерингу на сервері для кожного запиту.