FastAPI 响应模型与自定义响应

📚 目录

🎨 自定义响应类型概述
🗂️ 文件上传与下载详解
🍪 自定义响应头与 Cookie 配置

🎨 1. 自定义响应类型概述

在 FastAPI 中，自定义响应类型是开发者实现更丰富输出格式的重要方式。默认情况下，FastAPI 会根据返回的数据自动推断响应的类型，但在实际开发中，需求往往更加复杂，可能需要返回 HTML 页面、纯文本、XML 等不同格式的数据。

🔍 1.1 自定义 HTML 响应

在返回 HTML 页面时，可以直接使用 HTMLResponse。这是 FastAPI 提供的一个非常实用的响应类，能够简化 HTML 内容的返回过程。

🌟 代码示例

python 复制代码

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
def read_root():
    html_content = """
    <html>
        <head>
            <title>Welcome to FastAPI</title>
        </head>
        <body>
            <h1>Hello, FastAPI!</h1>
        </body>
    </html>
    """
    return html_content

🔧 代码解析

response_class=HTMLResponse 指定返回的内容为 HTML 格式。
HTML 内容直接以字符串的形式返回，这种方式在返回静态页面或小型动态页面时非常方便。

🛠️ 1.2 自定义纯文本响应

纯文本响应适用于接口需要返回简洁的字符串内容或错误信息时。

🌟 代码示例

python 复制代码

from fastapi.responses import PlainTextResponse

@app.get("/text", response_class=PlainTextResponse)
def get_text():
    return "This is a plain text response."

🔧 代码解析

使用 PlainTextResponse 返回纯文本数据。
适用于日志、调试信息等文本输出。

📄 1.3 返回 XML 数据

虽然 JSON 是主流的数据格式，但在某些场景下，XML 仍然是不可或缺的数据交换格式。

🌟 代码示例

python 复制代码

from fastapi.responses import Response
from fastapi.encoders import jsonable_encoder

@app.get("/xml", response_class=Response)
def get_xml():
    xml_content = """
    <note>
        <to>User</to>
        <from>FastAPI</from>
        <message>Hello, this is an XML response!</message>
    </note>
    """
    return Response(content=xml_content, media_type="application/xml")

🔧 代码解析

通过 Response 类可以直接返回自定义格式的响应。
media_type 参数指定返回的 MIME 类型为 application/xml。

🗂️ 2. 文件上传与下载详解

文件的上传与下载是 Web 开发中常见的功能。FastAPI 提供了一套便捷的接口用于处理这类需求，确保开发者能够快速实现文件操作。

📤 2.1 文件上传

文件上传的实现依赖于 UploadFile 和 File 类。

🌟 代码示例

python 复制代码

from fastapi import File, UploadFile

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

🔧 代码解析

UploadFile 提供了对上传文件的封装，包含文件名、文件类型和内容。
File(...) 表示该参数为必传项。

📂 多文件上传

python 复制代码

@app.post("/upload/multiple/")
def upload_multiple_files(files: list[UploadFile] = File(...)):
    return {"filenames": [file.filename for file in files]}

🔧 代码解析

接收多个文件的方式是将 UploadFile 封装在列表中。

📥 2.2 文件下载

文件下载通常通过返回 FileResponse 实现。

🌟 代码示例

python 复制代码

from fastapi.responses import FileResponse
import os

@app.get("/download/{file_name}")
def download_file(file_name: str):
    file_path = f"./files/{file_name}"
    if os.path.exists(file_path):
        return FileResponse(path=file_path, filename=file_name)
    return {"error": "File not found"}

🔧 代码解析

FileResponse 提供了直接返回文件的能力。
通过路径参数动态指定文件名称，实现文件的下载。

在 Web 开发中，设置自定义响应头与 Cookie 是提升用户体验和安全性的关键。FastAPI 提供了简单且强大的接口进行这些操作。

🎯 3.1 设置自定义响应头

🌟 代码示例

python 复制代码

from fastapi import Response

@app.get("/custom-header/")
def custom_header(response: Response):
    response.headers["X-Custom-Header"] = "CustomValue"
    return {"message": "Custom header set successfully"}

🔧 代码解析

response.headers 允许直接操作 HTTP 响应头。
可用于添加跟踪标识或安全性相关的头部信息。

🌟 代码示例

python 复制代码

@app.get("/set-cookie/")
def set_cookie(response: Response):
    response.set_cookie(key="user_id", value="12345", httponly=True)
    return {"message": "Cookie set successfully"}

🔧 代码解析

set_cookie 方法允许设置 Cookie 参数。
httponly=True 确保 Cookie 只能通过 HTTP 请求访问，增强安全性。

FastAPI 响应模型与自定义响应