【FastAPI】 响应类型详解：从默认 JSON 到自定义响应

FastAPI 响应类型详解从默认 JSON 到自定义响应HTML/文件/流/重定向一、FastAPI 响应机制概述FastAPI 默认会将路径操作函数返回的 Python 对象如dict、list、Pydantic Model自动转换为JSON 格式并通过JSONResponse返回客户端。转换依赖jsonable_encoder无需手动序列化。return{message:Hello World}# 自动转为 JSON但若需返回非 JSON 数据如 HTML、文件、流、纯文本等必须显式指定响应类型。二、响应类型设置方式共 6 种方式一在app.get()装饰器中设置response_class适用场景固定返回类型如HTML、纯文本、文件非动态流式fromfastapiimportFastAPIfromfastapi.responsesimportHTMLResponse,PlainTextResponse,FileResponse appFastAPI()app.get(/,response_classHTMLResponse)asyncdefroot():returnh1这是一级标题/h1响应类型response_class用途HTMLResponseHTMLResponse返回 HTML 内容如网页PlainTextResponsePlainTextResponse返回纯文本不含 HTML 标签FileResponseFileResponse返回文件下载如图片、txt、pdf示例纯文本响应app.get(/text,response_classPlainTextResponse)asyncdefget_text():return这是纯文本示例文件下载app.get(/file/txt,response_classFileResponse)asyncdefget_file():return./files/1.txt 注意FileResponse会自动设置Content-Disposition: attachment触发下载。方式二直接返回响应对象推荐用于动态响应适用场景文件流、图片、自定义 MIME 类型、重定向、流式响应返回图片FileResponseapp.get(/file/picture)asyncdefget_picture():returnFileResponse(./files/1.png)自动设置Content-Type: image/png流式响应StreamingResponsefromfastapi.responsesimportStreamingResponseapp.get(/stream)asyncdefget_stream():defiter_file():withopen(./files/1.png,rb)asf:whilechunk:f.read(1024):yieldchunkreturnStreamingResponse(iter_file(),media_typeimage/png)使用生成器函数模拟流式传输适用于大文件、视频流等。自定义 MIME 类型与文件名app.get(/file/download)asyncdefdownload_file():returnFileResponse(path./files/1.txt,media_typetext/plain,# 自定义 MIME 类型filenamenews.txt# 下载时的文件名)可通过filename设置下载后文件名打破原文件名限制。方式三使用RedirectResponse重定向fromfastapi.responsesimportRedirectResponseapp.get(/redirect)asyncdefredirect_to_home():returnRedirectResponse(url/)浏览器将跳转到/地址返回302状态码。重定向到外链如百度app.get(/to-baidu)asyncdefto_baidu():returnRedirectResponse(urlhttps://www.baidu.com)方式四自定义响应数据格式response_model Pydantic用Pydantic 模型定义 API 返回结构实现类型安全与文档自动生成。步骤 1定义 Pydantic 模型frompydanticimportBaseModelclassNews(BaseModel):id:inttitle:strcontent:str步骤 2在路由中启用response_modelapp.get(/news/{id},response_modelNews)asyncdefget_news(id:int):return{id:id,title:这是新闻标题,content:这是新闻内容}如果返回数据不符合News模型结构 → FastAPI 会返回422错误Swagger UI 会根据response_model生成响应示例三、FastAPI 响应类型总结表响应类型用途何时使用示例JSONResponse默认返回 JSON 数据一般 API 接口return {msg: ok}HTMLResponse返回 HTML 内容页面渲染、内嵌 HTMLresponse_classHTMLResponsePlainTextResponse返回纯文本日志、简单信息response_classPlainTextResponseFileResponse文件下载下载 PDF、TXT、图片return FileResponse(./file.txt)StreamingResponse流式响应大文件、视频、音频流StreamingResponse(generator, media_typevideo/mp4)RedirectResponse重定向跳转页面、登录后跳转return RedirectResponse(url/)四、易错点 注意事项易错点说明解决方案❌response_class放在函数外导致AttributeError必须在装饰器里写response_class...❌FileResponse路径写错文件找不到返回 404使用os.path或Path拼接路径❌ 流式响应未使用生成器报错或无法传输用def iter_func(): yield chunk❌response_model返回字段类型不匹配返回422错误保证数据完全符合模型结构❌ 忘记import响应类编译错误一定要导入from fastapi.responses import ...五、完整代码示例可直接运行fromfastapiimportFastAPIfromfastapi.responsesimport(HTMLResponse,PlainTextResponse,FileResponse,StreamingResponse,RedirectResponse)frompydanticimportBaseModelimportos appFastAPI()# 1. 默认 JSON 响应自动app.get(/)asyncdefroot():return{message:Hello World}# 2. HTML 响应固定类型app.get(/html,response_classHTMLResponse)asyncdefget_html():returnh1这是网页标题/h1# 3. 纯文本响应app.get(/text,response_classPlainTextResponse)asyncdefget_text():return这是纯文本内容# 4. 文件下载自动触发下载app.get(/file/download)asyncdefget_txt():returnFileResponse(./files/1.txt,filenamenews.txt)# 5. 图片响应app.get(/image)asyncdefget_image():returnFileResponse(./files/1.png)# 6. 流式响应支持大文件app.get(/stream)asyncdefstream_video():defiter_file():withopen(./files/1.png,rb)asf:whilechunk:f.read(1024):yieldchunkreturnStreamingResponse(iter_file(),media_typeimage/png)# 7. 重定向app.get(/redirect)asyncdefredirect_home():returnRedirectResponse(url/)# 8. 自定义响应数据格式Pydantic response_modelclassNews(BaseModel):id:inttitle:strcontent:strapp.get(/news/{id},response_modelNews)asyncdefget_news(id:int):return{id:id,title:FastAPI 响应类型详解,content:学习 FastAPI 的重要知识点}