python -m venv env
  
# On Unix/MacOS:  
source venv/bin/activate  
  
# On Windows:  
.\venv\Scripts\activate  

pip install "fastapi[all]"

from fastapi import FastAPI  
  
fake_posts_db = [{  
    'title': 'First Blog Post',  
    'content': 'Content of the first blog post.',  
    'author': 'John Doe',  
    'publication_date': '2023-06-20',  
    'comments': [  
        {'author': 'Alice', 'content': 'Great post!'},  
        {'author': 'Bob', 'content': 'Intresting read.'}  
    ],  
    'status': 'published'  
},{  
    'title': 'Second Blog Post',  
    'content': 'Content of the second blog post.',  
    'author': 'Jane Smith',  
    'publication_date': None,  
    'comments': [],  
    'status': 'draft'  
}]  
  
app = FastAPI()  
  
@app.get("/about")  
def about():  
    return "All you need to know about Simple Blog"

uvicorn main:app --reload

from fastapi.templating import Jinja2Templates  
  from fastapi.staticfiles import StaticFiles  

templates = Jinja2Templates(directory="templates")

app.mount("/static", StaticFiles(directory="static"), name="static")

{% if condition %}...{% endif %}

{% for item in iterable %}...{% endfor %}

{% include 'template_name.html' %}

{% block block_name %}...{% endblock %}

{% extend parent_temp.html %}

  
  
  
      
  
  
    
{% block heading %}Simple Blog{% endblock %}
  
  
    {% block content %}  
    {% endblock %}  
  
    {% include "footer.html" %}  
  

{% extends "base.html" %}  
  
{% block title %}Simple Blog - Blog Page{% endblock %}  
  
{% block heading %}Simple Blog - Blog Page{% endblock %}  
  
{% block content %}  
    
Total Number of Posts: {{ posts|length }}
  
  
    {% for post in posts %}  
          
  
            {% if post.status == 'published' %}  
                
{{ post.title }}
  
                
{{ post.content|truncate }}
  
                
Published on: {{ post.publication_date }}
  
  
                
Comments:
  
                
  
                    {% for comment in post.comments %}  
                        {{ comment.author }}-: {{ comment.content }}  
                         
  
                    {% endfor %}  
                
  
            {% else %}  
                
This post is still in draft mode.
  
            {% endif %}  
        

Дочерний шаблон расширяет базовый, заполняет блоки и выполняет итерацию по постам и комментариям.

Выражения

Jinja поддерживает арифметику, сравнения и логические операции. Пример:

{{2 + 2}} // output: 4

Подстановка переменных

Чтобы вывести переменную, используйте двойные фигурные скобки:

{{post.title}} // output: 'First Blog Post'

Фильтры

Фильтры меняют вывод переменной. Используйте их через |:

{{post|length}} // output: 2

Комментарии

В шаблонах можно добавлять однострочные и многострочные комментарии; они не попадут в итоговый HTML:

{# #} // inline  
  
{% comment %} ... {% end comment %} // multiline

Генерация URL

Контекст шаблона содержит url_for для формирования корректных ссылок внутри приложения:

About

Это сгенерирует http://localhost:8000/about при локальном запуске.

Передача данных в шаблоны

Добавьте в main.py обработчик корневого маршрута, который рендерит шаблон blog.html и передаёт список постов:

from fastapi import FastAPI, Request  
from fastapi.responses import HTMLResponse  
  
@app.get("/", response_class=HTMLResponse)  
async def read_posts(request: Request):  
    return templates.TemplateResponse("blog.html", {"request": request,   
                                            "posts": fake_posts_db})

Endpoint возвращает HTMLResponse, формируемый шаблоном blog.html, и передаёт в контекст request и fake_posts_db.

Откройте http://localhost:8000/ и увидите рендер страницы.

Обслуживание статических файлов

FastAPI умеет обслуживать статические файлы: CSS, JavaScript и изображения.

В каталоге static создайте styles.css:

body {  
    font-family: Arial, sans-serif;  
    margin: 0;  
    padding: 20px;  
    background-color: #f5f5f5;  
}  
  
h1, h2, h3, h4 {  
    color: #333;  
}  
  
.post {  
    background-color: #fff;  
    padding: 20px;  
    margin-bottom: 20px;  
    border-radius: 5px;  
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);  
}  
  
.post h3 {  
    margin-top: 0;  
}  
  
.post p {  
    margin-bottom: 10px;  
}  
  
.post ul {  
    list-style-type: none;  
    padding-left: 0;  
}  
  
.comment {  
    margin-bottom: 10px;  
    padding: 10px;  
    background-color: #f9f9f9;  
    border-radius: 5px;  
}  
  
footer {  
    background-color: #f2f2f2;  
    padding: 10px;  
    text-align: center;  
}

Измените head в templates/base.html, чтобы подключить CSS:

url_for(‘static’, path=’/styles.css’) сформирует путь /static/styles.css, который будет обслуживаться сервера.

Откройте http://localhost:8000/ и посмотрите изменения.

Аналогично можно подключать изображения и JavaScript.

Лучшие практики

