FastAPI + htmx: интерактивный список дел без React

Как устроен учебный проект FastAPI + htmx

Браузер отправляет форму, FastAPI проверяет данные и рендерит HTML-фрагмент, htmx вставляет его в выбранную часть DOM. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

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

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Пример сверялся с актуальной документацией официальной документации htmx на 19 октября 2026 года. Создайте проект через uv init и выполните uv add fastapi uvicorn python-multipart jinja2. htmx подключите официальным скриптом в шаблоне. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

from fastapi import FastAPI, Form, HTTPException
from fastapi.responses import HTMLResponse, Response

app = FastAPI()
tasks: dict[int, str] = {}


def task_html(task_id: int, title: str) -> str:
    return f'''<li id="task-{task_id}">
      <span>{title}</span>
      <button hx-delete="/tasks/{task_id}" hx-target="#task-{task_id}" hx-swap="outerHTML">Удалить</button>
    </li>'''


@app.post("/tasks", response_class=HTMLResponse)
def add_task(title: str = Form(min_length=1, max_length=80)):
    clean = title.strip()
    if not clean:
        raise HTTPException(422, "Введите задачу")
    task_id = max(tasks, default=0) + 1
    tasks[task_id] = clean
    return task_html(task_id, clean)


@app.delete("/tasks/{task_id}", status_code=200)
def delete_task(task_id: int):
    tasks.pop(task_id, None)
    return Response()

Контракт интерфейса здесь является HTML. Сервер возвращает готовое представление, а htmx управляет доставкой и заменой. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

hx-post сериализует форму и отправляет её на сервер. hx-target выбирает узел для обновления, а hx-swap определяет способ вставки ответа. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Если сервер возвращает ошибку 422, htmx по умолчанию не вставляет тело как успешный фрагмент. Для пользовательской ошибки удобно вернуть контролируемый HTML и подходящий статус или обработать событие ошибки.

Не собирайте HTML через f-строку для пользовательского текста в рабочем приложении: это создаёт риск внедрения разметки. В полном примере используйте шаблонизатор с экранированием. Здесь функция показывает форму ответа, но границу безопасности нужно понимать явно. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Добавьте переключение done через PATCH и класс завершённой задачи. Сервер должен вернуть обновлённый li, а не отдельный JSON. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

htmx не отменяет HTTP и серверные шаблоны. Он делает их видимыми прямо в разметке. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Перед постоянным хранением вынесите данные в репозиторий, замените f-строку на Jinja2 и добавьте тесты endpoints. Интерфейс htmx можно оставить. Для закрепления откройте в первом API FastAPI, в разборе Fetch API и в REST API на Node.js.

Как изучить тему в Кодике

Сначала повторите формы, методы HTTP и HTML-шаблоны, затем добавляйте hx-атрибуты по одному. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Отключите JavaScript и убедитесь, что понимаете базовый HTTP-контракт, даже если интерфейс без htmx станет менее удобным. Базовый синтаксис закрепите через курс Python.

Что получится в итоге

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