FastAPI 响应类型详解：默认响应与自定义响应实战

PeterMap
1 阅读6分钟

在 FastAPI 开发中，接口响应是衔接业务逻辑与前端交互的关键环节。默认情况下，FastAPI 会自动处理响应序列化，将 Python 对象转换为 JSON 格式返回，极大简化开发流程。当需要返回 HTML、文件、纯文本等非 JSON 数据时，FastAPI 提供了丰富的内置响应类型，同时支持自定义响应格式，满足不同业务场景需求。本文将聚焦响应类型的核心用法，通过可直接运行的代码示例，讲解默认响应、内置响应类型及自定义响应格式的实现方式。

一、默认响应：JSON 格式自动处理

FastAPI 的默认响应类型为 JSONResponse，无需手动配置，路径操作函数返回的 Python 对象（字典、列表、Pydantic 模型等），会经由 jsonable_encoder 自动转换为 JSON 兼容格式，包装为 JSONResponse 返回，省去手动序列化的麻烦。

from fastapi import FastAPI

# 初始化FastAPI应用
app = FastAPI()

# 默认响应：返回字典，自动转为JSON格式
@app.get("/default-json")
async def default_json_response():
    # 直接返回Python字典，FastAPI自动转为JSON响应
    return {
        "code": 200,
        "msg": "请求成功",
        "data": {"username": "test_user", "role": "normal"}
    }

# 返回列表，同样自动转为JSON格式
@app.get("/list-json")
async def list_json_response():
    return [
        {"id": 1, "name": "示例1"},
        {"id": 2, "name": "示例2"}
    ]

启动应用后，访问任意接口，都会返回标准 JSON 格式数据。例如访问 /default-json，会返回 {"code":200,"msg":"请求成功","data":{"username":"test_user","role":"normal"}}，无需手动处理 JSON 序列化。

二、FastAPI 内置响应类型

当需要返回非 JSON 数据时，FastAPI 提供了多种内置响应类型，可直接导入使用，覆盖 HTML、纯文本、文件下载等常见场景，每种响应类型都有明确的适用场景和简单的使用方式。

1. HTMLResponse：返回 HTML 内容

用于返回 HTML 代码，需在路径装饰器中通过 response_class 指定响应类型，函数直接返回 HTML 字符串即可。

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

# 响应HTML内容，指定response_class为HTMLResponse
@app.get("/html-page", response_class=HTMLResponse)
async def html_response():
    # 返回HTML字符串，FastAPI自动渲染为HTML页面
    return """
    <!DOCTYPE html>
    <html lang="zh-CN">
    <head>
        <meta charset="UTF-8">
        <title>FastAPI HTML响应示例</title>
    </head>
    <body>
        <h1 style="color: #2c3e50;">这是HTML响应页面</h1>
        <p>FastAPI 支持直接返回HTML内容</p>
    </body>
    </html>
    """

2. PlainTextResponse：返回纯文本内容

用于返回纯文本数据，适用于简单的文本反馈场景，同样需通过 response_class 指定响应类型。

from fastapi import FastAPI
from fastapi.responses import PlainTextResponse

app = FastAPI()

# 响应纯文本，指定response_class为PlainTextResponse
@app.get("/plain-text", response_class=PlainTextResponse)
async def plain_text_response():
    # 直接返回字符串，将以纯文本格式响应
    return "FastAPI 纯文本响应示例，无需JSON格式化"

# 结合业务场景：返回简单的状态提示
@app.get("/status", response_class=PlainTextResponse)
async def get_status():
    return "服务运行正常"}

3. FileResponse：返回文件下载/预览

专门用于高效返回文件内容（如图片、PDF、Excel等），支持自动推断文件媒体类型、处理缓存，无需手动读取文件内容，直接传入文件路径即可。

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

# 响应图片文件，支持预览和下载
@app.get("/download-image")
async def download_image():
    # 传入文件路径（相对路径或绝对路径均可）
    file_path = "./images/demo.jpg"
    # 返回FileResponse，自动处理文件响应
    return FileResponse(file_path, filename="demo.jpg")

