FastAPI 响应模型与自定义响应
📚 目录
- 🎨 自定义响应类型概述
- 🗂️ 文件上传与下载详解
- 🍪 自定义响应头与 Cookie 配置
🎨 1. 自定义响应类型概述
在 FastAPI 中，自定义响应类型是开发者实现更丰富输出格式的重要方式。默认情况下，FastAPI 会根据返回的数据自动推断响应的类型，但在实际开发中，需求往往更加复杂，可能需要返回 HTML 页面、纯文本、XML 等不同格式的数据。
🔍 1.1 自定义 HTML 响应
在返回 HTML 页面时，可以直接使用 HTMLResponse。这是 FastAPI 提供的一个非常实用的响应类，能够简化 HTML 内容的返回过程。
🌟 代码示例
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 自定义纯文本响应
纯文本响应适用于接口需要返回简洁的字符串内容或错误信息时。
🌟 代码示例
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 仍然是不可或缺的数据交换格式。
🌟 代码示例
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 类。
🌟 代码示例
from fastapi import File, UploadFile
@app.post("/upload/")
def upload_file(file: UploadFile = File(...)):
return {"filename": file.filename}
🔧 代码解析
UploadFile提供了对上传文件的封装，包含文件名、文件类型和内容。File(...)表示该参数为必传项。
📂 多文件上传
@app.post("/upload/multiple/")
def upload_multiple_files(files: list[UploadFile] = File(...)):
return {"filenames": [file.filename for file in files]}
🔧 代码解析
- 接收多个文件的方式是将
UploadFile封装在列表中。
📥 2.2 文件下载
文件下载通常通过返回 FileResponse 实现。
🌟 代码示例
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提供了直接返回文件的能力。- 通过路径参数动态指定文件名称，实现文件的下载。
🍪 3. 自定义响应头与 Cookie 配置
在 Web 开发中，设置自定义响应头与 Cookie 是提升用户体验和安全性的关键。FastAPI 提供了简单且强大的接口进行这些操作。
🎯 3.1 设置自定义响应头
🌟 代码示例
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 响应头。- 可用于添加跟踪标识或安全性相关的头部信息。
🍪 3.2 设置 Cookie
🌟 代码示例
@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 请求访问，增强安全性。
