如何在FastAPI前端表单下显示异常错误提示而非JSON响应

方案1：后端传递错误信息到模板（传统表单提交） #

核心思路：当表单验证失败时，不返回JSON错误响应，而是重新渲染表单页面并传递错误信息，由前端模板在对应字段下方显示提示。

后端代码（app.py）调整 #

from fastapi import FastAPI, Request, Form
from fastapi.templating import Jinja2Templates
from pydantic import BaseModel, ValidationError, Field

app = FastAPI()
templates = Jinja2Templates(directory="templates")

# 定义Pydantic验证模型
class TodoCreate(BaseModel):
    title: str = Field(..., min_length=2, message="请输入至少2个字符")

@app.get("/todo")
async def show_todo_form(request: Request):
    return templates.TemplateResponse("todo.html", {"request": request})

@app.post("/todo")
async def handle_todo_submit(request: Request, title: str = Form(...)):
    try:
        # 用Pydantic模型验证输入
        TodoCreate(title=title)
        # 执行待办项创建逻辑（如存入数据库）
        return templates.TemplateResponse("todo.html", {
            "request": request,
            "success_msg": "待办项创建成功"
        })
    except ValidationError as e:
        # 提取验证错误信息
        error_msg = e.errors()[0]["msg"]
        # 重新渲染表单页面，传递错误信息
        return templates.TemplateResponse("todo.html", {
            "request": request,
            "title_error": error_msg
        })

前端HTML模板（templates/todo.html）调整 #

在title输入框下方添加错误提示区域，通过模板语法判断是否显示：

<!DOCTYPE html>
<html>
<head>
    <title>待办表单</title>
</head>
<body>
    <h1>添加待办项</h1>
    {% if success_msg %}
        <p style="color: green;">{{ success_msg }}</p>
    {% endif %}
    <form method="post">
        <div>
            <label for="title">标题：</label>
            <input type="text" id="title" name="title" value="{{ request.form.get('title', '') }}">
            <!-- 错误提示区域 -->
            {% if title_error %}
                <p style="color: red; margin: 5px 0 0 0;">{{ title_error }}</p>
            {% endif %}
        </div>
        <button type="submit" style="margin-top: 10px;">提交</button>
    </form>
</body>
</html>

方案2：AJAX异步提交（无页面跳转，体验更流畅） #

核心思路：用JavaScript阻止表单默认跳转行为，通过AJAX异步提交数据，前端直接处理后端返回的JSON错误，动态显示提示。

后端代码（app.py）保留原有验证 #

无需大幅修改，保留Pydantic自动验证逻辑即可：

from fastapi import FastAPI, Form
from pydantic import BaseModel, Field

app = FastAPI()

class TodoCreate(BaseModel):
    title: str = Field(..., min_length=2, message="请输入至少2个字符")

@app.post("/todo")
async def create_todo(title: str = Form(...)):
    # FastAPI自动用模型验证，失败时返回JSON格式的422错误
    TodoCreate(title=title)
    # 执行创建逻辑
    return {"status": "success", "msg": "待办项创建成功"}

前端HTML模板调整 #

添加JavaScript监听表单提交，处理异步请求和错误提示：

<!DOCTYPE html>
<html>
<head>
    <title>待办表单</title>
</head>
<body>
    <h1>添加待办项</h1>
    <form id="todoForm">
        <div>
            <label for="title">标题：</label>
            <input type="text" id="title" name="title">
            <!-- 错误提示元素，默认隐藏 -->
            <p id="titleError" style="color: red; margin: 5px 0 0 0; display: none;"></p>
        </div>
        <button type="submit" style="margin-top: 10px;">提交</button>
    </form>

    <script>
        const form = document.getElementById('todoForm');
        const titleInput = document.getElementById('title');
        const errorElement = document.getElementById('titleError');

        form.addEventListener('submit', async (e) => {
            // 阻止表单默认跳转
            e.preventDefault();
            // 重置错误提示
            errorElement.style.display = 'none';
            
            const formData = new FormData(form);
            const response = await fetch('/todo', {
                method: 'POST',
                body: formData
            });

            if (!response.ok) {
                // 解析后端返回的JSON错误
                const errorData = await response.json();
                // 提取错误信息并显示
                errorElement.textContent = errorData.detail[0].msg;
                errorElement.style.display = 'block';
            } else {
                // 处理成功逻辑
                const successData = await response.json();
                alert(successData.msg);
                // 清空输入框
                titleInput.value = '';
            }
        });
    </script>
</body>
</html>

关键思路总结 #

• 传统表单提交：核心是避免FastAPI返回JSON错误，捕获验证异常后重新渲染模板，将错误信息传递给前端模板展示。
• AJAX异步提交：保留FastAPI默认JSON错误响应，前端通过JS拦截请求、解析错误信息并动态展示，实现无页面跳转的交互。

内容的提问来源于stack exchange，提问作者UGN