# 响应PDF文件，直接触发下载
@app.get("/download-pdf")
async def download_pdf():
    file_path = "./documents/example.pdf"
    # filename参数指定下载时的文件名
    return FileResponse(file_path, filename="示例文件.pdf")

4. RedirectResponse：重定向

用于实现页面或接口重定向，传入目标 URL 即可，适用于登录后跳转、页面跳转等场景。

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()

# 重定向到指定URL
@app.get("/redirect")
async def redirect_example():
    # 重定向到FastAPI官方文档
    return RedirectResponse(url="https://fastapi.tiangolo.com/")

# 业务场景：未登录重定向到登录页
@app.get("/home")
async def home():
    # 模拟未登录状态，重定向到登录接口
    return RedirectResponse(url="/login")

@app.get("/login")
async def login():
    return {"msg": "请登录", "login_url": "/login-page"}

三、自定义响应格式：response_model 约束输出

除了内置响应类型，FastAPI 支持通过 response_model 参数自定义响应数据格式。该参数接收一个 Pydantic 模型，用于严格约束接口的输出字段和类型，同时实现自动数据验证和序列化，保障响应数据的规范性和安全性。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义自定义响应模型（约束输出格式）
class UserResponse(BaseModel):
    # 必须返回的字段，类型为整数
    user_id: int
    # 必须返回的字段，类型为字符串
    username: str
    # 可选返回字段，类型为字符串，默认值为None
    email: str | None = None

# 使用response_model指定响应格式
@app.get("/user/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    # 模拟从数据库获取用户数据
    user_data = {
        "user_id": user_id,
        "username": f"user_{user_id}",
        "email": f"user_{user_id}@example.com",
        # 多余字段会被自动过滤，不返回
        "password": "123456"
    }
    # 返回的数据会被response_model约束，多余字段自动剔除
    return user_data

上述代码中，即使返回的字典包含 password 等多余字段，response_model 也会自动过滤，仅返回模型中定义的 user_id、username、email 字段，确保响应格式统一。

四、响应类型的两种设置方式

FastAPI 提供两种设置响应类型的方式，可根据业务场景灵活选择：

  1. 装饰器中指定 response_class：适用于固定响应类型（如 HTML、纯文本），直接在 @app.get、@app.post 等装饰器中设置，简洁高效。
  2. 函数内返回响应对象：适用于动态响应场景（如根据条件返回不同文件、动态重定向），直接在函数中返回对应响应类型的实例。
from fastapi import FastAPI
from fastapi.responses import HTMLResponse, PlainTextResponse

app = FastAPI()

# 方式1：装饰器中指定response_class（固定响应类型）
@app.get("/fixed-html", response_class=HTMLResponse)
async def fixed_html():
    return "<h1>固定HTML响应</h1>"

# 方式2：函数内返回响应对象（动态响应类型）
@app.get("/dynamic-response")
async def dynamic_response(type: str):
    if type == "html":
        return HTMLResponse("<h1>动态HTML响应</h1>")
    elif type == "text":
        return PlainTextResponse("动态纯文本响应")
    else:
        return {"msg": "默认JSON响应"}

总结

FastAPI 的响应类型设计简洁高效，既能自动处理默认 JSON 响应，又能通过内置响应类型满足多样化需求，同时支持自定义响应格式，适配不同业务场景：

  • 默认响应：无需配置，自动将 Python 对象转为 JSON 格式，适用于大多数接口场景；
  • 内置响应类型：HTMLResponse、PlainTextResponse、FileResponse 等，直接导入即可使用，覆盖非 JSON 响应场景；
  • 自定义响应：通过 response_model 结合 Pydantic 模型，约束响应格式，保障数据规范和安全。

掌握响应类型的核心用法，能让接口响应更灵活、规范，更好地衔接前端交互，提升接口开发的效率和质量。

avatar
文章
阅读
粉丝