FastAPI 响应类参考fastapi.responses 中 FileResponse、StreamingResponse 等九类 Response 详解【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文是fastapi.responses模块的完整参考指南系统梳理 FastAPI 提供的全部 9 个响应类Response、JSONResponse、HTMLResponse、PlainTextResponse、FileResponse、StreamingResponse、RedirectResponse、UJSONResponse、ORJSONResponse、它们的成员属性与使用方式。读完本文你能够直接在路径操作函数中返回自定义响应、通过response_class/default_response_class控制响应行为并理解 FastAPI 自研 JSON 响应类被弃用后 Pydantic 序列化的性能替代方案。从fastapi.responses导入响应类FastAPI 允许在路径操作函数中直接创建并返回响应类实例以此覆盖默认的 JSON 序列化行为。所有可用的响应类都可以直接从fastapi.responses导入from fastapi.responses import ( FileResponse, HTMLResponse, JSONResponse, ORJSONResponse, PlainTextResponse, RedirectResponse, Response, StreamingResponse, UJSONResponse, )从源码结构看fastapi/responses.py中FileResponse、HTMLResponse、JSONResponse、PlainTextResponse、RedirectResponse、Response、StreamingResponse这 7 个类全部是从 Starlette 直接重导出的from starlette.responses import ...FastAPI 只是将它们以fastapi.responses的名义再次暴露方便开发者统一从 FastAPI 包中导入而UJSONResponse和ORJSONResponse则是 FastAPI 自己定义的类目前已被弃用。已弃用的 FastAPI 响应类UJSONResponse 与 ORJSONResponsefastapi.responses中曾有 2 个 FastAPI 自研的响应类设计初衷是优化 JSON 序列化性能UJSONResponse—— 使用ujson库把数据序列化为 JSON。ORJSONResponse—— 使用orjson库把数据序列化为 JSON。这两个类如今均已弃用。当前更推荐的做法是声明响应模型Response Model/ 返回类型让 FastAPI 通过 Pydantic 把数据直接序列化为 JSON 字节Pydantic 在 Rust 层完成序列化性能优于这些自定义 JSON 响应类且不再需要安装额外的第三方库。源码中的弃用证据在 fastapi/responses.py 中可以看到两个类都使用了typing_extensions.deprecated装饰器弃用消息为 FastAPI now serializes data directly to JSON bytes via Pydantic when a return type or response model is set, which is faster and doesnt need a custom response class警告类别是FastAPIDeprecationWarningUJSONResponse.render()的实现是ujson.dumps(content, ensure_asciiFalse).encode(utf-8)ORJSONResponse.render()的实现是orjson.dumps(content, optionorjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY)即同时启用了「允许非字符串键」与「序列化 NumPy 数据」两个 orjson 选项两个类都依赖可选依赖ujson和orjson均不包含在 FastAPI 中需要单独安装例如pip install ujson/pip install orjson。如果对应库未安装模块加载时静默置为None真正调用render()时才会触发assert ... is not None断言失败。tests/test_orjson_response_class.py 用pytest.importorskip(orjson)守卫了可选依赖并通过warnings.catch_warnings()忽略FastAPIDeprecationWarning后验证了ORJSONResponse对非字符串键SQLAlchemy 的quoted_name对象、整数键1也能正确序列化为{msg: Hello World, 1: 1}。这正是OPT_NON_STR_KEYS选项在实际中的体现。两个弃用响应类的成员弃用响应类继承自JSONResponse其参考成员包括charset—— 响应字符集status_code—— HTTP 状态码media_type—— 媒体类型两者均为application/jsonbody—— 响应体background—— 后台任务Background Taskraw_headers—— 原始请求头字节render—— 把内容渲染为bytes的序列化方法两者各自重写的核心init_headers—— 响应头初始化headers—— 响应头set_cookie—— 设置 Cookiedelete_cookie—— 删除 Cookiedocs_src/custom_response/tutorial001_py310.py 展示了UJSONResponse作为response_class的传统用法现已不推荐from fastapi import FastAPI from fastapi.responses import UJSONResponse app FastAPI() app.get(/items/, response_classUJSONResponse) async def read_items(): return [{item_id: Foo}]Starlette 响应类参考除 2 个弃用类外fastapi.responses提供的其余响应类直接来自 Starlette。它们都继承自Response可以逐个查看其成员。Response基类所有其他响应类的基类可以直接返回。参考成员charset—— 响应字符集status_code——int型 HTTP 状态码media_type—— 媒体类型字符串如text/htmlbody—— 响应体background—— 后台任务raw_headers—— 原始响应头字节render—— 序列化钩子返回bytesinit_headers—— 响应头初始化headers—— 响应头set_cookie/delete_cookie—— Cookie 操作直接返回Response的构造参数包括contentstr或bytes、status_codeint、headers字符串字典、media_type如text/html。FastAPI实际是 Starlette会自动附加Content-Length头并基于media_type附加Content-Type头文本类型会追加 charset。FileResponse以流式方式异步发送文件作为响应。除Response的全部成员外额外提供chunk_size—— 分块读取文件的大小参数构造参数与别的响应类不同path—— 要流式传输的文件路径headers—— 自定义响应头字典media_type—— 媒体类型字符串未设置时会根据文件名/路径自动推断filename—— 若设置会写入响应的Content-Disposition头文件响应会自动包含Content-Length、Last-Modified和ETag头。from fastapi import FastAPI from fastapi.responses import FileResponse some_file_path large-video-file.mp4 app FastAPI() app.get(/) async def main(): return FileResponse(some_file_path)也可以放在response_class参数中此时路径操作函数直接返回文件路径字符串即可见 docs_src/custom_response/tutorial009b_py310.py。HTMLResponse接收文本或字节返回 HTML 响应text/html。PlainTextResponse接收文本或字节返回纯文本响应text/plain。JSONResponse接收任意数据返回application/json编码响应是 FastAPI 的默认响应类型。RedirectResponse返回 HTTP 重定向默认使用307Temporary Redirect状态码。StreamingResponse接收异步生成器或普通生成器/迭代器含yield的函数流式发送响应体。除Response全部成员外额外提供body_iterator—— 提供响应体字节的迭代器import anyio from fastapi import FastAPI from fastapi.responses import StreamingResponse app FastAPI() async def fake_video_streamer(): for i in range(10): yield bsome fake video bytes await anyio.sleep(0) app.get(/) async def main(): return StreamingResponse(fake_video_streamer())技术细节异步任务只有在到达await时才能被取消生成器中如果没有await即使请求取消后生成器也可能继续运行。上面的示例特意加入了await anyio.sleep(0)给事件循环一个处理取消的机会——对大型或无限流式响应这一点尤为关键。更推荐使用 FastAPI 内置的流式返回风格见 docs_src/stream_data 与 docs_src/stream_json_lines 相关文档它更便捷且会自动在幕后处理取消逻辑。实战三种使用方式方式一直接返回Response实例在路径操作函数中直接return一个响应实例如RedirectResponsefrom fastapi import FastAPI from fastapi.responses import RedirectResponse app FastAPI() app.get(/typer) async def redirect_typer(): return RedirectResponse(https://typer.tiangolo.com)注意直接返回的Response不会写入 OpenAPI 文档例如Content-Type不会被记录也不会显示在自动交互文档中实际的Content-Type、状态码等来自你返回的Response对象本身。方式二response_class参数在路径操作装饰器中声明response_class函数只需返回原始数据字符串、字典等FastAPI 会把数据装进该响应类app.get(/, response_classFileResponse) async def main(): return some_file_pathresponse_class同时决定了响应在 OpenAPI 中的媒体类型。如果声明的响应类没有媒体类型FastAPI 会认为该响应没有内容从而不在 OpenAPI 文档中记录响应格式。方式三default_response_class全局默认创建FastAPI实例或APIRouter时可以用default_response_class指定默认响应类单个路径操作仍可用response_class覆盖from fastapi import FastAPI from fastapi.responses import HTMLResponse app FastAPI(default_response_classHTMLResponse) app.get(/items/) async def read_items(): return h1Items/h1pThis is a list of items./p自定义响应类重写render()继承Response即可创建自定义响应类核心是重写render(content)方法并返回bytes见 docs_src/custom_response/tutorial009c_py310.pyfrom typing import Any import orjson from fastapi import FastAPI, Response app FastAPI() class CustomORJSONResponse(Response): media_type application/json def render(self, content: Any) - bytes: assert orjson is not None, orjson must be installed return orjson.dumps(content, optionorjson.OPT_INDENT_2) app.get(/, response_classCustomORJSONResponse) async def main(): return {message: Hello World}这个响应会把{message: Hello World}渲染为带两空格缩进的格式化 JSON。性能提示Response Model 优于自定义 JSON 响应如果你的目标是 JSON 序列化性能声明响应模型比写orjson自定义响应更优FastAPI 会用 Pydantic 直接把数据序列化为 JSON 字节省去了jsonable_encoder这类中间转换而 Pydantic 底层使用的 Rust 序列化机制与orjson同源因此响应模型已经能获得最佳性能——这也是UJSONResponse/ORJSONResponse被弃用的根本原因。若确实需要response_class且媒体类型为application/json返回数据会先经过response_model过滤、再由jsonable_encoder转换、最后由标准 JSON 库序列化为字节性能不如纯 Pydantic 路径。小结fastapi.responses提供 9 个响应类7 个重导出自 StarletteResponse、JSONResponse、HTMLResponse、PlainTextResponse、FileResponse、StreamingResponse、RedirectResponse2 个 FastAPI 自研且已弃用UJSONResponse、ORJSONResponse见 fastapi/responses.py所有响应类共享charset、status_code、media_type、body、background、raw_headers、render、init_headers、headers、set_cookie、delete_cookie等成员FileResponse额外提供chunk_sizeStreamingResponse额外提供body_iterator使用上支持三种路径直接返回Response实例、装饰器response_class参数、应用级default_response_classJSON 性能优化请优先采用响应模型/返回类型而不是自定义 JSON 响应类。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FastAPI 响应类参考fastapi.responses 中 FileResponse、StreamingResponse 等九类 Response 详解【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文是fastapi.responses模块的完整参考指南系统梳理 FastAPI 提供的全部 9 个响应类Response、JSONResponse、HTMLResponse、PlainTextResponse、FileResponse、StreamingResponse、RedirectResponse、UJSONResponse、ORJSONResponse、它们的成员属性与使用方式。读完本文你能够直接在路径操作函数中返回自定义响应、通过response_class/default_response_class控制响应行为并理解 FastAPI 自研 JSON 响应类被弃用后 Pydantic 序列化的性能替代方案。从fastapi.responses导入响应类FastAPI 允许在路径操作函数中直接创建并返回响应类实例以此覆盖默认的 JSON 序列化行为。所有可用的响应类都可以直接从fastapi.responses导入from fastapi.responses import ( FileResponse, HTMLResponse, JSONResponse, ORJSONResponse, PlainTextResponse, RedirectResponse, Response, StreamingResponse, UJSONResponse, )从源码结构看fastapi/responses.py中FileResponse、HTMLResponse、JSONResponse、PlainTextResponse、RedirectResponse、Response、StreamingResponse这 7 个类全部是从 Starlette 直接重导出的from starlette.responses import ...FastAPI 只是将它们以fastapi.responses的名义再次暴露方便开发者统一从 FastAPI 包中导入而UJSONResponse和ORJSONResponse则是 FastAPI 自己定义的类目前已被弃用。已弃用的 FastAPI 响应类UJSONResponse 与 ORJSONResponsefastapi.responses中曾有 2 个 FastAPI 自研的响应类设计初衷是优化 JSON 序列化性能UJSONResponse—— 使用ujson库把数据序列化为 JSON。ORJSONResponse—— 使用orjson库把数据序列化为 JSON。这两个类如今均已弃用。当前更推荐的做法是声明响应模型Response Model/ 返回类型让 FastAPI 通过 Pydantic 把数据直接序列化为 JSON 字节Pydantic 在 Rust 层完成序列化性能优于这些自定义 JSON 响应类且不再需要安装额外的第三方库。源码中的弃用证据在 fastapi/responses.py 中可以看到两个类都使用了typing_extensions.deprecated装饰器弃用消息为 FastAPI now serializes data directly to JSON bytes via Pydantic when a return type or response model is set, which is faster and doesnt need a custom response class警告类别是FastAPIDeprecationWarningUJSONResponse.render()的实现是ujson.dumps(content, ensure_asciiFalse).encode(utf-8)ORJSONResponse.render()的实现是orjson.dumps(content, optionorjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY)即同时启用了「允许非字符串键」与「序列化 NumPy 数据」两个 orjson 选项两个类都依赖可选依赖ujson和orjson均不包含在 FastAPI 中需要单独安装例如pip install ujson/pip install orjson。如果对应库未安装模块加载时静默置为None真正调用render()时才会触发assert ... is not None断言失败。tests/test_orjson_response_class.py 用pytest.importorskip(orjson)守卫了可选依赖并通过warnings.catch_warnings()忽略FastAPIDeprecationWarning后验证了ORJSONResponse对非字符串键SQLAlchemy 的quoted_name对象、整数键1也能正确序列化为{msg: Hello World, 1: 1}。这正是OPT_NON_STR_KEYS选项在实际中的体现。两个弃用响应类的成员弃用响应类继承自JSONResponse其参考成员包括charset—— 响应字符集status_code—— HTTP 状态码media_type—— 媒体类型两者均为application/jsonbody—— 响应体background—— 后台任务Background Taskraw_headers—— 原始请求头字节render—— 把内容渲染为bytes的序列化方法两者各自重写的核心init_headers—— 响应头初始化headers—— 响应头set_cookie—— 设置 Cookiedelete_cookie—— 删除 Cookiedocs_src/custom_response/tutorial001_py310.py 展示了UJSONResponse作为response_class的传统用法现已不推荐from fastapi import FastAPI from fastapi.responses import UJSONResponse app FastAPI() app.get(/items/, response_classUJSONResponse) async def read_items(): return [{item_id: Foo}]Starlette 响应类参考除 2 个弃用类外fastapi.responses提供的其余响应类直接来自 Starlette。它们都继承自Response可以逐个查看其成员。Response基类所有其他响应类的基类可以直接返回。参考成员charset—— 响应字符集status_code——int型 HTTP 状态码media_type—— 媒体类型字符串如text/htmlbody—— 响应体background—— 后台任务raw_headers—— 原始响应头字节render—— 序列化钩子返回bytesinit_headers—— 响应头初始化headers—— 响应头set_cookie/delete_cookie—— Cookie 操作直接返回Response的构造参数包括contentstr或bytes、status_codeint、headers字符串字典、media_type如text/html。FastAPI实际是 Starlette会自动附加Content-Length头并基于media_type附加Content-Type头文本类型会追加 charset。FileResponse以流式方式异步发送文件作为响应。除Response的全部成员外额外提供chunk_size—— 分块读取文件的大小参数构造参数与别的响应类不同path—— 要流式传输的文件路径headers—— 自定义响应头字典media_type—— 媒体类型字符串未设置时会根据文件名/路径自动推断filename—— 若设置会写入响应的Content-Disposition头文件响应会自动包含Content-Length、Last-Modified和ETag头。from fastapi import FastAPI from fastapi.responses import FileResponse some_file_path large-video-file.mp4 app FastAPI() app.get(/) async def main(): return FileResponse(some_file_path)也可以放在response_class参数中此时路径操作函数直接返回文件路径字符串即可见 docs_src/custom_response/tutorial009b_py310.py。HTMLResponse接收文本或字节返回 HTML 响应text/html。PlainTextResponse接收文本或字节返回纯文本响应text/plain。JSONResponse接收任意数据返回application/json编码响应是 FastAPI 的默认响应类型。RedirectResponse返回 HTTP 重定向默认使用307Temporary Redirect状态码。StreamingResponse接收异步生成器或普通生成器/迭代器含yield的函数流式发送响应体。除Response全部成员外额外提供body_iterator—— 提供响应体字节的迭代器import anyio from fastapi import FastAPI from fastapi.responses import StreamingResponse app FastAPI() async def fake_video_streamer(): for i in range(10): yield bsome fake video bytes await anyio.sleep(0) app.get(/) async def main(): return StreamingResponse(fake_video_streamer())技术细节异步任务只有在到达await时才能被取消生成器中如果没有await即使请求取消后生成器也可能继续运行。上面的示例特意加入了await anyio.sleep(0)给事件循环一个处理取消的机会——对大型或无限流式响应这一点尤为关键。更推荐使用 FastAPI 内置的流式返回风格见 docs_src/stream_data 与 docs_src/stream_json_lines 相关文档它更便捷且会自动在幕后处理取消逻辑。实战三种使用方式方式一直接返回Response实例在路径操作函数中直接return一个响应实例如RedirectResponsefrom fastapi import FastAPI from fastapi.responses import RedirectResponse app FastAPI() app.get(/typer) async def redirect_typer(): return RedirectResponse(https://typer.tiangolo.com)注意直接返回的Response不会写入 OpenAPI 文档例如Content-Type不会被记录也不会显示在自动交互文档中实际的Content-Type、状态码等来自你返回的Response对象本身。方式二response_class参数在路径操作装饰器中声明response_class函数只需返回原始数据字符串、字典等FastAPI 会把数据装进该响应类app.get(/, response_classFileResponse) async def main(): return some_file_pathresponse_class同时决定了响应在 OpenAPI 中的媒体类型。如果声明的响应类没有媒体类型FastAPI 会认为该响应没有内容从而不在 OpenAPI 文档中记录响应格式。方式三default_response_class全局默认创建FastAPI实例或APIRouter时可以用default_response_class指定默认响应类单个路径操作仍可用response_class覆盖from fastapi import FastAPI from fastapi.responses import HTMLResponse app FastAPI(default_response_classHTMLResponse) app.get(/items/) async def read_items(): return h1Items/h1pThis is a list of items./p自定义响应类重写render()继承Response即可创建自定义响应类核心是重写render(content)方法并返回bytes见 docs_src/custom_response/tutorial009c_py310.pyfrom typing import Any import orjson from fastapi import FastAPI, Response app FastAPI() class CustomORJSONResponse(Response): media_type application/json def render(self, content: Any) - bytes: assert orjson is not None, orjson must be installed return orjson.dumps(content, optionorjson.OPT_INDENT_2) app.get(/, response_classCustomORJSONResponse) async def main(): return {message: Hello World}这个响应会把{message: Hello World}渲染为带两空格缩进的格式化 JSON。性能提示Response Model 优于自定义 JSON 响应如果你的目标是 JSON 序列化性能声明响应模型比写orjson自定义响应更优FastAPI 会用 Pydantic 直接把数据序列化为 JSON 字节省去了jsonable_encoder这类中间转换而 Pydantic 底层使用的 Rust 序列化机制与orjson同源因此响应模型已经能获得最佳性能——这也是UJSONResponse/ORJSONResponse被弃用的根本原因。若确实需要response_class且媒体类型为application/json返回数据会先经过response_model过滤、再由jsonable_encoder转换、最后由标准 JSON 库序列化为字节性能不如纯 Pydantic 路径。小结fastapi.responses提供 9 个响应类7 个重导出自 StarletteResponse、JSONResponse、HTMLResponse、PlainTextResponse、FileResponse、StreamingResponse、RedirectResponse2 个 FastAPI 自研且已弃用UJSONResponse、ORJSONResponse见 fastapi/responses.py所有响应类共享charset、status_code、media_type、body、background、raw_headers、render、init_headers、headers、set_cookie、delete_cookie等成员FileResponse额外提供chunk_sizeStreamingResponse额外提供body_iterator使用上支持三种路径直接返回Response实例、装饰器response_class参数、应用级default_response_classJSON 性能优化请优先采用响应模型/返回类型而不是自定义 JSON 响应类。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
