在FastAPI中返回纯文本（PlainText）的指南

fastapi默认会将字符串返回值自动转换为json响应，导致特殊字符如双引号被转义。本文将详细介绍如何利用plaintextresponse对象来覆盖这一默认行为，从而在fastapi接口中直接返回未经格式化的纯文本内容，确保输出与原始字符串完全一致，适用于需要精确控制响应格式的场景。

FastAPI字符串响应的默认行为

当我们在FastAPI的路由函数中直接返回一个Python字符串时，FastAPI为了提供统一且结构化的API响应，会默认将其序列化为JSON格式。这意味着，如果字符串中包含双引号（"）等特殊字符，它们将根据JSON规范被自动转义，例如，Hello "World"! 会被转换为 "Hello \"World\"!"。这种行为对于大多数API场景是理想的，因为它确保了客户端能够接收到有效的JSON数据。

然而，在某些特定场景下，我们可能需要API接口直接返回未经任何处理的原始文本，例如，提供一个纯文本文件、日志内容或特定格式的非JSON数据。在这种情况下，FastAPI的默认JSON序列化行为就不再适用，因为它会对原始字符串进行修改。

使用 PlainTextResponse 返回纯文本

为了满足直接返回纯文本的需求，FastAPI提供了PlainTextResponse对象。PlainTextResponse是一个特殊的响应类，它指示FastAPI将返回的字符串内容作为text/plain类型的数据直接发送给客户端，而不会进行JSON序列化或字符转义。这意味着，你提供的字符串将原封不动地作为HTTP响应体发送。

实现步骤

要使用PlainTextResponse，你需要完成以下两个主要步骤：

1. 导入 PlainTextResponse： 从fastapi.responses模块中导入PlainTextResponse类。
2. 指定 response_class： 在FastAPI的路由装饰器（如@app.get()、@app.post()等）中，通过设置response_class参数为PlainTextResponse来指定该接口的响应类型。

示例代码

下面是一个具体的示例，展示了如何修改原始代码以返回纯文本。我们将以一个简单的GET请求为例，返回包含双引号的字符串：

TTS Free Online免费文本转语音

免费的文字生成语音网站，包含各种方言（东北话、陕西话、粤语、闽南语）

37

查看详情

import uvicorn
from fastapi import FastAPI
from fastapi.responses import PlainTextResponse # 导入 PlainTextResponse

app = FastAPI()

@app.get(
    "/",
    response_class=PlainTextResponse, # 指定响应类为 PlainTextResponse
)
def read_root():
    """
    返回一个包含双引号的纯文本字符串。
    FastAPI将不会对其进行JSON转义。
    """
    return 'Hello "World"!'

if __name__ == "__main__":
    # 运行FastAPI应用
    # host设置为"127.0.0.1"表示只监听本地回环地址
    # port设置为8000表示在8000端口监听请求
    uvicorn.run(app, host="127.0.0.1", port=8000)

运行此代码后：

当你启动Uvicorn服务器并访问 http://127.0.0.1:8000/ 时，你将直接在浏览器或客户端（例如使用curl命令）中看到 Hello "World"!，没有任何额外的引号或转义字符。响应的Content-Type头部也将被正确设置为text/plain，明确指示客户端这是一个纯文本响应。

注意事项

• 适用场景： PlainTextResponse主要适用于那些明确需要返回原始、非结构化文本的API端点。对于返回结构化数据（如字典、列表、Pydantic模型）的场景，应继续使用FastAPI的默认JSON响应机制，以确保数据的一致性和易用性。
• 内容类型： 使用PlainTextResponse时，FastAPI会自动将HTTP响应的Content-Type头部设置为text/plain。如果需要返回其他纯文本类型（例如text/html或text/csv），可以考虑使用Response类并手动指定media_type。
• 编码： PlainTextResponse默认使用UTF-8编码。如果你的文本内容需要使用不同的编码，可以在实例化PlainTextResponse时通过encoding参数指定。
• 错误处理： 即使是纯文本响应，FastAPI的异常处理机制依然有效。如果路由函数内部发生未捕获的异常，FastAPI仍会返回适当的错误响应（通常是JSON格式，除非你自定义了全局错误处理）。

总结

通过利用FastAPI提供的PlainTextResponse，开发者可以轻松地控制API端点的响应格式，使其能够直接输出未经处理的纯文本内容。这为处理特定类型的数据或与需要精确文本输出的系统集成提供了极大的灵活性。理解并正确应用PlainTextResponse是构建健壮且适应性强的FastAPI应用的关键一步。在选择响应类型时，应根据实际需求权衡默认的JSON行为与自定义的纯文本输出，以实现最佳的API设计。

以上就是在FastAPI中返回纯文本（PlainText）的指南的详细内容，更多请关注php中文网其它相关文章！