HTML-сайт на FastAPI: Jinja, static files и формы

FastAPI может возвращать не только JSON. Jinja2Templates рендерит HTML, а
StaticFiles обслуживает CSS и изображения. HTML-форма отправляет данные как
application/x-www-form-urlencoded, а форма с файлом — как multipart/form-data.

Это удобно, когда отдельный frontend пока не нужен: пользователь открывает страницу,
FastAPI получает данные из БД, Jinja подставляет их в шаблон, а браузер показывает
готовый HTML. Формы отправляют изменения обратно тому же приложению.

Для небольшого сайта достаточно трёх частей: папки templates, папки static и
маршрутов GET/POST. Сначала добейся отображения одной страницы, затем подключай форму.

Надёжные пути

Строй каталоги относительно файла приложения, а не текущей папки терминала:

from pathlib import Path
from fastapi import FastAPI, Request
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

BASE_DIR = Path(__file__).resolve().parent
app = FastAPI()
app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
templates = Jinja2Templates(directory=BASE_DIR / "templates")

@app.get("/")
def home(request: Request):
    return templates.TemplateResponse(
        request=request,
        name="index.html",
        context={"projects": []},
    )

В шаблоне:

<link rel="stylesheet" href="{{ url_for('static', path='/style.css') }}">

Формы

from typing import Annotated
from fastapi import Form

@app.post("/projects")
def create_project(title: Annotated[str, Form(min_length=3, max_length=120)]):
    return {"title": title}

Для загрузки файла добавь enctype="multipart/form-data". Имена <input name>
должны совпадать с параметрами маршрута. После успешного POST обычно возвращают
redirect 303, чтобы обновление страницы не повторяло создание записи.

HTML-валидация удобна пользователю, но сервер обязан повторно проверить все поля.

Понятный цикл GET → POST → redirect

1. GET показывает форму и существующие данные.
2. POST проверяет поля и сохраняет изменения.
3. При ошибке сервер снова показывает форму с объяснением.
4. При успехе сервер отвечает redirect 303 на GET-страницу.

Так обновление вкладки не отправит форму второй раз. Если CSS не подключился, открой
DevTools → Network: ответ 404 обычно означает неверный путь или имя mount.

Официальная документация

• FastAPI: Templates
• FastAPI: Static Files
• FastAPI: Forms and Files