吃透FastAPI的响应类型

1. 最傻瓜的方式直接返回字典默认JSON响应这是你最先接触的用法。FastAPI会自动把字典、列表等转成JSON并设置响应头Content-Type: application/json。from fastapi import FastAPI app FastAPI() app.get(/) def read_root(): # 直接返回一个字典 return {message: Hello World}访问机会得到{message: Hello World}2. 用response_model规定输出的数据形状response_model就像一个质检员它会把你函数返回的数据转换成指定的Pydantic模型结构过滤掉不想让客户端看到的字段比如密码自动生成API文档from pydantic import BaseModel class UserIn(BaseModel): # 用于输入注册 username: str password: str class UserOut(BaseModel): # 用于输出返回给客户端 username: str app.post(/user, response_modelUserOut) def create_user(user: UserIn): # 虽然返回的是包含password的user但response_model会把它过滤掉 return user客户端调用后只会收到 {username: xxx}password字段被自动去除。怎么用把Pydantic模型写在装饰器的response_model参数里还可以用response_model_include/response_model_exclude进一步控制显示/隐藏字段如果不需要过滤可以不写response_model但写上可以提高文档质量和安全性3. 直接返回各种“封装好的响应盒子”Response对象当你想控制更多细节比如状态码、响应头、Cookie或者返回非JSON内容时就要直接返回一个Response对象或其子类。这些类都在fastapi.responses里。 JSONResponse —— 手工打造JSON响应如果你需要在返回JSON的同时设置自定义头或状态码就可以用这个。from fastapi.responses import JSONResponse app.get(/custom-json) def custom_json(): content {msg: 手工打造} return JSONResponse( contentcontent, status_code201, # 自定义状态码 headers{X-Custom: foo} # 自定义响应头 ) HTMLResponse —— 返回网页from fastapi.responses import HTMLResponse app.get(/page, response_classHTMLResponse) def get_page(): html h1你好/h1p这是HTML页面/p return html你也可以不用response_class参数直接返回HTMLResponse实例return HTMLResponse(contenth1.../h1, status_code200)✍️ PlainTextResponse —— 纯文本from fastapi.responses import PlainTextResponse app.get(/text, response_classPlainTextResponse) def get_text(): return 这是一段纯文本不是HTML也不是JSON RedirectResponse —— 重定向from fastapi.responses import RedirectResponse app.get(/old) def old_page(): return RedirectResponse(/new-page)访问 /old 时浏览器会自动跳转到/new-page。 FileResponse —— 文件下载from fastapi.responses import FileResponse app.get(/download) def download(): file_path example.png return FileResponse( pathfile_path, filenamedownload-name.png, # 让浏览器看到的名字 media_typeimage/png # 可选自动识别 ) StreamingResponse —— 流式响应大数据、实时输出适合返回很大的数据流如AI生成内容、视频流、SSE。from fastapi.responses import StreamingResponse def data_generator(): for i in range(10): yield f第{i}条数据\n app.get(/stream) def stream(): return StreamingResponse(data_generator(), media_typetext/plain)4. 在装饰器里设置response_class —— 改变默认响应格式如果你希望一个路由返回某些内容时自动被包裹成指定的响应类而不用在函数内手动创建响应对象就用response_class参数。最常见的例子返回字符串时默认是JSON字符串带引号但我们想返回HTML/纯文本。app.get(/auto-html, response_classHTMLResponse) def auto_html(): # 直接返回字符串FastAPI会用HTMLResponse包装 return h1我是自动生成的HTML/h1如果不写response_classHTMLResponse你会看到带引号的字符串 h1.../h1而不是被浏览器渲染的HTML。总结response_class相当于告诉FastAPI“这个路由内部返回的任何数据都用这种盒子发出去”。5. 文档中声明额外响应不同状态码的模型当你希望OpenAPI文档里展示某个接口在错误状态码如404时返回的数据结构可以使用responses参数。from pydantic import BaseModel class Message(BaseModel): message: str app.get( /items/{item_id}, response_modeldict, responses{ 404: {model: Message, description: 物品未找到}, 200: {description: 成功返回物品数据} } ) async def read_item(item_id: str): if item_id ! 123: return JSONResponse(status_code404, content{message: 找不到物品}) return {item_id: item_id, value: 重要资料}这样Swagger文档里就会清楚说明404会返回{message: ...}。6. 更高级的响应类性能优化如果对JSON序列化性能有要求可以安装orjson然后使用ORJSONResponse替代默认的JSONResponse。from fastapi.responses import ORJSONResponse app FastAPI(default_response_classORJSONResponse) # 全局使用 app.get(/fast-json) def fast_json(): return {data: [1,2,3]}总结什么时候用什么你想要的响应 用什么 返回JSON字典/列表接受默认状态码200 直接return dict 返回JSON但想把密码等字段藏起来 加response_modelOutputModel 返回JSON需要自定义状态码/头部 return JSONResponse(...) 返回HTML、纯文本、重定向、文件、流 使用对应的HTMLResponse等 整个路由都要返回HTML简化代码 装饰器里写response_classHTMLResponse 需要在文档里标明404等错误格式 使用responses{...}参数