自定义响应 - HTML，流，文件和其他

    你可以通过直接返回 Response 来重载它，参见 直接返回响应。

    但如果你直接返回 Response，返回数据不会自动转换，也不会自动生成文档（例如，在 HTTP 头 Content-Type 中包含特定的「媒体类型」作为生成的 OpenAPI 的一部分）。

    你还可以在 路径操作装饰器 中声明你想用的 Response。

    你从 路径操作函数 中返回的内容将被放在该 Response 中。

    并且如果该 Response 有一个 JSON 媒体类型（application/json），比如使用 JSONResponse 或者 UJSONResponse 的时候，返回的数据将使用你在路径操作装饰器中声明的任何 Pydantic 的 response_model 自动转换（和过滤）。

    说明

    如果你使用不带有任何媒体类型的响应类，FastAPI 认为你的响应没有任何内容，所以不会在生成的OpenAPI文档中记录响应格式。

    例如，如果你需要压榨性能，你可以安装并使用 orjson 并将响应设置为 ORJSONResponse。

    导入你想要使用的 Response 类（子类）然后在 路径操作装饰器 中声明它。

    提示

    参数 response_class 也会用来定义响应的「媒体类型」。

    在这个例子中，HTTP 头的 Content-Type 会被设置成 application/json。

    并且在 OpenAPI 文档中也会这样记录。

    小贴士

    ORJSONResponse 目前只在 FastAPI 中可用，而在 Starlette 中不可用。

    使用 HTMLResponse 来从 FastAPI 中直接返回一个 HTML 响应。

    • 导入 HTMLResponse。
    • 将 HTMLResponse 作为你的 路径操作 的 response_class 参数传入。
    1. from fastapi import FastAPI
    2. from fastapi.responses import HTMLResponse
    4. app = FastAPI()
    7. @app.get("/items/", response_class=HTMLResponse)
    8. async def read_items():
    9.     return """
    10.     <html>
    11.         <head>
    12.             <title>Some HTML in here</title>
    13.         </head>
    14.         <body>
    15.             <h1>Look ma! HTML!</h1>
    16.         </body>
    17.     </html>
    18.     """

    提示

    参数 response_class 也会用来定义响应的「媒体类型」。

    在这个例子中，HTTP 头的 Content-Type 会被设置成 text/html。

    并且在 OpenAPI 文档中也会这样记录。

    和上面一样的例子，返回一个 HTMLResponse 看起来可能是这样：

    1. from fastapi import FastAPI
    2. from fastapi.responses import HTMLResponse
    6. @app.get("/items/")
    7. async def read_items():
    9.     <html>
    10.         <head>
    11.             <title>Some HTML in here</title>
    12.         </head>
    13.         <body>
    14.             <h1>Look ma! HTML!</h1>
    15.         </body>
    16.     </html>
    17.     """
    18.     return HTMLResponse(content=html_content, status_code=200)

    警告

    路径操作函数 直接返回的 Response 不会被 OpenAPI 的文档记录（比如，Content-Type 不会被文档记录），并且在自动化交互文档中也是不可见的。

    提示

    当然，实际的 Content-Type 头，状态码等等，将来自于你返回的 Response 对象。

    OpenAPI 中的文档和重载 Response

    如果你想要在函数内重载响应，但是同时在 OpenAPI 中文档化「媒体类型」，你可以使用 response_class 参数并返回一个 Response 对象。

    接着 response_class 参数只会被用来文档化 OpenAPI 的 路径操作，你的 Response 用来返回响应。

    直接返回 HTMLResponse

    比如像这样：

    在这个例子中，函数 generate_html_response() 已经生成并返回 Response 对象而不是在 str 中返回 HTML。

    通过返回函数 generate_html_response() 的调用结果，你已经返回一个重载 FastAPI 默认行为的 Response 对象，

    但如果你在 response_class 中也传入了 HTMLResponse，FastAPI 会知道如何在 OpenAPI 和交互式文档中使用 text/html 将其文档化为 HTML。

    这里有一些可用的响应。

    要记得你可以使用 Response 来返回任何其他东西，甚至创建一个自定义的子类。

    技术细节

    你也可以使用 from starlette.responses import HTMLResponse。

    FastAPI 提供了同 fastapi.responses 相同的 starlette.responses 只是为了方便开发者。但大多数可用的响应都直接来自 Starlette。

    Response

    其他全部的响应都继承自主类 Response。

    你可以直接返回它。

    Response 类接受如下参数：

    • content - 一个 str 或者 bytes。
    • status_code - 一个 int 类型的 HTTP 状态码。
    • headers - 一个由字符串组成的 dict。
    • media_type - 一个给出媒体类型的 str，比如 "text/html"。
    1. from fastapi import FastAPI, Response
    3. app = FastAPI()
    6. @app.get("/legacy/")
    7. def get_legacy_data():
    8.     data = """<?xml version="1.0"?>
    9.     <shampoo>
    10.     <Header>
    11.         Apply shampoo here.
    12.     </Header>
    13.     <Body>
    14.         You'll have to use soap here.
    15.     </Body>
    16.     </shampoo>
    17.     """
    18.     return Response(content=data, media_type="application/xml")

    如上文所述，接受文本或字节并返回 HTML 响应。

    PlainTextResponse

    接受文本或字节并返回纯文本响应。

    1. from fastapi import FastAPI
    6. @app.get("/", response_class=PlainTextResponse)
    7. async def main():
    8.     return "Hello World"

    JSONResponse

    接受数据并返回一个 application/json 编码的响应。

    如上文所述，这是 FastAPI 中使用的默认响应。

    ORJSONResponse

    如上文所述，ORJSONResponse 是一个使用 的快速的可选 JSON 响应。

    UJSONResponse 是一个使用 的可选 JSON 响应。

    警告

    在处理某些边缘情况时，ujson 不如 Python 的内置实现那么谨慎。

    小贴士

    ORJSONResponse 可能是一个更快的选择。

    RedirectResponse

    返回 HTTP 重定向。默认情况下使用 307 状态代码（临时重定向）。

    1. from fastapi import FastAPI
    2. from fastapi.responses import RedirectResponse
    4. app = FastAPI()
    7. @app.get("/typer")
    8. async def redirect_typer():
    9.     return RedirectResponse("https://typer.tiangolo.com")

    StreamingResponse

    采用异步生成器或普通生成器/迭代器，然后流式传输响应主体。

    1. from fastapi import FastAPI
    2. from fastapi.responses import StreamingResponse
    4. app = FastAPI()
    7. async def fake_video_streamer():
    8.     for i in range(10):
    9.         yield b"some fake video bytes"
    12. @app.get("/")
    13. async def main():
    14.     return StreamingResponse(fake_video_streamer())

    对类似文件的对象使用 StreamingResponse

    如果您有类似文件的对象（例如，由 open() 返回的对象），则可以在 StreamingResponse 中将其返回。

    包括许多与云存储，视频处理等交互的库。

    小贴士

    注意在这里，因为我们使用的是不支持 async 和 await 的标准 open()，我们使用普通的 def 声明了路径操作。

    FileResponse

    异步传输文件作为响应。

    与其他响应类型相比，接受不同的参数集进行实例化：

    • path - 要流式传输的文件的文件路径。
    • headers - 任何自定义响应头，传入字典类型。
    • media_type - 给出媒体类型的字符串。如果未设置，则文件名或路径将用于推断媒体类型。
    • filename - 如果给出，它将包含在响应的 Content-Disposition 中。

    文件响应将包含适当的 Content-Length，Last-Modified 和 ETag 的响应头。

    1. from fastapi import FastAPI
    2. from fastapi.responses import FileResponse
    4. some_file_path = "large-video-file.mp4"
    5. app = FastAPI()
    8. @app.get("/")
    9.     return FileResponse(some_file_path)

    您还可以使用 在 OpenAPI 中声明媒体类型和许多其他详细信息：。