在FastAPI开发中，我们经常需要向客户端返回一段不带任何格式的纯文本，例如健康检查探针结果、简单的校验提示或者日志快照。但不少人在刚接触时发现，自己明明返回了一个字符串，前端接收到的却是被双引号包裹的JSON字符串。这是因为FastAPI基于Starlette，默认会把视图函数返回的Python对象当作JSON进行序列化。要实现真正的纯文本输出，必须理解响应模型的封装逻辑并主动控制响应类型。
一、为什么直接返回字符串会变成JSON
FastAPI的路由函数如果返回的是基础类型（如str、int、dict），且没有声明response_class，框架会调用默认的JSONResponse来处理。对于字符串，JSON标准规定字符串必须用双引号包围，于是前端拿到的是类似"hello"这样的内容，而不是hello。这种处理在需要提供API给JavaScript前端时很方便，但在纯文本场景下反而成了障碍。
另外一个容易忽略的点是，当使用ResponseModel或者依赖了某些中间件时，返回内容还可能经过额外的编码或包装。因此如果只是想输出一段人类可读的文本，依赖默认行为并不可靠。下面通过代码看看默认情况下的表现。
from fastapi import FastAPI
app = FastAPI()
@app.get("/default")
def default_text():
return "服务正常运行"
上面这段代码访问 /default 时，响应体是带引号的字符串，Content-Type 为 application/json。如果客户端是一个简单的Shell脚本或监控探针，它就需要自己去掉引号才能使用，这显然不够友好。
二、使用Response显式返回纯文本
最直接的做法是返回一个Starlette的Response对象，并在构造时指定media_type为text/plain。这样FastAPI就不会再用JSON序列化，而是把字符串原样写进响应体。这种方式灵活度最高，你可以同时控制状态码、头部信息等。
需要注意，Response的第一个参数是字符串内容，如果传入的不是字符串需要先转换。另外字符编码默认是utf-8，对于中文场景通常无需修改，但如果有特殊编码需求可以通过headers设置。下面给出一个基础示例：
from fastapi import FastAPI
from fastapi.responses import Response
app = FastAPI()
@app.get("/raw")
def raw_text():
content = "当前节点存活，内存使用率正常"
return Response(content=content, media_type="text/plain")
此时访问 /raw，响应体就是干净的文本，Content-Type变为text/plain。这种方式适合需要完全掌控响应结构的场景，比如代理转发一段外部文本。
三、使用PlainTextResponse简化写法
FastAPI提供了PlainTextResponse这个专用子类，语义更清晰，代码也更短。它本质上就是预设了media_type为text/plain的Response，但在可读性上更好，其他同事一眼就能明白接口的意图。
除了直接返回实例，也可以在路由装饰器里通过response_class参数声明，这样函数体内直接返回字符串即可，框架会自动用指定的类包装。两种写法各有适用面，前者适合偶发需求，后者适合整个接口都固定输出文本的情况。
from fastapi import FastAPI
from fastapi.responses import PlainTextResponse
app = FastAPI()
# 写法一：函数内返回实例
@app.get("/plain")
def plain():
return PlainTextResponse("订单校验通过，可以提交")
# 写法二：装饰器声明response_class
@app.get("/probe", response_class=PlainTextResponse)
def probe():
return "OK"
上述代码中，/plain和/probe最终都返回纯文本。第二种写法让视图函数保持返回原生字符串，由框架负责包装，逻辑更简洁。如果你的接口只做文本输出，推荐用response_class声明，减少重复代码。
四、自定义状态码与头部
纯文本接口常常需要配合非200状态码，例如校验失败返回400，或者探针异常返回503。使用Response或PlainTextResponse时，可以传入status_code参数。同时还能通过headers添加缓存控制或跨域允许头部。
在依赖注入函数中也可以返回文本响应，实现统一的鉴权失败提示。但要注意，如果依赖里返回了Response对象，主路由函数返回的将是依赖中的响应，主函数逻辑不会继续执行，这是Starlette的设计机制。
from fastapi import FastAPI, HTTPException
from fastapi.responses import PlainTextResponse
app = FastAPI()
@app.get("/check")
def check(token: str = ""):
if token != "secret":
return PlainTextResponse("令牌无效", status_code=401)
return PlainTextResponse("验证成功", headers={"X-Cache": "no-store"})
上面示例在令牌错误时返回401状态和纯文本错误说明，正确时返回带自定义头部的文本。这样监控系统和人工排查都能直接读取内容。
五、不同方案对比与选型建议
为了更直观地看出差异，我们把三种常见方式放在一张表里比较。实际项目中应根据接口定位来选择，而不是盲目统一。
| 返回方式 | 响应体格式 | Content-Type | 适用场景 |
|---|---|---|---|
| 直接返回字符串 | 带引号JSON字符串 | application/json | 前端JS消费的API |
| Response + text/plain | 原始文本 | text/plain | 需要精细控制头部和状态 |
| PlainTextResponse | 原始文本 | text/plain | 固定文本输出接口 |
从维护成本看，装饰器声明response_class最省心；从灵活性看，手动构造Response能力最强。若接口可能被多种客户端调用，纯文本加正确的Content-Type能避免解析歧义。
最后提醒，纯文本并不意味着可以忽视安全。如果文本中包含用户输入，仍要防范换行注入响应头或敏感信息泄露。在FastAPI中返回纯文本响应，核心就是主动声明媒体类型，别让框架替你做JSON假设。