FastAPI自学教程（65） - 模板系统详解

1.基础用法

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

app = FastAPI()

# 挂载静态文件目录
app.mount("/static", StaticFiles(directory="static"), name="static")

# 配置模板目录
templates = Jinja2Templates(directory="templates")

@app.get("/items/{id}", response_class=HTMLResponse)
async def read_item(request: Request, id: str):
    return templates.TemplateResponse(
        request=request, 
        name="item.html", 
        context={"id": id}
    )

通过Jinja2Templates类初始化模板引擎，指定模板文件存储目录
使用TemplateResponse返回渲染后的HTML响应，必须传递request对象

流程图展示模板处理流程：

graph TD
  A[客户端请求] --> B{路径匹配}
  B -->|匹配路由| C[初始化请求上下文]
  C --> D[加载模板文件]
  D --> E[注入上下文变量]
  E --> F[渲染HTML内容]
  F --> G[返回响应]

2.模板上下文机制

2.1 变量传递

1	context={"id": id, "user": current_user}

通过字典形式传递模板变量，支持复杂数据结构（列表/字典/对象）
模板内使用{{ variable }}语法访问变量，如{{ id }}会渲染为实际值

2.2 动态URL生成

1	<a href="{{ url_for('read_item', id=id) }}">详情</a>

使用url_for()函数根据路由名称生成URL，自动处理路径参数
支持多级路径参数和查询参数的动态生成

3.静态文件集成

3.1 引用CSS/JS

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

通过mount挂载静态文件目录后，使用url_for引用静态资源
生产环境建议配置CDN加速静态资源加载

3.2 文件上传处理

1
2
3

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    return {"filename": file.filename}

结合模板实现文件上传表单，注意设置enctype="multipart/form-data"

4.生产环境建议

性能优化：
- 启用模板缓存（Jinja2Templates(auto_reload=False)）
- 使用gzip中间件压缩HTML响应
安全防护：
- 开启XSS防护头Content-Security-Policy
- 对用户输入内容进行HTML转义（Jinja2默认开启）
静态文件配置：
1
app.mount("/assets", StaticFiles(directory="dist"), name="assets")
分离开发环境与生产环境的静态资源路径

测试命令示例：

# 启动服务并访问模板页面
uvicorn main:app --reload --port 8000
# 访问测试页面
curl http://localhost:8000/items/42