路径函数完成后,FastAPI 需要把 Python 结果转换成 HTTP 响应。一个响应不只有 JSON 数据,还包括状态码、响应头和媒体类型:
1HTTP/1.1 200 OK 2Content-Type: application/json 3 4{"answer":"FastAPI 是一个 Python Web 框架。"}
FastAPI 默认很适合 JSON API。返回字典、列表或 Pydantic 模型时,它会把结果编码成 JSON,并设置合适的 Content-Type。
Content-Type
本文的完整可请求案例位于 src/fastapi/api/res/,每个下划线命名的 Python 文件对应一个独立路由模块;它们统一由 res/__init__.py 聚合。文章中的说明性表格、HTTP 报文和文字解释不对应项目文件。
src/fastapi/api/res/
res/__init__.py
res/__init__.py 负责声明响应案例的领域前缀,并聚合各个案例。上层 api/router.py 将整个响应案例模块挂载到 /api/v1:
api/router.py
/api/v1
01from fastapi import APIRouter 02 03from . import ( 04 create_response, 05 direct_json_response, 06 documented_responses, 07 dynamic_status, 08 exclude_unset, 09 file_response, 10 no_content, 11 response_classes, 12 response_cookie, 13 response_header, 14 response_model, 15 return_model, 16 serialization, 17) 18 19# /api/v1 由上层聚合路由统一添加,本模块只声明自己的领域前缀。 20router = APIRouter(prefix="/res", tags=["responses"]) 21 22router.include_router(serialization.router) 23router.include_router(response_model.router) 24router.include_router(return_model.router) 25router.include_router(create_response.router) 26router.include_router(dynamic_status.router) 27router.include_router(exclude_unset.router) 28router.include_router(response_header.router) 29router.include_router(response_cookie.router) 30router.include_router(response_classes.router) 31router.include_router(direct_json_response.router) 32router.include_router(file_response.router) 33router.include_router(no_content.router) 34router.include_router(documented_responses.router)
因此,案例文件中的相对路径会统一组合成 /api/v1/res/...。
/api/v1/res/...
JSON 只支持有限的数据类型,但 Python 还包含日期、UUID 和模型对象。FastAPI 会根据路径函数有没有声明响应模型,选择不同的序列化方式:
response_model
jsonable_encoder
JSONResponse
Response
我们先来看没有显式响应模型时最常见的写法:
下面的案例请求一个固定 UUID 对应的会话,并同时展示正文、状态码、响应头和响应 URL:
01from datetime import datetime, timezone 02from uuid import UUID 03 04from fastapi import APIRouter 05 06router = APIRouter() 07 08@router.get("/conversations/{conversation_id}") 09async def get_conversation(conversation_id: UUID) -> dict[str, UUID | datetime]: 10 return { 11 "id": conversation_id, 12 "created_at": datetime.now(timezone.utc), 13 }
UUID 和时间会转换成 JSON 字符串。时间字段应明确时区,跨系统传输时通常使用 UTC 和 ISO 8601 格式,不要返回依赖服务器本地时区的模糊时间。
即使没有显式设置 response_model,有效的返回类型也会参与建立响应模型,FastAPI 会通过 Pydantic 完成响应校验与序列化。只有没有有效响应模型的普通返回值,才会交给 jsonable_encoder() 转换;不能仅根据装饰器中没有 response_model 就判断转换路径。
jsonable_encoder()
使用 response_model 可以声明并校验公开响应:
下面的案例可以直接观察公开响应中只有 id 和 name,服务端返回的 password_hash 会被响应模型过滤:
id
name
password_hash
01from fastapi import APIRouter 02from pydantic import BaseModel 03 04router = APIRouter() 05 06class UserRead(BaseModel): 07 id: str 08 name: str 09 10@router.get("/users/{user_id}", response_model=UserRead) 11async def get_user(user_id: str) -> dict[str, str]: 12 return { 13 "id": user_id, 14 "name": "小微", 15 "password_hash": "internal-value", 16 }
响应中只会保留 UserRead 声明的字段,password_hash 不会发送给客户端。这种过滤是重要的安全边界,但不能代替正确的数据分层:业务代码也不应该随意把敏感对象交给响应层。
UserRead
可以直接把返回类型写成 Pydantic 模型:
这个案例请求使用返回类型声明响应模型的接口,它与上一个案例采用不同声明方式,但都会经过响应校验和序列化:
01from fastapi import APIRouter 02from pydantic import BaseModel 03 04router = APIRouter() 05 06class UserRead(BaseModel): 07 id: str 08 name: str 09 10@router.get("/typed-users/{user_id}") 11async def get_user(user_id: str) -> UserRead: 12 return UserRead(id=user_id, name="小微")
返回类型和 response_model 都能参与运行时响应校验、序列化、字段过滤和文档生成。它们不是只给编辑器看的类型提示。
两者同时存在时,response_model 优先。一般可以按下面的方式选择:
-> UserRead
response_model=UserRead
response_model=None
响应数据不符合模型时,通常意味着服务端实现违反了自己的契约。FastAPI 会把它作为服务器错误处理,而不是向客户端返回 422。422 主要表示客户端提交的请求无法通过校验。
创建资源时,输入和输出应使用不同模型:
下面的案例会提交会话标题。请求成功后,可以在响应元数据中观察 201 状态码以及浏览器允许读取的响应头:
01from datetime import datetime, timezone 02from uuid import uuid4 03 04from fastapi import APIRouter, Response, status 05from pydantic import BaseModel 06 07router = APIRouter() 08 09 10class ConversationCreate(BaseModel): 11 title: str 12 13 14class ConversationRead(BaseModel): 15 id: str 16 title: str 17 created_at: datetime 18 19 20@router.post( 21 "/conversations", 22 response_model=ConversationRead, 23 status_code=status.HTTP_201_CREATED, 24) 25async def create_conversation( 26 payload: ConversationCreate, 27 response: Response, 28) -> ConversationRead: 29 conversation_id = str(uuid4()) 30 response.headers["Location"] = f"/api/v1/res/conversations/{conversation_id}" 31 32 return ConversationRead( 33 id=conversation_id, 34 title=payload.title, 35 created_at=datetime.now(timezone.utc), 36 )
客户端只提供标题,服务器负责生成 ID 和时间。响应模型把这种所有权写进了接口契约。201 Created 表示服务器创建了新资源,Location 响应头进一步告诉客户端可以从哪里访问它。
201 Created
Location
固定状态码写在路径装饰器中,动态状态码可以通过 Response 参数调整:
第一次提交新的 item_id 时接口返回 201,再次提交同一个 ID 时返回 200。可以修改 ID 和查询参数 value 观察状态变化:
item_id
value
01from fastapi import APIRouter, Response, status 02from pydantic import BaseModel 03 04router = APIRouter() 05 06 07class ItemRead(BaseModel): 08 id: str 09 value: str 10 11 12items: dict[str, str] = {} 13 14 15@router.put( 16 "/items/{item_id}", 17 response_model=ItemRead, 18 responses={ 19 201: { 20 "model": ItemRead, 21 "description": "创建了新资源", 22 }, 23 }, 24) 25async def upsert_item( 26 item_id: str, 27 value: str, 28 response: Response, 29) -> dict[str, str]: 30 created = item_id not in items 31 items[item_id] = value 32 33 if created: 34 response.status_code = status.HTTP_201_CREATED 35 response.headers["Location"] = f"/api/v1/res/items/{item_id}" 36 37 return {"id": item_id, "value": value}
只有业务结果确实存在多种成功状态时才动态修改。接口行为越稳定,客户端越容易处理。
这里还要区分实际响应和接口文档。给注入的 Response 设置 status_code 会改变本次请求的实际状态码,但 OpenAPI 无法根据函数中的条件分支自动推断 201,因此还需要使用装饰器的 responses 参数声明这个分支。responses 只补充文档,不会替我们执行状态切换。
status_code
responses
常见的成功状态码可以这样理解:
200 OK
202 Accepted
204 No Content
304 Not Modified
响应模型可以控制默认字段是否输出。例如数据记录中有许多可选字段时,可以只返回实际赋值的内容:
下面的响应只包含服务端实际设置的 name,默认字段不会出现在 data 中:
data
01from fastapi import APIRouter 02from pydantic import BaseModel 03 04router = APIRouter() 05 06 07class UserProfile(BaseModel): 08 name: str 09 bio: str | None = None 10 theme: str = "system" 11 12 13@router.get( 14 "/profiles/{user_id}", 15 response_model=UserProfile, 16 response_model_exclude_unset=True, 17) 18async def get_profile(user_id: str) -> dict[str, str]: 19 return {"name": "小微"}
响应只包含 name,因为 bio 和 theme 没有被实际设置。这里判断的是字段是否被显式赋值:即使客户端明确传入 bio=None 或 theme="system",值刚好与默认值相同,response_model_exclude_unset=True 仍会保留这些字段。
bio
theme
bio=None
theme="system"
response_model_exclude_unset=True
FastAPI 还提供两个容易混淆的选项:
response_model_exclude_unset
response_model_exclude_defaults
response_model_exclude_none
None
此外,response_model_include 和 response_model_exclude 可以临时选择部分字段,但 OpenAPI 仍然会引用完整模型的 Schema,文档和实际响应容易产生理解偏差。公开接口长期需要不同字段时,优先创建独立的响应模型。
response_model_include
response_model_exclude
这些选项适合稀疏数据,但也可能让同一接口的字段忽隐忽现。稳定公开契约通常更容易使用,不要只为了减少几个字节就默认开启。
FastAPI 可以注入 Response,在保留普通返回值和响应模型能力的同时设置响应头:
下面的案例会请求健康状态,并把浏览器能够读取的响应头一起显示出来:
1from fastapi import APIRouter, Response 2 3router = APIRouter() 4 5 6@router.get("/response-health") 7async def health(response: Response) -> dict[str, str]: 8 response.headers["X-Service-Version"] = "0.1.0" 9 return {"status": "ok"}
分页链接、缓存策略、限流信息和 Request ID 都可能放在响应头中。浏览器跨域读取自定义响应头时,还要在 CORS 配置中通过 expose_headers 明确暴露。
expose_headers
响应对象也可以设置 Cookie:
下面的请求允许浏览器接收凭证,用于观察设置 Cookie 的接口行为:
01from fastapi import APIRouter, Response 02 03router = APIRouter() 04 05 06@router.post("/sessions") 07async def create_session(response: Response) -> dict[str, bool]: 08 response.set_cookie( 09 key="session_id", 10 value="signed-session-value", 11 httponly=True, 12 secure=True, 13 samesite="lax", 14 max_age=3600, 15 ) 16 return {"created": True}
httponly 可以阻止前端 JavaScript 读取 Cookie,secure 表示只通过 HTTPS 发送,samesite 控制跨站请求携带规则。真正的会话值还需要安全随机、签名或服务端存储,不能直接相信客户端传回的任意文本。
httponly
secure
samesite
不是所有响应都是 JSON。FastAPI 提供多种 Response 类:
下面两个案例分别请求纯文本和重定向响应。重定向请求会记录原始地址和浏览器自动跟随后到达的最终地址:
01from fastapi import APIRouter 02from fastapi.responses import PlainTextResponse, RedirectResponse 03 04router = APIRouter() 05 06 07@router.get("/robots.txt", response_class=PlainTextResponse) 08async def robots() -> str: 09 return "User-agent: *\nDisallow: /" 10 11 12@router.get("/documentation") 13async def documentation() -> RedirectResponse: 14 return RedirectResponse(url="/docs")
RedirectResponse 默认使用 307,它会要求客户端在跳转后保留原请求方法。如果业务需要永久跳转或希望改变请求方法,应根据协议显式选择 301、302、303、307 或 308,而不是默认把所有重定向都理解成 302。
RedirectResponse
常见类型包括:
PlainTextResponse
HTMLResponse
FileResponse
StreamingResponse
直接返回一个 Response 对象时,开发者接管了状态码、内容和媒体类型。FastAPI 不会再按照普通 Pydantic 响应模型处理内容,因此要自己保证格式与文档一致。
这里不要把注入的 Response 参数和直接返回的 Response 对象混为一谈。前者是一个临时响应对象,FastAPI 会提取其中的状态码、响应头和 Cookie,再继续处理路径函数返回的数据;后者已经是最终响应,FastAPI 会将它原样发送。
response_class=PlainTextResponse 会告诉 FastAPI 如何构造响应,并把媒体类型写入 OpenAPI;return PlainTextResponse(...) 则直接返回已经构造好的对象。需要动态状态码或完全控制内容时使用后者,固定格式优先使用装饰器参数。
response_class=PlainTextResponse
return PlainTextResponse(...)
如果先用 response_model 约束数据,又直接返回 JSONResponse,不要期待响应模型继续过滤内容。直接 Response 是一条绕过自动响应处理的通道。
直接构造 JSONResponse 时,内容必须已经能够被 JSON 编码。datetime、UUID、Pydantic 模型等对象需要先转换:
datetime
这个案例用于观察手动构造的 JSON 响应以及时间字段最终得到的字符串形式:
01from datetime import datetime, timezone 02 03from fastapi import APIRouter 04from fastapi.encoders import jsonable_encoder 05from fastapi.responses import JSONResponse 06 07router = APIRouter() 08 09 10@router.get("/build-info") 11async def get_build_info() -> JSONResponse: 12 content = { 13 "version": "0.1.0", 14 "generated_at": datetime.now(timezone.utc), 15 } 16 return JSONResponse(content=jsonable_encoder(content))
如果已经声明了 Pydantic 响应模型,就不需要手动做这一步。只有确实需要自己控制响应对象时,才接管这部分转换工作。
文件下载则可以使用 FileResponse:
下面的案例以 Blob 接收 PDF,只展示响应状态、文件名、媒体类型和文件大小:
01from pathlib import Path 02 03from fastapi import APIRouter 04from fastapi.responses import FileResponse 05 06router = APIRouter() 07report_path = Path(__file__).parent / "files" / "report.pdf" 08 09 10@router.get("/reports/latest", response_class=FileResponse) 11async def download_report() -> FileResponse: 12 return FileResponse( 13 path=report_path, 14 media_type="application/pdf", 15 filename="fastapi-report.pdf", 16 )
media_type 决定 Content-Type,filename 会让 FileResponse 生成用于下载的 Content-Disposition。文件不存在、路径是否允许访问等检查仍应由业务代码负责,不能直接把客户端传入的任意路径交给 FileResponse。
media_type
filename
Content-Disposition
删除资源后可以返回 204:
下面的案例发送 DELETE 请求。成功后可以看到 204 状态码,并确认响应中没有正文:
01from fastapi import APIRouter, Response, status 02 03router = APIRouter() 04 05 06@router.delete( 07 "/conversations/{conversation_id}", 08 status_code=status.HTTP_204_NO_CONTENT, 09) 10async def delete_conversation(conversation_id: str) -> Response: 11 return Response(status_code=status.HTTP_204_NO_CONTENT)
204 表示响应没有正文,不应再返回 {"success": true}。如果客户端确实需要删除结果或新状态,就使用 200 并声明相应模型。
{"success": true}
一个接口可能除了成功响应,还会返回业务错误。可以通过装饰器的 responses 参数把这些分支写入 OpenAPI:
下面两个案例请求同一个接口:第一个得到正常会话,第二个使用不存在的 ID 得到文档中声明的 404 错误响应:
01from fastapi import APIRouter 02from fastapi.responses import JSONResponse 03from pydantic import BaseModel 04 05router = APIRouter() 06 07 08class ConversationRead(BaseModel): 09 id: str 10 title: str 11 12 13class ErrorResponse(BaseModel): 14 code: str 15 message: str 16 17 18conversations = { 19 "conversation-1": {"title": "新会话"}, 20} 21 22 23@router.get( 24 "/documented-conversations/{conversation_id}", 25 response_model=ConversationRead, 26 responses={ 27 404: { 28 "model": ErrorResponse, 29 "description": "会话不存在", 30 }, 31 }, 32) 33async def get_conversation( 34 conversation_id: str, 35) -> dict[str, str] | JSONResponse: 36 conversation = conversations.get(conversation_id) 37 38 if conversation is None: 39 return JSONResponse( 40 status_code=404, 41 content={ 42 "code": "conversation_not_found", 43 "message": "会话不存在", 44 }, 45 ) 46 47 return { 48 "id": conversation_id, 49 "title": conversation["title"], 50 }
responses 主要补充文档,并不会自动把所有异常转换成这个结构。这里仍然需要在失败分支中明确返回 404;实际项目也可以由下一篇介绍的异常处理器统一生成错误响应。
除了 model 和 description,responses 还可以声明不同媒体类型、示例、响应头和 OpenAPI links。它也能为主成功响应补充说明,并与 response_model、status_code 合并生成最终文档。不过这些内容仍然只是契约描述,运行时代码必须返回与契约一致的状态码、媒体类型和数据结构。
model
description
响应模型应该面向调用方,而不是简单映射内部对象:
对于 AI 接口,普通响应可以返回消息 ID、会话 ID、内容、模型标识和结束原因。供应商返回的完整原始对象不应未经筛选直接暴露给网页。
对比 JSON 模型响应、纯文本响应和没有正文的 204,观察状态码、响应头与字段过滤。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
1from fastapi import FastAPI 2 3from responses_demo import router 4 5app = FastAPI(title="FastAPI 响应") 6app.include_router(router) 7
01from datetime import datetime, timezone 02from uuid import UUID, uuid4 03 04from fastapi import APIRouter, Response 05from fastapi.responses import PlainTextResponse 06from pydantic import BaseModel, Field 07 08router = APIRouter() 09 10class UserInput(BaseModel): 11 name: str = Field(min_length=1, max_length=40) 12 13class PublicUser(BaseModel): 14 id: UUID 15 name: str 16 created_at: datetime 17 18@router.post("/users", status_code=201, response_model=PublicUser) 19async def create_user(payload: UserInput, response: Response) -> dict[str, object]: 20 user_id = uuid4() 21 response.headers["Location"] = f"/users/{user_id}" 22 return {"id": user_id, "name": payload.name, 23 "created_at": datetime.now(timezone.utc), "secret": "不公开"} 24 25@router.get("/text", response_class=PlainTextResponse) 26async def text() -> str: 27 return "这是一条纯文本响应" 28 29@router.delete("/draft", status_code=204) 30async def delete_draft() -> Response: 31 return Response(status_code=204) 32
打开在线案例,点击运行,等待环境就绪,再发送默认 POST /users。本篇不需要模型密钥或外部服务。
POST /users
默认请求体:
1{"name":"小微"}
默认状态码为 201,响应只包含 id、name 和 created_at,UUID 与 UTC 日期被序列化成 JSON 字符串。Location 响应头指向本次生成的用户 ID;它只演示资源地址,不意味着本篇已经保存了用户。
GET /text 返回 text/plain;DELETE /draft 返回没有正文的 204。每次请求独立生成 ID 和时间,不写数据库。文章的 FileResponse 与同步文件读取保留为本机示例,在线不启动文件线程池。
GET /text
DELETE /draft
下载项目后,在项目目录执行:
1uv run fastapi dev main.py
再通过 http://127.0.0.1:8000/docs 发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。
http://127.0.0.1:8000/docs
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 响应
路径函数完成后,FastAPI 需要把 Python 结果转换成 HTTP 响应。一个响应不只有 JSON 数据,还包括状态码、响应头和媒体类型:
FastAPI 默认很适合 JSON API。返回字典、列表或 Pydantic 模型时,它会把结果编码成 JSON,并设置合适的
Content-Type。本文的完整可请求案例位于
src/fastapi/api/res/,每个下划线命名的 Python 文件对应一个独立路由模块;它们统一由res/__init__.py聚合。文章中的说明性表格、HTTP 报文和文字解释不对应项目文件。res/__init__.py负责声明响应案例的领域前缀,并聚合各个案例。上层api/router.py将整个响应案例模块挂载到/api/v1:因此,案例文件中的相对路径会统一组合成
/api/v1/res/...。2. 序列化
JSON 只支持有限的数据类型,但 Python 还包含日期、UUID 和模型对象。FastAPI 会根据路径函数有没有声明响应模型,选择不同的序列化方式:
response_model或有效的返回类型jsonable_encoder转换,再交给JSONResponseResponse子类我们先来看没有显式响应模型时最常见的写法:
下面的案例请求一个固定 UUID 对应的会话,并同时展示正文、状态码、响应头和响应 URL:
UUID 和时间会转换成 JSON 字符串。时间字段应明确时区,跨系统传输时通常使用 UTC 和 ISO 8601 格式,不要返回依赖服务器本地时区的模糊时间。
即使没有显式设置
response_model,有效的返回类型也会参与建立响应模型,FastAPI 会通过 Pydantic 完成响应校验与序列化。只有没有有效响应模型的普通返回值,才会交给jsonable_encoder()转换;不能仅根据装饰器中没有response_model就判断转换路径。3. 响应模型
使用
response_model可以声明并校验公开响应:下面的案例可以直接观察公开响应中只有
id和name,服务端返回的password_hash会被响应模型过滤:响应中只会保留
UserRead声明的字段,password_hash不会发送给客户端。这种过滤是重要的安全边界,但不能代替正确的数据分层:业务代码也不应该随意把敏感对象交给响应层。可以直接把返回类型写成 Pydantic 模型:
这个案例请求使用返回类型声明响应模型的接口,它与上一个案例采用不同声明方式,但都会经过响应校验和序列化:
返回类型和
response_model都能参与运行时响应校验、序列化、字段过滤和文档生成。它们不是只给编辑器看的类型提示。两者同时存在时,
response_model优先。一般可以按下面的方式选择:-> UserReadresponse_model=UserReadResponse子类Response或具体子类response_model=None响应数据不符合模型时,通常意味着服务端实现违反了自己的契约。FastAPI 会把它作为服务器错误处理,而不是向客户端返回 422。422 主要表示客户端提交的请求无法通过校验。
4. 输入输出
创建资源时,输入和输出应使用不同模型:
下面的案例会提交会话标题。请求成功后,可以在响应元数据中观察 201 状态码以及浏览器允许读取的响应头:
客户端只提供标题,服务器负责生成 ID 和时间。响应模型把这种所有权写进了接口契约。
201 Created表示服务器创建了新资源,Location响应头进一步告诉客户端可以从哪里访问它。5. 状态码
固定状态码写在路径装饰器中,动态状态码可以通过
Response参数调整:第一次提交新的
item_id时接口返回 201,再次提交同一个 ID 时返回 200。可以修改 ID 和查询参数value观察状态变化:只有业务结果确实存在多种成功状态时才动态修改。接口行为越稳定,客户端越容易处理。
这里还要区分实际响应和接口文档。给注入的
Response设置status_code会改变本次请求的实际状态码,但 OpenAPI 无法根据函数中的条件分支自动推断 201,因此还需要使用装饰器的responses参数声明这个分支。responses只补充文档,不会替我们执行状态切换。常见的成功状态码可以这样理解:
200 OK201 CreatedLocation202 Accepted204 No Content304 Not Modified6. 默认字段
响应模型可以控制默认字段是否输出。例如数据记录中有许多可选字段时,可以只返回实际赋值的内容:
下面的响应只包含服务端实际设置的
name,默认字段不会出现在data中:响应只包含
name,因为bio和theme没有被实际设置。这里判断的是字段是否被显式赋值:即使客户端明确传入bio=None或theme="system",值刚好与默认值相同,response_model_exclude_unset=True仍会保留这些字段。FastAPI 还提供两个容易混淆的选项:
response_model_exclude_unsetresponse_model_exclude_defaultsresponse_model_exclude_noneNone的字段此外,
response_model_include和response_model_exclude可以临时选择部分字段,但 OpenAPI 仍然会引用完整模型的 Schema,文档和实际响应容易产生理解偏差。公开接口长期需要不同字段时,优先创建独立的响应模型。这些选项适合稀疏数据,但也可能让同一接口的字段忽隐忽现。稳定公开契约通常更容易使用,不要只为了减少几个字节就默认开启。
7. 响应头
FastAPI 可以注入
Response,在保留普通返回值和响应模型能力的同时设置响应头:下面的案例会请求健康状态,并把浏览器能够读取的响应头一起显示出来:
分页链接、缓存策略、限流信息和 Request ID 都可能放在响应头中。浏览器跨域读取自定义响应头时,还要在 CORS 配置中通过
expose_headers明确暴露。8. Cookie
响应对象也可以设置 Cookie:
下面的请求允许浏览器接收凭证,用于观察设置 Cookie 的接口行为:
httponly可以阻止前端 JavaScript 读取 Cookie,secure表示只通过 HTTPS 发送,samesite控制跨站请求携带规则。真正的会话值还需要安全随机、签名或服务端存储,不能直接相信客户端传回的任意文本。9. 响应类
不是所有响应都是 JSON。FastAPI 提供多种 Response 类:
下面两个案例分别请求纯文本和重定向响应。重定向请求会记录原始地址和浏览器自动跟随后到达的最终地址:
RedirectResponse默认使用 307,它会要求客户端在跳转后保留原请求方法。如果业务需要永久跳转或希望改变请求方法,应根据协议显式选择 301、302、303、307 或 308,而不是默认把所有重定向都理解成 302。常见类型包括:
JSONResponsePlainTextResponseHTMLResponseFileResponseRedirectResponseStreamingResponse直接返回一个 Response 对象时,开发者接管了状态码、内容和媒体类型。FastAPI 不会再按照普通 Pydantic 响应模型处理内容,因此要自己保证格式与文档一致。
这里不要把注入的
Response参数和直接返回的Response对象混为一谈。前者是一个临时响应对象,FastAPI 会提取其中的状态码、响应头和 Cookie,再继续处理路径函数返回的数据;后者已经是最终响应,FastAPI 会将它原样发送。response_class=PlainTextResponse会告诉 FastAPI 如何构造响应,并把媒体类型写入 OpenAPI;return PlainTextResponse(...)则直接返回已经构造好的对象。需要动态状态码或完全控制内容时使用后者,固定格式优先使用装饰器参数。如果先用
response_model约束数据,又直接返回JSONResponse,不要期待响应模型继续过滤内容。直接 Response 是一条绕过自动响应处理的通道。直接构造
JSONResponse时,内容必须已经能够被 JSON 编码。datetime、UUID、Pydantic 模型等对象需要先转换:这个案例用于观察手动构造的 JSON 响应以及时间字段最终得到的字符串形式:
如果已经声明了 Pydantic 响应模型,就不需要手动做这一步。只有确实需要自己控制响应对象时,才接管这部分转换工作。
文件下载则可以使用
FileResponse:下面的案例以 Blob 接收 PDF,只展示响应状态、文件名、媒体类型和文件大小:
media_type决定Content-Type,filename会让FileResponse生成用于下载的Content-Disposition。文件不存在、路径是否允许访问等检查仍应由业务代码负责,不能直接把客户端传入的任意路径交给FileResponse。10. 空响应
删除资源后可以返回 204:
下面的案例发送 DELETE 请求。成功后可以看到 204 状态码,并确认响应中没有正文:
204 表示响应没有正文,不应再返回
{"success": true}。如果客户端确实需要删除结果或新状态,就使用 200 并声明相应模型。11. 其他响应
一个接口可能除了成功响应,还会返回业务错误。可以通过装饰器的
responses参数把这些分支写入 OpenAPI:下面两个案例请求同一个接口:第一个得到正常会话,第二个使用不存在的 ID 得到文档中声明的 404 错误响应:
responses主要补充文档,并不会自动把所有异常转换成这个结构。这里仍然需要在失败分支中明确返回 404;实际项目也可以由下一篇介绍的异常处理器统一生成错误响应。除了
model和description,responses还可以声明不同媒体类型、示例、响应头和 OpenAPI links。它也能为主成功响应补充说明,并与response_model、status_code合并生成最终文档。不过这些内容仍然只是契约描述,运行时代码必须返回与契约一致的状态码、媒体类型和数据结构。12. 契约
响应模型应该面向调用方,而不是简单映射内部对象:
对于 AI 接口,普通响应可以返回消息 ID、会话 ID、内容、模型标识和结束原因。供应商返回的完整原始对象不应未经筛选直接暴露给网页。
13. 在线实验
对比 JSON 模型响应、纯文本响应和没有正文的 204,观察状态码、响应头与字段过滤。
下面的代码直接读取工作区的原始文件,文章与下载项目使用同一份来源:
打开在线案例,点击运行,等待环境就绪,再发送默认
POST /users。本篇不需要模型密钥或外部服务。默认请求体:
默认状态码为 201,响应只包含 id、name 和 created_at,UUID 与 UTC 日期被序列化成 JSON 字符串。Location 响应头指向本次生成的用户 ID;它只演示资源地址,不意味着本篇已经保存了用户。
GET /text返回 text/plain;DELETE /draft返回没有正文的 204。每次请求独立生成 ID 和时间,不写数据库。文章的 FileResponse 与同步文件读取保留为本机示例,在线不启动文件线程池。下载项目后,在项目目录执行:
再通过
http://127.0.0.1:8000/docs发送同一请求。本机示例使用 Python 3.12,浏览器由共享 Pyodide 环境执行;本篇代码只使用两者都有的能力。