Litestar框架中的模板引擎使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00723/article/details/148465858

Litestar框架中的模板引擎使用指南

litestar Production-ready, Light, Flexible and Extensible ASGI API framework | Effortlessly Build Performant APIs 项目地址: https://gitcode.com/gh_mirrors/li/litestar

前言

在现代Web开发中，模板引擎是实现动态网页内容的重要工具。Litestar作为一款高性能的Python Web框架，提供了对多种流行模板引擎的内置支持。本文将详细介绍如何在Litestar中使用模板引擎，包括配置、使用技巧以及高级功能。

模板引擎支持概述

Litestar框架原生支持三种主流模板引擎：

Jinja2 - 功能强大且广泛使用的模板引擎
Mako - 以高性能著称的模板系统
Minijinja - Jinja2的轻量级替代方案

框架通过统一的接口抽象，使得开发者可以轻松切换不同引擎，同时也支持自定义引擎的集成。

安装与基础配置

安装模板引擎

由于保持核心框架轻量化的考虑，Litestar默认不包含任何模板引擎实现。使用前需要单独安装：

# 安装Jinja2支持
pip install 'litestar[jinja]'

# 安装Mako支持
pip install 'litestar[mako]'

# 安装Minijinja支持
pip install 'litestar[minijinja]'

提示：如果已经安装了litestar[standard]扩展包，则无需额外安装Jinja2支持，因为它已包含在标准扩展中。

基本配置示例

在应用初始化时注册模板引擎：

from litestar import Litestar
from litestar.template import TemplateConfig

# 使用Jinja2模板引擎
app = Litestar(
    template_config=TemplateConfig(
        directory="path/to/templates",
        engine=JinjaTemplateEngine
    )
)

配置参数说明：

directory：指定模板文件存放目录，可以是字符串路径或路径列表
engine：指定使用的模板引擎类

高级配置选项

自定义模板引擎实例

对于需要更精细控制的情况，可以直接传入预配置的引擎实例：

from jinja2 import Environment, DictLoader

custom_env = Environment(loader=DictLoader({"index.html": "Hello {{name}}!"}))
app = Litestar(
    template_config=TemplateConfig(
        instance=JinjaTemplateEngine.from_environment(custom_env)
    )
)

注意：使用instance参数时不能同时使用directory参数，开发者需完全负责引擎的创建和配置。

实现自定义模板引擎

Litestar通过TemplateEngineProtocol协议类支持任意模板引擎的集成：

from typing import Protocol
from pathlib import Path

class MyTemplateEngine(Protocol):
    def __init__(self, directory: Path) -> None:
        """初始化模板引擎"""
    
    def get_template(self, name: str):
        """加载并返回指定模板"""

实现该协议后，即可像内置引擎一样使用自定义引擎。

模板响应实践

基本用法

在路由处理函数中返回模板响应：

from litestar.response import Template

@get("/")
async def homepage() -> Template:
    return Template(
        template_name="index.html",
        context={"user": "Alice", "visits": 42}
    )

参数说明：

template_name：模板文件名（相对于配置的模板目录）
context：传递给模板的上下文数据字典

字符串模板

对于简单场景或动态生成的模板内容，可以直接使用字符串模板：

@get("/greet")
async def greet(name: str) -> Template:
    return Template(
        template_str="Hello, {{ name }}!",
        context={"name": name}
    )

模板上下文详解

访问请求对象

模板中可以直接访问当前请求对象：

<!-- Jinja2语法示例 -->
<div>当前用户: {{ request.user.name }}</div>
<div>应用状态: {{ request.app.state.counter }}</div>

CSRF防护支持

配置CSRF中间件后，可以在表单中添加隐藏的CSRF令牌：

<form method="post">
    {{ csrf_input | safe }}
    <!-- 其他表单字段 -->
</form>

安全提示：必须使用safe过滤器防止HTML转义，确保令牌正确渲染。

模板函数扩展

内置模板函数

Litestar提供了多个有用的内置模板函数：

url_for() - 生成路由URL

<a href="{{ url_for('user_profile', user_id=42) }}">个人资料</a>

csrf_token() - 获取当前CSRF令牌

<meta name="csrf-token" content="{{ csrf_token() }}">

url_for_static_asset() - 生成静态资源URL

<img src="{{ url_for_static_asset('images/logo.png') }}">

自定义模板函数

通过register_template_callable方法注册自定义函数：

def format_currency(value: float) -> str:
    return f"${value:,.2f}"

engine = JinjaTemplateEngine(directory="templates")
engine.register_template_callable("currency", format_currency)

模板中使用：