• Организуйте шаблоны по папкам: templates/base.html, templates/components/*.html.
• Используйте наследование шаблонов для общего макета и частых фрагментов (header/footer).
• Передавайте в шаблоны только необходимые данные: уменьшайте объём передаваемого контекста.
• Вынесите повторяющуюся логику в фильтры и макросы Jinja.
• Кешируйте статические шаблоны и используйте HTTP‑заголовки кеширования.
• Профилируйте рендеринг при большом объёме данных.

Когда серверная отрисовка не подходит

Контрпримеры и ограничения:

• Очень интерактивные SPA с множеством клиентских состояний лучше делать на React/Vue и отдавать только API.
• Если требуется масштабная асинхронная отрисовка на клиенте (много WebSocket‑событий), серверные шаблоны могут усложнить логику.
• Для SEO‑менее критичных внутренних админок можно использовать клиентскую отрисовку.

Альтернативы: Mako, Chameleon, или полное клиентское рендеринг через SPA.

Руководство: шаблонный playbook для интеграции (мини‑SOP)

1. Создайте виртуальное окружение и установите зависимости.
2. Настройте структуру проекта: my_blog/{main.py,templates,static}.
3. Подключите Jinja2Templates и смонтируйте StaticFiles.
4. Сделайте базовый шаблон base.html и включаемые фрагменты (footer, header).
5. Создайте страницы, использующие {% extends %} и {% block %}.
6. Настройте маршруты, возвращающие TemplateResponse с контекстом.
7. Покройте тестами: unit‑тесты для рендеринга, интеграционные тесты конечных точек.
8. Настройте кеширование и HTTP‑заголовки.
9. Добавьте защиту от XSS и CSRF для форм.

Контроль качества: критерии приёмки

• Главная страница корректно рендерится и содержит все опубликованные посты.
• CSS и другие статические ресурсы загружаются без ошибок (HTTP 200).
• Навигационные ссылки ведут на существующие маршруты.
• Шаблоны не содержат утечек чувствительных данных (паролей, секретов).

Тестовые сценарии и приёмочные тесты

• При GET / должен возвращаться HTML с кодом 200.
• Проверить, что в HTML присутствует количество постов, равное len(posts).
• Для поста со status == ‘published’ отображается title и content, для draft — сообщение о черновике.
• Статические файлы (например /static/styles.css) возвращают 200 и имеют корректный Content-Type.

Безопасность и рекомендации по жёсткой защите

• Фильтры Jinja экранируют вывод по умолчанию; не отключайте экранирование без необходимости.
• Не вставляйте необработанный HTML, полученный от пользователей, в шаблоны. Пропускайте через sanitizer.
• Для форм используйте проверку на стороне сервера: валидация типов и длины полей.
• При хранении персональных данных используйте минимизацию данных и шифрование в хранилище.
• Настройте Content Security Policy (CSP) для ограничения источников скриптов и стилей.

Приватность и соответствие требованиям (GDPR и общие рекомендации)

• Отправляйте в шаблон только те персональные данные, которые нужны для отображения.
• Если отрисовываете персональные данные пользователя, предоставьте возможность их удаления и корректировки.
• В логах не храните чувствительные данные, отображаемые в шаблонах.

Ментальные модели и эвристики выбора подхода

• Если ваша задача доминируется контентом и SEO — выбирайте серверную отрисовку (Jinja + FastAPI).
• Если интерфейс требует богатой клиентской логики — отдайте предпочтение SPA и используйте FastAPI как API‑сервер.
• Смешанный подход: рендерьте критический контент на сервере, а динамику переносите на клиент.

Чек‑листы по ролям

Разработчик:

• Создать шаблоны и переиспользуемые фрагменты.
• Проверить корректную передачу данных в контекст.
• Написать модульные тесты рендеринга.

DevOps:

• Настроить обработку статических файлов на CDN или через reverse proxy.
• Настроить заголовки кеширования и CSP.

Дизайнер:

• Проверить соответствие CSS и компонентов макетам.
• Убедиться в доступности (a11y) и адаптивности.

Шпаргалка (cheat sheet)

• Формирование URL: {{ url_for(‘route_name’) }}
• Подключение статических файлов: url_for(‘static’, path=’/styles.css’)
• Проверка длины списка: {{ items|length }}
• Тримминг текста: {{ text|truncate(100) }}

Диаграмма принятия решения

flowchart TD
  A[Нужна серверная отрисовка?] -->|Да, контент и SEO| B[Jinja + FastAPI]
  A -->|Нет, интерактивность| C[SPA + FastAPI API]
  B --> D{Есть интенсивная динамика?}
  D -->|Нет| E[Чистая серверная отрисовка]
  D -->|Да| F[Гибрид: сервер + клиент]

Когда стоит отказаться от Jinja

• Если у вас большое SPA с состоянием на клиенте и частыми обновлениями, обслуживание через Jinja усложнит поддержку.
• Если нужно масштабирование рендеринга на миллионы уникальных пользователе́й в секунду, стоит рассмотреть специализированные решения и CDN‑кеширование.

Альтернативные подходы

• Server Side Rendering на Next.js/Nuxt для проектов с главной ролью SEO и одновременной клиентской интерактивностью.
• Использовать Mako/Chameleon как альтернативные шаблонизаторы в Python.
• Полностью клиентская архитектура (React/Vue) с FastAPI как чистым API.

Краткая методология развертывания

1. Локальная разработка и тесты.
2. Настройка CI для линтинга и тестов.
3. Размещение статических файлов на CDN.
4. Настройка HTTPS и CSP.
5. Мониторинг производительности и логирование ошибок.

Краткое резюме

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

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

Короткое объявление для команды (100–200 слов)

Мы интегрировали Jinja в наш FastAPI проект: теперь можно быстро создавать серверные HTML‑страницы с наследуемыми шаблонами и подключать CSS/JS через /static. Рекомендуется хранить общие части интерфейса в base.html, выносить повторяемые фрагменты в include и передавать в шаблоны только необходимые данные. Для продакшна обслуживайте статические файлы через CDN, настройте CSP и HTTP‑кеширование. Тесты рендеринга и контроль безопасности (XSS, приватность) обязательны перед релизом.

Если нужно, могу подготовить пример полного проекта в ZIP‑архиве или детализированный чек‑лист для CI/CD.