04.7.15.1 路由依赖注入与请求生命周期
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架
覆盖范围
APIRouter与include_router的prefix/tags/dependencies/responsesDepends依赖解析、use_cache缓存、yield依赖的执行与清理时机Annotated写法演进、类依赖、Security、子依赖链与全局app.dependenciesPath/Query/Header/Cookie/Body/Form/File参数绑定与校验- 请求生命周期:ASGI → Starlette → 依赖解析 → 端点 → 响应序列化 →
BackgroundTasks Request/Response注入、app.state、路由匹配顺序、redirect_slashes、root_path、Mount/StaticFiles
04.7.15.1-001 APIRouter 与直接在 app 上定义路由有什么区别?
一句话结论
APIRouter 是可复用的路由容器,行为上与直接挂在 FastAPI 实例上的路由一致:两者最终都生成 APIRoute 加入路由表。区别在于组织方式:APIRouter 支持独立的 prefix、tags、dependencies、responses,可以按模块拆分后由 include_router 汇总,便于大型项目分层与复用。
概念解释
FastAPI本身继承自 Starlette 的Router,@app.get与@router.get最终调用同一套路由注册逻辑。- 路由器是“未挂载的路由集合”,挂载前不参与匹配;挂载后其路由才进入应用路由表。
原理流程
- 用
APIRouter()创建路由器,在其上用装饰器声明端点。 - 在主应用中
app.include_router(router)把路由并入应用。 - 注册时路由器上的
prefix、tags、依赖被合并到每条APIRoute上。
代码或图示
from fastapi import APIRouter, FastAPI
router = APIRouter(prefix="/items", tags=["items"])
@router.get("/{item_id}")
def get_item(item_id: int):
return {"id": item_id}
app = FastAPI()
app.include_router(router)
常见误区
- 以为路由器有独立的中间件栈:
APIRouter不注册中间件,中间件只能挂在app上;路由器只携带路由级依赖与元数据。 - 以为不
include_router路由也能访问:未挂载的路由器不进入路由表,请求会 404。
追问
- 路由器能单独挂静态文件吗?答:静态资源用
app.mount或router上挂Mount,APIRouter本身不替代Mount。 - 多个路由器可以挂同一前缀吗?答:可以,路由按各自注册顺序进入全局路由表,注意路径冲突。
- 路由器上的
dependencies作用于哪些路由?答:作用于该路由器下挂载的全部端点。
04.7.15.1-002 include_router 的 prefix 如何与路由自身路径拼接?
一句话结论
最终路径 = include_router(prefix=...) 的前缀 + 路由器内装饰器声明的路径;拼接时框架会规整斜杠,避免出现双斜杠或丢斜杠。路由自身路径以 / 开头,前缀通常也以 / 开头,二者按字符串拼接后归一化。
概念解释
prefix是挂载级路径前缀,只影响 URL 路径,不影响参数名与 OpenAPI 分组之外的行为。- 路由器内部还可以再
include_router,前缀逐级叠加(见 006)。
原理流程
- 挂载时读取
include_router的prefix,默认空字符串。 - 遍历路由器内每条路由,把前缀拼到路由
path前。 - 对拼接结果做斜杠规整,生成最终
APIRoute.path。
代码或图示
router = APIRouter()
@router.get("/detail") # 装饰器路径
def detail():
...
app.include_router(router, prefix="/v1/items")
# 最终路径:/v1/items/detail
常见误区
- 把前缀写成相对路径(
v1/items不带前导/):多数情况下能工作,但拼接结果依赖规整逻辑,跨版本易出问题,规范写法是前缀与路由路径都以/开头。 - 以为
prefix会改变请求体模型或参数校验:前缀只参与 URL 匹配,与入参绑定无关。
追问
- 前缀末尾带斜杠会怎样?答:框架规整斜杠,不会产生双斜杠,但建议前缀不带尾斜杠。
- 同一路由器能否以不同前缀挂两次?答:可以,两次挂载生成两套路由,各自带前缀。
- 前缀里能放路径参数吗?答:可以,路径参数会进入该路由器端点的参数解析链。
04.7.15.1-003 tags 在路由器与路由级别如何叠加并影响 OpenAPI 分组?
一句话结论
tags 是字符串列表:路由器级 tags 与路由级 tags 在挂载时合并(去重),OpenAPI 文档按合并后的 tags 把端点分组展示。路由级 tags 追加在路由器 tags 之后,不会覆盖父级 tags。
概念解释
- tags 只影响文档分组与展示,不参与路由匹配,也不改变鉴权或响应行为。
- 一个端点可以挂多个 tag,在 Swagger UI 中会出现在多个分组下。
原理流程
- 路由器创建时记录
tags,装饰器上再记录路由级tags。 include_router合并两层 tags 到每条APIRoute.tags。- 生成 OpenAPI 时按 tags 聚合
paths下的操作。
代码或图示
router = APIRouter(tags=["items"])
@router.get("/", tags=["read"]) # 合并后:["items", "read"]
def list_items():
...
app.include_router(router, tags=["v1"]) # 再合并:["v1", "items", "read"]
常见误区
- 以为路由级 tags 会替换路由器 tags:实际是合并追加,父级 tags 仍然保留。
- 用 tags 做权限隔离:tags 仅是文档元数据,鉴权必须靠依赖或中间件。
追问
- tags 顺序影响文档展示吗?答:影响分组内端点排列顺序,建议按模块固定顺序。
- 不传 tags 会归到哪一组?答:归入默认空分组(Swagger UI 顶部未命名区域)。
- tags 支持对象形式吗?答:0.11x 支持
Tag对象携带 description 给分组加说明,纯字符串仍是最常见写法。
04.7.15.1-004 include_router 的 dependencies 与路由级 dependencies 有何区别?
一句话结论
两者都是 Depends 列表,区别只在作用域:include_router(dependencies=[...]) 作用于该路由器下全部端点;路由装饰器上的 dependencies=[...] 只作用于单个端点。执行时父级依赖先解析,再解析子级与端点参数依赖。
概念解释
- 路由级依赖不向端点注入返回值,只利用其副作用(鉴权、日志、限流);需要注入值时仍在端点参数上声明
Depends。 - 依赖列表中的每个依赖独立解析,默认各自缓存(见 017)。
原理流程
- 挂载时把
include_router的dependencies附加到路由器所有路由。 - 路由注册时把装饰器
dependencies合并到该条路由。 - 请求到达后按“全局 → 路由器 → 路由 → 端点参数”的顺序解析依赖树。
代码或图示
async def verify_token(x_token: str = Header()):
if not x_token:
raise HTTPException(status_code=401)
router = APIRouter(dependencies=[Depends(verify_token)])
@router.get("/me", dependencies=[Depends(check_perm)])
def me():
...
app.include_router(router)
常见误区
- 以为
dependencies=[Depends(x)]里的返回值能在端点里用:不能,列表依赖只执行副作用;要取值必须在函数参数上声明。 - 把业务校验写进路由级依赖后又在端点重复校验:依赖已短路失败,端点内无需重复判断。
追问
- 路由器依赖能被子路由覆盖吗?答:不能覆盖,只能追加;父级依赖始终执行。
- 依赖抛
HTTPException后还会执行后续依赖吗?答:不会,异常沿依赖链上抛,未解析的依赖不再执行。 - 全局依赖与路由器依赖谁先执行?答:全局
app.dependencies先,路由器依赖后。
04.7.15.1-005 responses 参数如何在 OpenAPI 中声明额外响应?
一句话结论
responses 是 {状态码: {模型/描述/headers}} 的映射,用于在 OpenAPI 中补充端点除成功响应外的状态码与 Schema,例如 401、404、422。它只影响文档与响应模型声明,不拦截或改写真实响应。
概念解释
- 成功响应模型由
response_model给出;responses用于声明失败或其他分支响应,便于前端与文档对齐。 - 值可以是
dict描述,也可以直接传 Pydantic 模型。
原理流程
- 在路由装饰器或
include_router上声明responses={404: {"model": NotFound, "description": "未找到"}}。 - 生成 OpenAPI 时把这些条目合并进该操作的
responses。 - 运行时框架不据此做响应校验,真实响应仍由端点返回值决定。
代码或图示
from fastapi import FastAPI
from pydantic import BaseModel
class NotFound(BaseModel):
detail: str
app = FastAPI()
@app.get(
"/items/{item_id}",
responses={404: {"model": NotFound, "description": "商品不存在"}},
)
def read_item(item_id: int):
...
常见误区
- 以为
responses会自动把错误响应序列化:不会,它只是文档声明;错误响应仍需端点或异常处理器生成。 - 在
responses里重复声明 200 会覆盖response_model:声明同状态码时会合并/覆盖对应条目,成功模型建议统一由response_model给出。
追问
responses能声明响应头吗?答:可以,条目内用headers描述头字段及类型。- 路由器级
responses会继承到子路由吗?答:会合并到该路由器下各端点的文档声明。 - 422 需要手动声明吗?答:不需要,FastAPI 自动按请求体模型生成 422 的 Schema。
04.7.15.1-006 子路由器嵌套 include_router 时 prefix 如何逐级叠加?
一句话结论
路由器可以再 include_router,最终路径按“外层挂载前缀 + 内层路由器前缀 + 路由装饰器路径”逐级拼接。嵌套层级不影响依赖解析顺序,依赖仍按外层到内层的层级解析。
概念解释
- 嵌套适合按领域分层:顶层按版本挂,中层按资源挂,底层按操作挂。
- 每层都可以独立带 tags、dependencies、responses,逐层合并。
原理流程
- 内层路由器先注册自己的路由与子路由器。
- 外层
include_router(inner, prefix="/v1")把前缀拼到内层所有路径前。 - 主应用再挂载外层路由器,前缀再次叠加。
代码或图示
items = APIRouter(prefix="/items")
admin = APIRouter(prefix="/admin")
@items.get("/{id}")
def detail(id: int):
...
admin.include_router(items, prefix="/v1")
app.include_router(admin)
# 最终路径:/admin/v1/items/{id}
常见误区
- 嵌套层级过深导致前缀难以推算:建议每层前缀在注释或模块名中写清,避免线上路径与文档不一致。
- 以为内层路由器的依赖会绕过外层:不会,外层依赖始终先解析,内层无法跳过。
追问
- 嵌套路由器的 tags 如何合并?答:从外到内逐层追加合并,去重后挂到每条路由。
- 子路由器能访问父路由器的参数吗?答:路径参数沿 URL 匹配链传递,函数参数按声明解析。
- 嵌套会影响 OpenAPI 操作顺序吗?答:按路由注册顺序输出,嵌套深度不改变排序规则。
04.7.15.1-007 路由匹配按注册顺序还是路径优先级?
一句话结论
FastAPI/Starlette 按路由在路由表中的注册顺序逐条匹配,先注册先匹配,不是按路径长度或静态段优先级排序。因此静态路径必须注册在带路径参数的通配路由之前,否则会被后者抢先匹配。
概念解释
- 每条
APIRoute编译为正则/路径模式,匹配时按列表顺序遍历,命中即返回。 - 路径参数(
{id})与转换器({id:int})只约束该段格式,不改变“先注册先匹配”的总规则。
原理流程
- 应用启动时把所有
APIRoute按注册顺序存入app.routes。 - 请求到达后遍历路由表,逐条用路径模式与方法匹配。
- 第一条同时匹配路径与 HTTP 方法的路由被选中;都不匹配则 405/404。
代码或图示
# 错误:通配路由先注册,/me 会被 {username} 吃掉
@app.get("/{username}")
def profile(username: str): ...
@app.get("/me")
def me(): ... # 永远命中不到
# 正确:静态路径先注册
@app.get("/me")
def me(): ...
@app.get("/{username}")
def profile(username: str): ...
常见误区
- 以为框架会把静态段排到参数段前面:Starlette 不做这种重排,顺序完全由注册决定。
- 多个
include_router之间不注意先后:后挂的路由器若路径更宽,可能先于先挂的具体路由匹配。
追问
- 方法不匹配时会怎样?答:路径匹配但方法不匹配,继续找下一条;全部路径匹配但方法都不对则返回 405。
- 如何排查被通配路由抢占?答:打印
app.routes顺序,或在 Swagger/OpenAPI 中核对实际路径。 - 路径转换器能避免抢占吗?答:
{id:int}只接受整数段,字符串/me不会命中,但同类型参数仍受注册顺序约束。
04.7.15.1-008 redirect_slashes 的行为与 307 重定向条件?
一句话结论
redirect_slashes=True(默认)时,若请求路径与某路由仅差末尾斜杠,框架会把请求 307 临时重定向到带/不带斜杠的规范路径。307 保留原方法与请求体,POST 不会被改成 GET。关闭后斜杠不一致直接 404。
概念解释
- 重定向由 Starlette 的
Router在匹配失败后做一次“去尾斜杠/加尾斜杠”重试。 - 307 区别于 301/302:307 强制客户端保留请求方法与 body,避免 POST 表单被转成 GET。
原理流程
- 按原始路径遍历路由表,未命中。
- 若开启
redirect_slashes,尝试去掉/补上末尾斜杠再匹配一次。 - 二次命中则返回 307,
Location指向规范路径;仍未命中则 404。
代码或图示
app = FastAPI(redirect_slashes=True)
@app.get("/items/")
def list_items():
...
# 请求 GET /items → 307 → /items/
常见误区
- 以为 307 会像 302 一样把 POST 变 GET:307 保留方法与 body,POST 重定向后仍是 POST。
- 依赖浏览器自动跟随重定向而忽略 API 客户端:部分 HTTP 客户端默认不跟随 307 的 body 重定向,API 设计应保持路径规范一致。
追问
- 在哪里关闭斜杠重定向?答:
FastAPI(redirect_slashes=False),对整个应用生效。 - 重定向会保留查询串吗?答:
Location一般携带原查询参数,具体由 Starlette 实现。 - 斜杠不一致会影响 WebSocket 吗?答:WebSocket 路由同样走路由表,斜杠规则一致,但不做 307 重定向。
04.7.15.1-009 root_path 在反向代理或网关下起什么作用?
一句话结论
root_path 是应用挂载在代理子路径下时的“前缀基线”:代理把 /api/v1/items 转发到应用时剥掉 /api,应用内部路由按 /v1/items 匹配,但生成文档 URL、root_path 相关链接时需要知道外层前缀,避免 Swagger 与实际访问路径错位。
概念解释
root_path不参与路由匹配,只影响 OpenAPI/文档与某些 URL 生成的前缀计算。- 常见于 Nginx 子路径反代、K8s Ingress 子路径、网关统一前缀部署。
原理流程
- 代理按规则剥离外层前缀后把请求转给应用,
scope["root_path"]由服务器或配置注入。 - 应用路由按
scope["path"](剥离后的路径)匹配。 - 生成 OpenAPI 与文档链接时把
root_path拼回,保证浏览器访问的是完整外层路径。
代码或图示
app = FastAPI(root_path="/api")
# uvicorn 也可通过 --root-path 传入
# uvicorn main:app --root-path /api
常见误区
- 把
root_path当成路由前缀重复拼:路由里再写/api会导致匹配路径多出一层,404。 - 只在代码里设
root_path而代理没剥离前缀:此时外部路径与内部路径不一致,文档链接仍会错位,需两侧配置对齐。
追问
root_path与prefix的区别?答:prefix参与路由匹配;root_path只做外层基线,不参与匹配。- 多个服务挂同一网关不同前缀怎么办?答:每个服务按自身外层路径配置
root_path。 - 文档打不开是
root_path问题吗?答:常见表现是 Swagger 加载 404,先核对代理剥离规则与root_path是否一致。
04.7.15.1-010 Mount 与 APIRouter 挂载 StaticFiles 有何区别?
一句话结论
Mount 是 Starlette 级别的子应用挂载,按前缀把整段路径交给子应用(如 StaticFiles)处理,不经过 FastAPI 依赖注入与参数绑定;APIRouter 是 FastAPI 路由集合,走依赖解析、Pydantic 校验与响应模型。挂静态文件用 app.mount("/static", StaticFiles(...))。
概念解释
Mount接收的是另一个 ASGI 应用,匹配前缀后把剩余路径交给它。- 静态文件服务不需要鉴权注入与模型校验,走
Mount更直接、性能更好。
原理流程
- 路由表中
Mount条目按前缀匹配,命中后剥离前缀,把scope交给子应用。 StaticFiles在文件系统内定位文件并流式返回。- 未命中文件由
StaticFiles返回 404,不回退到 FastAPI 端点。
代码或图示
from fastapi.staticfiles import StaticFiles
app.mount("/static", StaticFiles(directory="static"), name="static")
常见误区
- 用
@app.get("/static/{path:path}")手写文件服务再套依赖:重复造轮子,且容易漏 MIME 类型与安全校验。 - 把
StaticFiles挂进APIRouter期望走鉴权依赖:Mount子应用不经过 FastAPI 依赖链,需要鉴权应在代理层或外层中间件处理。
追问
Mount能挂 FastAPI 子应用吗?答:可以,挂另一个FastAPI实例作为子应用,但其依赖与中间件独立。Mount的name有什么用?答:用于url_path_for反查挂载点 URL。- 静态目录不存在会怎样?答:
StaticFiles默认在启动时检查目录,不存在直接抛错。
04.7.15.1-011 StaticFiles 的 directory、html、check_dir 行为?
一句话结论
directory 指定静态文件根目录;html=True 时访问目录自动返回 index.html;check_dir=True(默认)在启动时校验目录存在,不存在则抛异常。关闭 check_dir 可在目录稍后创建的场景下延迟检查。
概念解释
html模式下目录请求先找index.html,找不到再按目录列表策略处理(Starlette 默认不自动列目录)。- 路径穿越由
StaticFiles内部规范化拦截,正常用法下不能通过..访问根目录外文件。
原理流程
- 挂载时记录
directory、html、check_dir。 - 请求路径规范化后拼接进
directory,判定是否落在根目录内。 - 文件存在则按扩展名返回 MIME;目录且
html=True则找index.html;否则 404。
代码或图示
app.mount(
"/assets",
StaticFiles(directory="dist", html=True, check_dir=True),
name="assets",
)
常见误区
html=True被当成“SPA history 路由回退”:它只回退到目录的index.html,前端路由刷新 404 需要另配 catch-all 路由或代理。- 把敏感目录(配置、源码)挂为静态目录:只暴露资源目录,遵循最小暴露原则。
追问
- 如何禁止目录列表?答:Starlette
StaticFiles默认不输出目录列表,无需额外关闭。 - 自定义 404 页面可行吗?答:可在
StaticFiles外层包中间件或挂 catch-all 端点处理。 - 大文件如何流式返回?答:
StaticFiles内部按文件分块流式发送,无需端点手动读全文件。
04.7.15.1-012 路径参数转换器 int/path 如何约束匹配?
一句话结论
路径参数可带转换器:{id:int} 只匹配整数段,{path:path} 匹配剩余任意路径段(含斜杠);不带转换器的参数按普通字符串段匹配。转换器既约束 URL 匹配,也参与参数类型解析。
概念解释
- 常用转换器:
int、str、path;uuid等类型通过参数类型注解在解析阶段校验。 :path是“贪婪剩余段”,必须放在路径末尾,否则会吞掉后续字面段。
原理流程
- 路由注册时把路径模板编译为匹配规则,转换器对应段模式。
- 请求路径按段匹配,
int段要求全数字,path段吸收剩余斜杠。 - 匹配成功后把段值交给参数绑定层,按类型注解转换校验。
代码或图示
@app.get("/files/{file_path:path}")
def read_file(file_path: str):
...
@app.get("/items/{item_id:int}")
def read_item(item_id: int):
...
常见误区
- 把
:path放在中间:贪婪匹配会吞掉后面的字面路径,导致尾部段永远匹配不到。 - 以为
{id:int}匹配后参数仍是字符串:匹配只做格式约束,最终类型由参数注解int转换。
追问
- 段为空能匹配吗?答:普通段不匹配空串;
path段在路径止于前缀时按空处理,具体以 Starlette 行为为准。 - 转换器能自定义吗?答:Starlette 支持注册自定义路径转换器,FastAPI 端点内再配合类型注解校验。
- 路径参数能声明默认值吗?答:路径段必须出现在 URL 中,不能像 Query 那样给可选默认值。
04.7.15.1-013 路由 name 与 url_path_for 如何生成 URL?
一句话结论
每条路由可在装饰器上传 name,应用通过 app.url_path_for(name, **params) 反查并生成路径,用于在邮件、重定向、文档中构造内部链接,避免硬编码路径字符串。
概念解释
url_path_for是 Starlette 提供的路由反查方法,返回包含路径参数填充后的 URL 路径(不含域名)。- 路由 name 在同一应用内应唯一,否则反查命中不确定。
原理流程
- 注册路由时记录
route.name(默认取端点函数名)。 - 调用
url_path_for按 name 找到路由模板。 - 用传入的关键字参数填充模板中的路径段,返回生成的路径。
代码或图示
@app.get("/items/{item_id}", name="item-detail")
def detail(item_id: int):
...
url = app.url_path_for("item-detail", item_id=42)
# url == "/items/42"
常见误区
- 跨应用反查 name:
url_path_for只在当前应用路由表内查找,挂载子应用的路由需要对应子应用实例或按其 name 空间处理。 - 漏传路径参数导致报错:模板中的每个段都必须在关键字参数中给出。
追问
- 不指定 name 时默认是什么?答:默认使用端点函数的
__name__。 - 生成的 URL 包含查询串吗?答:
url_path_for只填路径段,查询参数需自行拼接。 - Mount 的 name 也能反查吗?答:可以,Mount 同样有 name,反查得到挂载前缀。
04.7.15.1-014 全局 app.dependencies 与路由器依赖的执行层级?
一句话结论
依赖解析层级从外到内为:app.dependencies(全局)→ include_router/路由器 dependencies → 路由装饰器 dependencies → 端点函数参数上的 Depends。外层先解析,失败即短路;同层按列表顺序解析。
概念解释
- 全局依赖适合跨所有端点的横切逻辑:请求 ID、审计日志、全局鉴权。
- 路由器/路由级依赖做模块内分组鉴权;参数依赖负责向端点注入具体对象。
原理流程
- 请求匹配到路由后,收集该路由继承到的全部依赖(全局、路由器、路由、参数)。
- 按层级与顺序构建依赖树,从外层开始递归解析。
- 某层抛异常则中断解析,异常向上交给异常处理器。
代码或图示
app = FastAPI(dependencies=[Depends(request_id)])
router = APIRouter(dependencies=[Depends(auth)])
@router.get("/x", dependencies=[Depends(perm)])
def x(obj: DBC = Depends(get_db)):
...
常见误区
- 全局依赖里做了需要请求体的校验:请求体在端点参数解析阶段才读取,全局依赖拿不到已解析的模型,需要在依赖内直接读
Request。 - 把重依赖挂到全局导致每个请求都付出成本:全局依赖影响面最大,应保持轻量。
追问
- 全局依赖会出现在每个端点的 OpenAPI 里吗?答:会按依赖声明的参数生成安全方案/参数条目,注意敏感头暴露。
- 能在测试中覆盖全局依赖吗?答:可用
app.dependency_overrides替换指定依赖函数。 - 依赖解析顺序对缓存有影响吗?答:同请求内相同依赖按
use_cache共享,解析顺序决定首次解析时机。
04.7.15.1-015 同一前缀下多个路由的路径冲突如何解析?
一句话结论
同一前缀下若多条路由模板都能匹配当前路径,按注册顺序取第一条命中的;静态段与参数段混用、path 贪婪段是最常见冲突来源。排查方式是打印 app.routes,核对每条路由的 path、methods 与注册先后。
概念解释
- 冲突不是框架去“择优”,而是顺序遍历命中即返回,因此设计阶段就要约定“静态优先、参数靠后、贪婪段收尾”。
- 方法不同但路径相同不算冲突:路径匹配后再按 HTTP 方法区分。
原理流程
- 启动时各路由器按
include_router顺序把路由追加进app.routes。 - 请求遍历表,路径模式与方法同时匹配才选中。
- 发现某端点 404 或行为不对时,对照路由表确认是否被更靠前的宽路由抢占。
代码或图示
# 排查:输出全部路由
for route in app.routes:
print(getattr(route, "path", route.prefix), getattr(route, "methods", ""))
常见误区
- 认为后注册的具体路由会“覆盖”先注册的通配路由:不会覆盖,先命中先生效。
- 多版本共用前缀时不隔离:
/v1/items与/v2/items分属不同路由器,注册顺序混乱时容易互相抢占。
追问
- 路径相同方法不同如何处理?答:遍历到路径匹配但方法不符的路由会继续找下一条,全不符返回 405。
- 如何调整已有路由顺序?答:调整
include_router的调用先后,或在注册前整理app.routes。 - OpenAPI 里路径重复是问题吗?答:重复路径会在文档中并列展示,需核对是否为误挂载。
04.7.15.1-016 Depends 的解析过程:框架如何抽取依赖签名?
一句话结论
FastAPI 在路由注册阶段用 inspect 读取依赖可调用对象的签名,把每个参数按 Path/Query/Header/Body/Depends 等声明归类,构建成依赖树;请求时递归执行叶子依赖,把返回值按参数名注入。Depends 既可以包裹函数,也可以包裹类或可调用实例。
概念解释
- 解析发生在两个时点:注册期做签名分析与 Schema 生成,请求期做实际调用与注入。
- 依赖本身的参数也会被同样分析,因此天然形成可递归的依赖树。
原理流程
- 注册路由时,FastAPI 调用
get_typed_signature提取端点与依赖的参数注解与默认值。 - 对每个参数判断类型:
Depends/Security继续展开为子依赖,其余按参数来源(Path/Query/Body 等)绑定。 - 请求到达后按依赖树深度优先解析,叶子先执行,结果注入上层参数。
代码或图示
from fastapi import Depends
def get_user_id(token: str = Header()) -> int:
return decode(token)
def get_profile(user_id: int = Depends(get_user_id)):
return repo.find(user_id)
@app.get("/me")
def me(profile: dict = Depends(get_profile)):
return profile
常见误区
- 以为依赖解析在每次请求时才“读签名”:签名分析在启动/注册阶段完成,请求期只按已构建的依赖树执行。
- 依赖函数参数没有类型注解导致绑定失败:缺少注解时框架无法判定参数来源,会归入隐式 Body 或报错。
追问
- 依赖树在哪个模块构建?答:
fastapi.dependencies.utils中的请求体/依赖解析工具函数按签名组装。 - 函数签名变化需要重启吗?答:注册期已缓存签名,代码改动后需重启进程才生效。
- 依赖能是生成器函数吗?答:能,带
yield的生成器依赖走资源管理流程(见 021)。
04.7.15.1-017 use_cache 缓存的键与同请求内共享实例边界?
一句话结论
Depends(callable, use_cache=True) 是默认行为:同一次请求内,同一个依赖可调用对象被多次引用时只执行一次,结果在该请求的依赖缓存中共享。缓存键基于依赖可调用对象与请求上下文,请求结束即销毁,不跨请求。
概念解释
- 缓存解决“同一个会话/同一个当前用户被多个上层依赖重复构造”的问题。
- 缓存粒度是“同一依赖 callable 在同一请求内”,不同 callable 之间不共享。
原理流程
- 请求开始时创建本次请求的依赖结果缓存(dict)。
- 解析到某依赖时先查缓存:命中直接取,未命中执行并写入缓存。
- 请求结束缓存随上下文销毁,下一个请求重新解析。
代码或图示
def get_db():
db = SessionLocal()
yield db
db.close()
# 两个参数都引用 get_db,同请求内拿到同一个 Session
@app.get("/items")
def items(a: Session = Depends(get_db), b: Session = Depends(get_db)):
return a is b # True
常见误区
- 以为缓存是全局单例:缓存只在单次请求内有效,跨请求必须用
app.state或外部池。 - 把有状态对象放进被缓存依赖后又期望每次新实例:默认缓存会复用,需要新实例应显式
use_cache=False。
追问
- 缓存键包含参数值吗?答:默认按依赖 callable 标识缓存;同一 callable 不同入参场景由子依赖各自解析,缓存粒度以框架实现为准(待确认:验证点:带参数依赖的缓存键是否含参数哈希)。
- 异步依赖结果会被缓存吗?答:会,
await完成后的返回值同样写入请求缓存。 - 缓存命中时还会进入
yield清理吗?答:yield依赖在请求结束时统一清理一次,不会因多次引用重复清理。
04.7.15.1-018 use_cache=False 的适用场景与重建代价?
一句话结论
use_cache=False 关闭请求内缓存,每次引用该依赖都重新执行并生成新实例。适用于依赖必须每次独立、不能共享可变状态的场景;代价是重复解析与资源获取开销,高频端点需评估。
概念解释
- 与默认缓存相反:关闭后同一请求内两个参数引用同一依赖,得到两个独立实例。
- 常见于需要独立事务、独立临时资源或每次读取最新值的依赖。
原理流程
- 解析依赖时跳过缓存查询,直接执行 callable。
- 每次引用都生成新结果,不写入共享缓存。
- 带
yield的依赖每次实例各自在请求结束时清理。
代码或图示
def fresh_session():
s = SessionLocal()
yield s
s.close()
@app.get("/compare")
def compare(
left: Session = Depends(fresh_session, use_cache=False),
right: Session = Depends(fresh_session, use_cache=False),
):
return left is right # False
常见误区
- 为“避免共享可变状态”而对所有依赖关闭缓存:多数依赖是只读或无状态的,关闭缓存徒增开销。
- 忽略关闭缓存后连接/会话数量翻倍:每个引用都开一个 Session,连接池压力随之上升。
追问
use_cache=False能跨请求隔离吗?答:默认缓存本来就不跨请求,关闭缓存只影响请求内多次引用。- 关闭缓存后
yield清理执行几次?答:每次实例对应一次清理,N 次引用清理 N 次。 - 何时必须关闭缓存?答:依赖返回带独立可变状态、且上层不能共享的对象时。
04.7.15.1-019 类作为依赖时 init 参数如何被解析?
一句话结论
Depends(SomeClass) 把类本身当作可调用对象,框架解析 __init__ 的签名并按参数声明绑定,实例化后把实例注入端点。类依赖适合把一组相关依赖与方法封装成对象,替代多个分散的函数依赖。
概念解释
- 类的
__init__参数同样支持Depends、Header、Query等声明,形成对象内的子依赖。 - 实例方法可在端点内调用,把数据访问逻辑收敛到依赖对象内。
原理流程
- 注册期读取类
__init__签名,归类各参数来源。 - 请求期先解析
__init__所需子依赖,再调用类构造器生成实例。 - 实例作为参数值注入端点,端点调用其方法完成业务。
代码或图示
class CurrentUser:
def __init__(self, token: str = Header()):
self.id = decode(token)
def profile(self):
return repo.find(self.id)
@app.get("/me")
def me(user: CurrentUser = Depends(CurrentUser)):
return user.profile()
常见误区
- 在类依赖里保存请求级可变状态后又依赖缓存复用:默认缓存下同一请求共享实例,跨请求则是新实例,边界要分清。
- 把重初始化逻辑写进
__init__导致每次请求都付出成本:重资源应下沉到外部池或app.state。
追问
- 类依赖能带
yield吗?答:类本身不是生成器;资源清理可在__init__获取、在端点后由方法或单独的生成器依赖完成。 - 类依赖实例会被缓存吗?答:默认
use_cache=True,同请求内复用同一实例。 - 类依赖适合替代服务层吗?答:适合做请求级门面,业务服务仍建议放在独立模块,便于测试与复用。
04.7.15.1-020 子依赖链如何递归解析与逐级缓存?
一句话结论
依赖可以再声明 Depends,框架按深度优先递归解析:先解析子依赖,再用子依赖结果构造上层依赖。每一层独立按 use_cache 缓存,子依赖被多个上层引用时在同请求内共享。
概念解释
- 依赖链是树不是链:一个依赖可被多个父依赖引用,子依赖结果被复用。
- 层级越深,启动期签名分析与请求期解析成本越高,应控制依赖层数。
原理流程
- 端点参数依赖进入解析队列,读取其签名中的子依赖。
- 递归解析子依赖直至叶子(无可再展开的
Depends)。 - 叶子结果回注上层,逐层构造;每层结果写入各自请求缓存。
代码或图示
def get_db():
db = SessionLocal()
yield db
db.close()
def get_repo(db: Session = Depends(get_db)):
return ItemRepo(db)
@app.get("/items")
def items(repo: ItemRepo = Depends(get_repo)):
return repo.list()
常见误区
- 子依赖抛异常后以为上层还能兜底:异常沿依赖树上抛,未执行完的上层依赖不再执行。
- 依赖链过长导致排查困难:建议每层职责单一,链路在代码评审时可追溯。
追问
- 子依赖缓存对父依赖可见吗?答:子依赖在请求缓存中,其他父依赖引用同一子依赖时命中同一实例。
- 循环依赖会怎样?答:解析时形成递归环,框架无法自动打破,需调整设计避免循环引用。
- 依赖链深度影响启动速度吗?答:签名分析在注册期进行,链越深启动期分析量越大。
04.7.15.1-021 yield 依赖的进入与清理时机?
一句话结论
带 yield 的依赖在 yield 前的代码于依赖解析阶段执行,yield 后的清理代码在端点处理完成、响应发送之后执行。即使端点抛异常,清理代码也会执行;yield 依赖适合管理数据库会话、连接、临时文件等请求级资源。
概念解释
- 机制类似上下文管理器:进入时获取资源,退出时释放,由框架在请求生命周期内驱动。
- 清理在响应序列化之后、请求完全结束之前运行,因此不能再向响应写入内容。
原理流程
- 解析到生成器依赖后,框架迭代执行到第一个
yield,把产出值注入上层。 - 端点执行、响应序列化与发送完成。
- 框架恢复生成器执行
yield后代码(清理);异常场景下也保证走到清理段。
代码或图示
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/items")
def items(db: Session = Depends(get_db)):
return db.query(Item).all()
常见误区
- 把需要在响应前执行的逻辑写在
yield后:清理段在响应之后,不能用于写响应头或校验拦截。 yield后再访问已关闭的资源:清理段应只做释放,不做业务读写。
追问
- 清理代码在 422 校验失败时执行吗?答:执行,进入依赖解析的生成器依赖都会被收尾;未进入解析的不执行。
- 多个
yield依赖清理顺序?答:按依赖解析完成的逆序收尾,类似栈结构。 yield依赖能返回值给端点吗?答:yield产出的值即注入值,return的值不作为注入值。
04.7.15.1-022 yield 依赖抛异常时 finally 与清理如何执行?
一句话结论
端点或上层依赖抛异常时,yield 依赖的 finally 段仍会执行;异常会继续向上传递给异常处理器。若在 yield 后清理段抛新异常,会叠加在原异常之上,需要在清理段内吞掉非关键异常并记录日志。
概念解释
- 框架通过生成器的
throw/收尾机制保证清理被调用,语义等价于try/finally包裹端点调用。 - 清理段不应依赖端点业务状态,避免因异常路径下状态不完整而出错。
原理流程
- 端点执行中抛出异常,异常沿调用栈向上传播。
- 框架在收尾阶段恢复各
yield依赖生成器,触发finally/清理段。 - 清理完成后原始异常交给
HTTPException/自定义异常处理器生成错误响应。
代码或图示
def get_db():
db = SessionLocal()
try:
yield db
finally:
try:
db.close()
except Exception:
logger.exception("close session failed")
常见误区
- 在
yield后用raise覆盖原始异常:清理段抛错会替换/叠加错误信息,影响故障定位。 - 以为异常时不提交事务就自动回滚:需要在清理段或业务代码显式
rollback,会话不会自动替你回滚。
追问
- 清理失败会导致请求 500 吗?答:未捕获的清理异常会进入错误处理,建议清理段内部兜底。
- 如何区分正常结束与异常结束?答:可在依赖内捕获传递的异常,或在端点/异常处理器中统一处理事务回滚。
finally里能发通知吗?答:可以,但注意清理段已在响应后执行,通知失败不应阻断主流程。
04.7.15.1-023 异步 yield 依赖与同步 yield 依赖的执行容器?
一句话结论
async def 带 yield 的依赖在事件循环内异步收尾;同步 def 带 yield 的依赖通过线程池执行。依赖是同步还是异步,与端点是否 async 无关,框架按依赖自身定义选择执行容器。
概念解释
- 异步依赖内可
await异步客户端;同步依赖内调用阻塞库,由 AnyIO 线程池承载。 - 混用规则与路由一致:异步上下文里不要调用阻塞 IO,否则卡住事件循环。
原理流程
- 注册期识别依赖函数是否为协程函数。
- 请求期异步依赖直接
await解析与收尾;同步依赖丢入线程池执行。 - 资源清理段按对应容器恢复生成器执行。
代码或图示
async def get_async_db():
session = AsyncSessionLocal()
try:
yield session
finally:
await session.close()
def get_sync_db():
session = SessionLocal()
try:
yield session
finally:
session.close()
常见误区
- 在
async def依赖里调用同步阻塞驱动:阻塞事件循环,应换成异步驱动或to_thread。 - 把同步依赖写进异步链后期望自动排队:同步段在线程池执行,不占用事件循环线程,但受线程池容量限制。
追问
- 异步依赖里能用
requests吗?答:不能直接用,会阻塞循环,改用httpx.AsyncClient或线程池包装。 - 同步依赖会阻塞其他请求吗?答:在线程池内执行,线程池耗尽时新的同步依赖/路由会排队。
- 一个应用能同时存在两种依赖吗?答:可以,框架按各依赖定义分别调度。
04.7.15.1-024 Depends 传函数、lambda 与可调用对象的差异?
一句话结论
Depends 接收任意可调用对象:普通函数、类、实现 __call__ 的实例都可被解析。lambda 也可作为依赖,但 lambda 签名难以复用、不利于测试与 dependency_overrides,生产代码优先使用命名函数。
概念解释
- 框架对可调用对象统一走签名分析,不区分函数还是实例方法。
- 可调用实例适合携带配置状态,例如初始化时注入阈值、客户端等。
原理流程
Depends保存可调用引用与use_cache等参数。- 解析期读取该可调用对象签名并构建子依赖树。
- 请求期调用可调用对象取得结果并注入。
代码或图示
# 命名函数(推荐)
def get_settings():
return app_settings
# 可调用实例
class ClientFactory:
def __init__(self, base_url: str):
self.base_url = base_url
def __call__(self):
return HttpClient(self.base_url)
dep = Depends(ClientFactory("https://api.example.com"))
# lambda(不推荐用于生产)
Depends(lambda x: x)
常见误区
- lambda 依赖无法被
dependency_overrides按引用替换:测试替换依赖需要可稳定引用的命名函数。 - 在可调用实例的
__init__里做重 IO:实例化仍发生在请求路径上,重资源应外部构造。
追问
Depends不传参数可以吗?答:Depends()会把端点函数自身作为依赖来源,通常显式传 callable 更清晰。- 依赖能是绑定方法吗?答:能,实例方法作为可调用对象被解析,
self由调用方持有。 - 可调用对象签名分析支持
*args/**kwargs吗?答:不明确的可变参数无法稳定绑定,建议显式声明参数。
04.7.15.1-025 Security 与 Depends 的区别及 scope 传递?
一句话结论
Security 是 Depends 的特化版本,用于安全认证依赖,额外携带 scopes 列表,支持 OAuth2/OpenAPI 的作用域声明。普通依赖注入用 Depends;涉及认证、授权与 OAuth scope 时用 Security,它会把 scopes 记录到 OpenAPI 安全方案。
概念解释
Security(dep, scopes=["read", "write"])把所需作用域传给安全依赖,依赖内可校验令牌是否包含这些 scope。- 底层解析机制与
Depends相同,差别在安全元数据与 scope 传播。
原理流程
- 端点参数用
Security(oauth2_scheme, scopes=[...])声明。 - 注册期把 scopes 写入该操作的安全要求,生成 OpenAPI
security条目。 - 请求期执行安全依赖,校验令牌与 scope 后返回当前用户/凭据。
代码或图示
from fastapi import Security, HTTPException
from fastapi.security import OAuth2PasswordBearer
oauth2 = OAuth2PasswordBearer(tokenUrl="login")
@app.get("/items", dependencies=[Security(oauth2, scopes=["items:read"])])
def list_items():
...
常见误区
- 用
Depends做 OAuth2 安全方案导致文档不显示授权头:安全方案需要Security/安全类依赖才能正确生成 OpenAPI 安全要求。 - 只在声明处写 scopes 而依赖内不校验:文档声明不等于鉴权生效,依赖内必须检查令牌 scope。
追问
Security支持子依赖传递 scope 吗?答:scopes 沿安全依赖链传播,子依赖可读取所需作用域。- 多个
Security是 AND 还是 OR?答:同一操作多个安全要求的组合语义按 OpenAPI 规范,常见为并列要求。 - 普通依赖能用
scopes参数吗?答:scopes是Security的参数,Depends不提供。
04.7.15.1-026 OAuth2PasswordBearer 作为依赖的底层行为?
一句话结论
OAuth2PasswordBearer 是一个可调用安全依赖:从请求头 Authorization: Bearer <token> 提取令牌字符串,未提供时按配置抛 401 或返回 None。它只负责取令牌,不校验签名;校验由后续依赖或安全库完成。
概念解释
tokenUrl只是 OpenAPI 文档中的登录地址声明,类本身不向该地址发请求。auto_error=True(默认)缺失头直接 401;设为False时返回None,由依赖自行处理可选认证。
原理流程
- 请求到达,框架执行安全依赖实例。
- 读取
Authorization头,按Bearer前缀拆分出令牌。 - 头缺失/格式不符时按
auto_error抛 401 或返回None;令牌字符串交给上层校验。
代码或图示
from fastapi.security import OAuth2PasswordBearer
oauth2 = OAuth2PasswordBearer(tokenUrl="login", auto_error=True)
@app.get("/me")
def me(token: str = Depends(oauth2)):
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
return payload
常见误区
- 以为
OAuth2PasswordBearer完成了 JWT 校验:它只提取字符串,验签、过期、scope 检查都要自己做。 - 把
tokenUrl当成实际回调地址:它仅用于 Swagger UI 的授权交互,不参与运行时请求。
追问
- 令牌放在 Cookie 怎么办?答:使用
OAuth2PasswordBearer不适合 Cookie 场景,自定义依赖从request.cookies读取。 auto_error=False有什么用?答:用于“登录可访问、未登录也可匿名访问”的混合端点。- 令牌提取失败返回什么状态码?答:默认 401,可在依赖内自定义
WWW-Authenticate头。
04.7.15.1-027 依赖返回值与参数类型注解如何匹配注入?
一句话结论
注入按参数名匹配依赖返回值,类型注解主要用于生成 Schema 与文档,不做“返回类型必须是注解子类”的强制转换。依赖返回什么就注入什么;端点注解与实际类型不符不会自动转换,但可能在响应模型序列化阶段暴露问题。
概念解释
- 依赖解析结果绑定到端点函数对应参数名,类型注解参与 OpenAPI 生成与参数绑定推断。
- 复杂返回对象(ORM 实例、服务对象)直接注入,不需要模型转换。
原理流程
- 依赖 callable 返回结果对象。
- 框架按端点签名参数名把结果放入调用参数。
- 调用端点函数,注解仅作为类型提示与文档依据。
代码或图示
def get_item(item_id: int) -> Item:
return repo.get(item_id)
@app.get("/{item_id}")
def detail(item: Item = Depends(get_item)):
return item
常见误区
- 以为类型注解会触发 Pydantic 校验把返回值转成模型:依赖注入不做模型转换,响应阶段才按
response_model裁剪校验。 - 注解写成 dict 但实际返回 ORM 对象:文档 Schema 与真实返回不符,需在
response_model上明确输出模型。
追问
- 依赖返回
None会怎样?答:注入None,端点注解非可选时文档可能标注不当,运行时不报错。 - 多个依赖返回同名对象会冲突吗?答:按参数名分别注入,参数名不同即可共存。
- 如何保证返回类型正确?答:在依赖内或响应模型层做校验,类型注解本身不强制。
04.7.15.1-028 Annotated[X, Depends(...)] 与 = Depends(...) 写法演进?
一句话结论
两种写法等价:旧写法 x: Session = Depends(get_db) 用默认值携带依赖;新写法 x: Annotated[Session, Depends(get_db)] 把元数据放进类型注解。FastAPI 0.11x 两者都支持,Annotated 写法是推荐方向,便于复用带依赖的类型别名。
概念解释
Annotated把类型与元数据打包,可提取成别名:DB = Annotated[Session, Depends(get_db)],端点直接复用。- 默认值写法历史更长,存量代码中大量存在;新代码统一
Annotated风格可读性更好。
原理流程
- 框架读取参数注解:若是
Annotated类型,从中提取Depends/Query等元数据。 - 若无
Annotated,则从参数默认值读取依赖声明。 - 两种来源合并后构建同一依赖树。
代码或图示
from typing import Annotated
# 旧写法
@app.get("/a")
def a(db: Session = Depends(get_db)):
...
# 新写法(推荐)
@app.get("/b")
def b(db: Annotated[Session, Depends(get_db)]):
...
# 复用别名
DB = Annotated[Session, Depends(get_db)]
@app.get("/c")
def c(db: DB):
...
常见误区
- 在
Annotated里同时写Depends和默认值导致重复声明:二选一,混合时框架按声明解析,容易混乱。 - 把
Annotated元数据当成运行时类型:Annotated在运行时可被typing.get_args提取,但不改变对象实际类型。
追问
Annotated需要 Python 版本?答:typing.Annotated自 Python 3.9 起可用;3.8 需typing_extensions。- 参数默认值还能与
Annotated共存吗?答:可给可选参数设默认值,依赖元数据仍放Annotated。 - 别名里能放
Query约束吗?答:能,Q = Annotated[str, Query(min_length=1)]可复用约束。
04.7.15.1-029 依赖被多个子依赖引用时缓存粒度?
一句话结论
同一请求内,被多个父依赖引用的同一 callable 依赖默认只解析一次,所有父依赖拿到同一实例;缓存以依赖 callable 为单位。若各父依赖需要独立实例,对应依赖需 use_cache=False。
概念解释
- 缓存共享发生在请求作用域内,与依赖在树中的位置无关。
- 不同 callable 即使逻辑相近也分别缓存,不按返回值内容去重。
原理流程
- 子依赖首次被解析时结果写入请求缓存。
- 另一父依赖解析到同一 callable 时命中缓存。
- 两个父依赖收到同一对象引用。
代码或图示
def common():
return {"trace": uuid4().hex}
def dep_a(c: dict = Depends(common)):
return c
def dep_b(c: dict = Depends(common)):
return c
@app.get("/x")
def x(a: dict = Depends(dep_a), b: dict = Depends(dep_b)):
return a is b # True
常见误区
- 期望各父依赖拿到独立副本而不显式关闭缓存:默认共享同一引用,一方修改会影响另一方。
- 把共享实例当成跨请求单例:请求结束缓存销毁,下次请求重新解析。
追问
- 缓存会序列化返回值吗?答:不会,直接保存对象引用。
- 关闭缓存后父依赖之间仍能共享吗?答:不能,每次引用独立执行。
- 如何在多个请求间共享对象?答:放在
app.state、外部连接池或缓存服务中。
04.7.15.1-030 依赖函数内如何访问 Request 与 Response?
一句话结论
依赖函数可像端点一样声明 request: Request、response: Response 类型参数,框架自动注入 Starlette 请求对象与响应对象。依赖内可读取头、查询串、Cookie,也可通过注入的 Response 设置响应头与 Cookie。
概念解释
Request封装 ASGIscope/receive,提供headers、query_params、cookies、json()等接口。- 注入的
Response是端点最终响应的载体,依赖内设置的头会保留到响应。
原理流程
- 依赖签名中出现
Request类型注解,框架识别为请求对象注入。 - 出现
Response类型注解时注入响应对象引用。 - 依赖内读取请求信息或写入响应头/ Cookie,随请求流程传递。
代码或图示
from fastapi import Request, Response
def add_header(request: Request, response: Response):
response.headers["X-Trace-Id"] = request.headers.get("X-Trace-Id", "-")
@app.get("/x", dependencies=[Depends(add_header)])
def x():
...
常见误区
- 在依赖内直接
await request.body()后端点再读 body:请求体流只能消费一次,重复读取会为空,需要缓存到request.state。 - 以为注入的
Response与端点返回的JSONResponse是同一对象:框架会把依赖设置的头合并到最终响应上。
追问
- 依赖能读取查询参数并做校验吗?答:能,
request.query_params可读;结构化校验仍建议用Query参数声明。 - 如何在依赖里终止请求?答:抛
HTTPException短路,或返回自定义响应;副作用依赖不直接返回响应体。 Request对象跨请求隔离吗?答:每个请求独立实例,基于 ASGI scope 构建,互不干扰。
04.7.15.1-031 Path/Query/Header/Cookie 分别从哪里取值?
一句话结论
Path 取 URL 路径段,Query 取查询串参数,Header 取请求头,Cookie 取请求 Cookie。参数有无默认值决定必填还是可选;类型注解决定转换与校验方式。未声明来源的简单标量参数,FastAPI 默认按 Query 处理。
概念解释
- 四类来源对应 HTTP 请求不同位置,绑定阶段分别从
scope、query_params、headers、cookies取值。 - 路径参数必然出现在 URL 中;查询/头/Cookie 可缺失,由默认值或可选注解处理。
原理流程
- 注册期按参数声明(
Path/Query/Header/Cookie)归类来源。 - 请求期从对应位置读取原始字符串。
- 按类型注解做转换与约束校验,失败收集为 422 错误。
代码或图示
@app.get("/items/{item_id}")
def read(
item_id: int = Path(),
q: str | None = Query(default=None, max_length=50),
token: str = Header(),
sid: str | None = Cookie(default=None),
):
...
常见误区
- 标量参数不显式写
Query():默认按 Query 绑定,但显式声明约束(min_length、alias)更清晰,也避免来源推断错误。 - 把 Header 参数名写成带下划线形式:Header 名默认把下划线转中划线,需注意与真实头名对齐。
追问
- 路径参数能设默认值吗?答:不能,路径段必须存在;可选段需另设计路由。
- Cookie 缺失返回什么?答:有默认值注入默认值;无默认值且非 Optional 则 422。
- 同一参数能同时从 Query 和 Header 取吗?答:不能跨来源合并,需分别声明参数。
04.7.15.1-032 单 Body 参数与多 Body 参数如何包装嵌套对象?
一句话结论
单个 Pydantic 模型参数直接作为请求体根对象;端点声明多个 Body 模型参数时,FastAPI 会把请求体包装成 {模型字段名: 模型实例} 的嵌套结构,用字段名作为外层键。显式 Body(embed=True) 可强制单模型也按嵌套键包裹。
概念解释
- 多模型共存时无法把两个扁平对象平铺到同一 JSON 根,框架以参数名做外层分组。
embed控制是否始终用字段名包裹,影响前端发送的 JSON 结构。
原理流程
- 注册期统计端点 Body 参数数量与模型。
- 单模型:请求体直接解析为该模型;多模型:按参数名构造外层 dict 分别解析。
- 解析失败在对应字段位置收集 422 错误。
代码或图示
class Item(BaseModel):
name: str
class User(BaseModel):
username: str
# 请求体:{"item": {"name": "x"}, "user": {"username": "u"}}
@app.post("/multi")
def multi(item: Item = Body(), user: User = Body()):
...
# 强制包裹:{"item": {"name": "x"}}
@app.post("/one")
def one(item: Item = Body(embed=True)):
...
常见误区
- 多 Body 时前端按扁平字段发送导致 422:必须按外层分组结构发送。
- 混用
Form与 JSON Body:二者不能在同一端点共存,Form走 multipart 表单编码。
追问
Body(embed=False)何时生效?答:多参数场景框架自动 embed;单参数显式embed=True才包裹。- Body 里能放标量字段吗?答:可以,
Body()标量参数同样进入外层分组结构。 - 嵌套模型校验失败定位到哪一层?答:错误
loc沿外层键 → 模型字段逐层记录。
04.7.15.1-033 Form 与 File 何时必须安装 python-multipart?
一句话结论
端点使用 Form 或 File 参数时,请求按 multipart/form-data 或表单编码解析,必须安装 python-multipart 依赖;未安装时 FastAPI 在启动/请求阶段抛出缺少该包的错误。JSON Body 端点不需要它。
概念解释
Form解析表单字段,File解析上传文件,二者底层都依赖 multipart 解析器。- 依赖声明:
pip install python-multipart,进入生产镜像时一并安装。
原理流程
- 注册期检测到
Form/File参数,标记端点需要表单解析。 - 请求到达后框架调用 multipart 解析器读取表单字段与文件流。
- 字段绑定为普通值,文件绑定为
UploadFile或bytes。
代码或图示
from fastapi import Form, File, UploadFile
@app.post("/upload")
async def upload(
title: str = Form(),
file: UploadFile = File(),
):
return {"title": title, "size": file.size}
常见误区
- 只在开发环境装了 multipart,生产镜像漏装:上线后表单/上传端点报错,需把依赖写入锁文件。
- 同一端点同时声明 JSON 模型与
Form:Content-Type 只能选一种,混用会导致解析失败。
追问
Form能接收嵌套对象吗?答:表单是扁平键值结构,嵌套需前端展开键名或改用 JSON Body。- 不装 multipart 报错信息是什么?答:FastAPI 提示需要安装
python-multipart才能使用 Form/File。 - 大文件上传走 Form 合适吗?答:
UploadFile有大小阈值与临时文件机制,超大文件需评估流式与磁盘策略。
04.7.15.1-034 File 的 UploadFile 与 bytes 区别及读取方式?
一句话结论
File() 注解为 UploadFile 时拿到包装对象,提供 filename、content_type、size、read()/write()/seek() 与异步接口;注解为 bytes 时直接把整个文件读进内存。小文件用 bytes 简单,大文件用 UploadFile 流式处理避免内存爆掉。
概念解释
UploadFile底层是 SpooledTemporaryFile:内存超过阈值后落临时文件,支持异步读写。bytes模式一次性载入内存,文件大时直接抬高内存峰值。
原理流程
- multipart 解析器识别文件部分。
- 注解
UploadFile:包装为上传文件对象,元数据与句柄随对象暴露。 - 注解
bytes:读取全部内容为字节串注入参数。
代码或图示
@app.post("/up")
async def up(file: UploadFile = File()):
content = await file.read()
return {"name": file.filename, "type": file.content_type}
@app.post("/up-bytes")
def up_bytes(data: bytes = File()):
return {"len": len(data)}
常见误区
- 用
bytes接收用户头像/附件后不限制大小:恶意大文件直接打满内存,必须配合大小校验与网关限制。 - 在异步端点里调用同步
file.read():UploadFile提供异步方法,应await file.read(),同步方法在线程池语义下使用。
追问
UploadFile临时文件何时清理?答:请求结束后由框架关闭/删除临时文件(待确认:验证点:不同版本临时文件回收策略)。- 如何限制上传类型?答:校验
content_type与扩展名,服务端再做文件头魔数检测。 - 能分块读取吗?答:
read(size)按字节读取,配合seek实现流式处理。
04.7.15.1-035 Path/Query 的长度与数值约束如何生成校验?
一句话结论
Query/Path 支持 min_length、max_length、pattern(字符串)与 gt、ge、lt、le、multiple_of(数值)等约束;这些约束既在请求期做校验,也进入 OpenAPI Schema。约束写法与 Pydantic Field 对齐。
概念解释
- 字符串约束作用于长度/正则;数值约束作用于大小关系;容器类型还可约束最小/最大项数。
- 校验失败的错误类型与字段位置写入 422 响应。
原理流程
- 注册期把约束收集到参数 Schema。
- 请求期取值后按约束逐项校验。
- 全部通过才注入端点;任一失败收集错误并返回 422。
代码或图示
@app.get("/items")
def items(
q: str = Query(min_length=2, max_length=20, pattern=r"^\w+$"),
page: int = Query(default=1, ge=1, le=100),
size: int = Query(default=10, gt=0, multiple_of=5),
):
...
常见误区
- 数值约束写成字符串边界:
gt=0必须传数值,传"0"不被识别为数值约束。 - 正则约束只在文档里出现而运行时不校验:FastAPI 会把
pattern接入 Pydantic 校验,运行时同样生效。
追问
pattern与旧regex参数关系?答:0.11x 使用pattern,旧regex为兼容保留(待确认:验证点:当前版本弃用状态)。- 列表 Query 能约束元素个数吗?答:
min_length/max_length作用于列表长度。 - 校验失败返回哪个状态码?答:422 Unprocessable Entity,错误体含字段级详情。
04.7.15.1-036 Header 下划线转中划线与 Cookie 命名规则?
一句话结论
Header 参数名默认把 Python 下划线 _ 转为 HTTP 中划线 -(如 x_token 对应 X-Token);可用 alias 指定真实头名覆盖。Cookie 名区分大小写,直接按声明名从 request.cookies 读取,不做下划线转换。
概念解释
- HTTP 头惯例使用中划线,Python 标识符只能用下划线,框架做名称映射以符合两侧惯例。
- 若真实头名本身含下划线,需用
alias显式声明避免被转换。
原理流程
- 注册期记录参数名与是否设置
alias。 - 未设 alias 时把下划线替换为中划线作为头名查找。
- 命中后按类型注解转换注入。
代码或图示
@app.get("/")
def h(x_app_version: str = Header(), trace_id: str = Header(alias="X-Trace-Id")):
...
常见误区
- 头名含下划线导致映射后找不到:真实头名带下划线时必须
alias指定。 - 以为 Cookie 也做下划线转换:Cookie 名原样匹配,不转换。
追问
- 关闭下划线转换可以吗?答:通过
alias指定精确头名即可绕过默认转换。 - 重复头名如何取值?答:
request.headers.getlist可取多值,单参数默认取首值(待确认:验证点:多值 Header 参数注解写法)。 - 头名大小写敏感吗?答:HTTP 头名不区分大小写,框架按规范化名称匹配。
04.7.15.1-037 Annotated 元数据写法与 Query/Path 装饰器等价性?
一句话结论
Annotated[str, Query(min_length=2)] 与 q: str = Query(min_length=2) 等价,框架两种来源都能解析。Annotated 写法便于把类型与约束打包成可复用别名,是 0.11x 推荐风格;默认值写法在存量代码中继续可用。
概念解释
- 元数据(Query/Path/Header/Body/Depends)作为
Annotated的第二个及以后参数存放。 - 别名复用可统一全局约束,例如分页大小、搜索串长度。
原理流程
- 框架提取参数注解中的
Annotated元数据。 - 与默认值中的声明合并去重。
- 生成参数 Schema 与依赖树。
代码或图示
from typing import Annotated
Page = Annotated[int, Query(ge=1, le=100)]
Keyword = Annotated[str, Query(min_length=1, max_length=30)]
@app.get("/search")
def search(page: Page, q: Keyword):
...
常见误区
- 别名里同时塞
Query和Depends导致来源冲突:一个参数只应有一个来源元数据,依赖另开参数。 - 把
Annotated当成类型运行时判断:它是注解包装,isinstance不识别包装后的类型。
追问
Annotated里能放多个元数据吗?答:可以,例如同时携带Query与文档描述,按框架提取规则解析。- 旧代码需要批量改
Annotated吗?答:不需要,默认值写法仍受支持,新代码统一即可。 - 别名跨模块复用有什么风险?答:约束被隐式继承,修改别名会影响所有使用处,需评审。
04.7.15.1-038 复杂类型作为 Query/Path 如何解析与校验?
一句话结论
Query/Path 原始值是字符串,框架按类型注解转换:int、float、bool、UUID、Decimal、Enum/Literal 由 Pydantic 解析;list/set 类型接收重复参数值。解析失败进入 422,复杂嵌套对象不能走 Query,应放 Body。
概念解释
- 布尔值识别
true/false(不区分大小写)等常见字面量;UUID 按标准格式校验。 - 枚举参数限定在枚举成员范围内,序列化时取成员值。
原理流程
- 从查询串/路径段取出原始字符串或字符串列表。
- Pydantic 按注解类型做转换与约束校验。
- 成功注入枚举/UUID/数值实例;失败记录类型错误。
代码或图示
from enum import Enum
from uuid import UUID
class Status(str, Enum):
active = "active"
archived = "archived"
@app.get("/items")
def items(status: Status, uid: UUID, tags: list[str] = Query(default=[])):
...
常见误区
- 把 JSON 字符串塞进 Query 再用模型解析:嵌套结构应放 Body;Query 只适合标量与标量列表。
- 数值参数传千分位/空格导致转换失败:输入需是规范字面量,前置清洗在依赖或校验层做。
追问
bool接受哪些值?答:常见true/false、1/0、on/off、yes/no等(待确认:验证点:当前版本可识别字面量清单)。- 列表 Query 重复传参怎么写?答:
?tags=a&tags=b,注解为list[str]。 - 枚举作为 Path 参数会校验取值范围吗?答:会,不在枚举内返回 422。
04.7.15.1-039 请求体嵌套模型校验失败的错误位置如何定位?
一句话结论
Pydantic 校验错误的 loc 按嵌套层级记录(外层键、模型字段、列表索引),FastAPI 422 响应原样携带该位置链。排查时按 loc 逐层下钻,定位是哪个嵌套字段、列表第几个元素出问题。
概念解释
- 错误结构含
loc(位置)、msg(错误说明)、type(错误类型)、input(原始输入)。 - 嵌套模型与列表元素各自独立校验,错误位置链保持完整。
原理流程
- 请求体解析为外层模型,逐层递归校验嵌套字段。
- 某字段失败时把路径追加到错误
loc。 - 全部错误收集后由 FastAPI 包装成 422 响应体返回。
代码或图示
{
"detail": [
{
"loc": ["body", "items", 1, "price"],
"msg": "Input should be greater than 0",
"type": "greater_than",
"input": -3
}
]
}
常见误区
- 只看错误
msg不看loc:嵌套场景下多个同名字段容易定位错层级。 - 自定义校验错误不携带位置:
ValueError在field_validator中抛出,位置自动绑定到当前字段。
追问
- 列表元素失败 loc 如何表示?答:列表索引作为数字段出现在
loc中。 - 422 错误体能改格式吗?答:注册自定义
RequestValidationError处理器重新组织响应结构。 - 错误里的
input会脱敏吗?答:默认保留输入值,敏感字段需在模型层配置截断或排除。
04.7.15.1-040 Form 字段与 JSON Body 能否在同一端点共存?
一句话结论
不能。Form/File 端点按 multipart/form-data(或 urlencoded 表单)解析,JSON Body 端点按 application/json 解析,Content-Type 互斥;同一端点内混用会导致框架无法确定编码方式,参数绑定失败。需要混合传输时拆分端点或整体走 multipart。
概念解释
- 浏览器表单上传天然 multipart;JSON API 用 application/json,二者编码模型不同。
- 文本字段走 Form、文件走 File 是常见组合;JSON 模型与 Form 不能并列。
原理流程
- 注册期扫描参数来源,判定端点编码类型。
- 请求按声明编码读取对应部分。
- 编码与实际 Content-Type 不符则解析失败。
代码或图示
# 可行:表单字段 + 文件
@app.post("/profile")
def profile(nickname: str = Form(), avatar: UploadFile = File()):
...
# 不可行:JSON 模型与 Form 并列
# def bad(item: Item, nickname: str = Form()): ...
常见误区
- 前端 Postman 同时填 form-data 与 raw JSON:服务端只按一种编码解析,另一部分丢失。
- 以为可以用
Body包一个嵌套对象进 Form:扁平表单无法承载嵌套模型,需改 JSON 或展开键名。
追问
- 上传 JSON 文件与表单字段怎么共存?答:文件内容在服务端读取后解析为模型,字段仍走 Form。
- urlencoded 表单支持文件吗?答:不支持文件,文件必须 multipart。
- 如何兼容两种 Content-Type?答:提供两个端点,或在中间层按头分流,单一端点不混用。
04.7.15.1-041 一个 FastAPI 请求从 ASGI 到响应的完整链路?
一句话结论
完整链路:ASGI 服务器(uvicorn/hypercorn)解析 HTTP → 构造 ASGI scope/receive/send → Starlette 中间件栈 → 路由匹配 → FastAPI 解析请求参数与依赖树 → 执行端点(同步路由进线程池)→ 按 response_model 序列化 → 写回响应 → 执行 yield 依赖清理与后台任务。
概念解释
- FastAPI 应用本身是 ASGI 可调用对象,挂在 Starlette 路由系统之上。
- 各阶段失败都会被对应异常处理器捕获,转换为错误响应。
原理流程
- 服务器接收请求,构造
scope(路径、方法、头、客户端)与收发通道。 - 穿过应用注册的中间件,进入路由器匹配路由。
- 解析 Query/Path/Header/Cookie/Body 与依赖树,注入端点参数。
- 执行端点,拿到返回值;有响应模型则裁剪校验并序列化。
- 响应发出后收尾:后台任务执行、
yield依赖清理、中间件回程。
代码或图示
uvicorn → ASGI scope → middleware stack → router match
→ dependency resolution → endpoint (loop/threadpool)
→ response model serialization → send response
→ BackgroundTasks → yield cleanup → middleware outbound
常见误区
- 把依赖解析放在端点函数内部理解:依赖在端点调用前由框架完成解析与注入。
- 以为后台任务在响应发送前执行:
BackgroundTasks在响应发送后运行,不阻塞客户端收到响应。
追问
- 哪一步最容易成为性能瓶颈?答:参数/模型校验与响应序列化是 CPU 密集段,大请求体下明显。
- 中间件与依赖谁先执行?答:中间件包裹整个路由处理,先于依赖解析进入、后于清理退出。
- 422 在哪一步产生?答:参数绑定与 Pydantic 校验阶段,端点函数不会被调用。
04.7.15.1-042 Starlette 中间件与 FastAPI 依赖的执行顺序?
一句话结论
中间件在 ASGI 外层包裹整个请求处理:进入时先于依赖解析,退出时晚于端点与依赖清理。依赖在路由匹配之后、端点执行之前解析。典型顺序:中间件进入 → 路由匹配 → 依赖解析 → 端点 → 响应 → 依赖清理 → 中间件退出。
概念解释
- 中间件基于 ASGI 可调用链包装,适合跨所有路由的横切:CORS、日志、GZip、请求 ID。
- 依赖与具体路由/参数绑定,适合鉴权、会话、资源获取。
原理流程
- 请求进入中间件栈,由外到内依次执行进入逻辑。
- 到达路由器匹配端点,解析依赖树。
- 端点执行完返回响应,依赖清理收尾。
- 响应沿中间件栈由内到外回程处理。
代码或图示
@app.middleware("http")
async def log_request(request: Request, call_next):
# 进入:先于依赖
response = await call_next(request)
# 退出:晚于依赖清理
return response
常见误区
- 在中间件里读取请求体后又交给依赖/端点读取:body 流被消费一次,需缓存到
request.state再放行。 - 用中间件做需要模型校验的鉴权:中间件拿不到已解析模型,复杂校验应放在依赖层。
追问
- 中间件能拿到响应模型吗?答:拿到的是响应对象,模型裁剪已在更内层完成。
- 多个中间件顺序如何确定?答:后注册的在最外层包裹,按注册逆序进入、顺序退出。
- 依赖抛异常会穿过中间件吗?答:会,异常沿 ASGI 链上抛,中间件可捕获记录。
04.7.15.1-043 Request 对象在 scope/receive/send 之上封装了什么?
一句话结论
Starlette Request 封装 ASGI scope/receive,提供属性化接口:method、url、path、headers、query_params、cookies、client、state,以及 json()、body()、form()、stream() 等读取方法。它不代表请求已解析,原始 ASGI 通道仍在其底层。
概念解释
scope是连接元数据 dict;receive是读取 body 的消息通道;send属于响应方向,Request 一般不持有。request.state是请求级临时存储,供中间件与依赖之间传递数据。
原理流程
- ASGI 服务器把
scope/receive交给应用。 - 框架构造
Request(scope, receive),把原始 dict/通道包装成属性与方法。 - 业务代码通过 Request 接口读取请求信息,无需直接操作 ASGI 消息。
代码或图示
@app.middleware("http")
async def mw(request: Request, call_next):
request.state.trace_id = request.headers.get("X-Trace-Id", "-")
response = await call_next(request)
return response
常见误区
- 缓存整个 Request 到全局:Request 绑定单次请求 scope,跨请求持有会造成状态串扰与资源滞留。
- 多次调用
body()/json():body 只接收一次,重复读取需使用框架缓存或自行保存到 state。
追问
request.app指向什么?答:当前 ASGI 应用实例,可访问app.state等。query_params与scope.query_string区别?答:前者是解析后的多值映射,后者是原始字符串。- 如何在依赖间共享请求级数据?答:写入
request.state,同请求内各层读取同一对象。
04.7.15.1-044 直接返回 Response 与模型序列化两条路径?
一句话结论
端点返回 Response(含 JSONResponse、PlainTextResponse、StreamingResponse)实例时,框架直接采用该响应,不再走 response_model 裁剪;返回普通 dict/模型实例时,框架按 response_model 校验、过滤字段后序列化为 JSON。
概念解释
- 显式 Response 用于自定义状态码、头、Cookie、流式内容与非 JSON 格式。
- 模型序列化路径负责隐藏内部字段、类型转换与输出校验,避免 ORM 对象直接外泄。
原理流程
- 端点返回值传入响应处理流程。
- 若为
Response子类实例:直接作为最终响应。 - 否则按
response_model(或返回类型注解)做输出校验与字段过滤,再编码 JSON。
代码或图示
@app.get("/raw")
def raw():
return Response(content="hello", media_type="text/plain", status_code=200)
@app.get("/items/{i}", response_model=ItemOut)
def item(i: int):
return repo.get(i) # 按 ItemOut 裁剪后序列化
常见误区
- 返回自定义 Response 后仍指望
response_model过滤敏感字段:显式响应跳过模型裁剪,字段暴露风险自行控制。 - 流式响应误用模型序列化:大文件/流应返回
StreamingResponse,不要把全量内容读进内存再序列化。
追问
- 端点能同时设状态码与返回模型吗?答:可以,
status_code作用于模型序列化路径;Response 实例自带状态码。 - 返回
JSONResponse还会过模型校验吗?答:不会,实例直接发出。 - 响应模型校验失败返回什么?答:输出校验错误一般在序列化阶段暴露,按框架错误处理流程返回 500/422(待确认:验证点:当前版本响应校验失败的状态码约定)。
04.7.15.1-045 BackgroundTasks 的执行时机及与 yield 清理顺序?
一句话结论
BackgroundTasks 收集的任务在响应发送给客户端之后执行,不阻塞响应返回;yield 依赖的清理同样在响应后运行。一般顺序为:响应发出 → 后台任务执行 → yield 依赖收尾(具体先后以 FastAPI/Starlette 实现为准,复杂资源释放不要依赖跨阶段顺序)。
概念解释
- 后台任务适合发邮件、写日志、触发非关键通知;不能放失败会影响主响应结论的逻辑。
- 任务在请求上下文内运行,异常需自行捕获,避免拖垮收尾流程。
原理流程
- 端点把
BackgroundTasks注入参数,通过add_task注册可调用对象与参数。 - 响应主体发出后,框架依次执行已注册任务。
- 依赖生成器在收尾阶段被恢复执行清理段。
代码或图示
from fastapi import BackgroundTasks
def send_welcome(email: str):
mailer.send(email)
@app.post("/signup")
def signup(email: str, tasks: BackgroundTasks):
tasks.add_task(send_welcome, email)
return {"ok": True}
常见误区
- 把数据库事务提交放后台任务:主响应已返回,任务失败会导致数据不一致;关键写操作应在响应前完成。
- 后台任务里再抛未捕获异常:可能在收尾阶段产生未处理错误,任务内部要兜底记录。
追问
- 后台任务能
async吗?答:能,协程任务在事件循环内执行,同步任务在线程池执行。 - 多个后台任务并行还是串行?答:按注册顺序依次执行(待确认:验证点:当前版本是否并发调度)。
- 后台任务共享请求资源安全吗?答:请求级资源在收尾阶段可能已释放,任务内不要依赖会话仍打开。
04.7.15.1-046 app.state 存放什么,与请求级依赖的边界?
一句话结论
app.state 是应用级单例命名空间,存放跨请求共享的对象:配置、初始化好的客户端、连接池、缓存实例。请求级可变状态(当前用户、请求 trace、临时会话)放在依赖或 request.state,不能写进 app.state,否则会跨请求串扰。
概念解释
app.state属性动态挂载,底层是State对象;进程内所有请求访问同一实例。- 多 worker 部署时每个进程一份
app.state,不是分布式共享存储,跨进程状态需用外部缓存/数据库。
原理流程
- 应用启动时在 lifespan 或模块加载期初始化共享对象,挂到
app.state。 - 请求内通过
request.app.state读取共享对象。 - 请求结束不清理
app.state;进程关闭时随应用回收。
代码或图示
from fastapi import FastAPI, Request
app = FastAPI()
@app.on_event("startup")
def startup():
app.state.http_client = HttpClient(base_url="https://api.example.com")
@app.get("/x")
def x(request: Request):
client = request.app.state.http_client
...
常见误区
- 把当前用户信息写进
app.state:多请求并发覆盖,造成越权与串号。 - 在
app.state存需要按请求隔离的可变对象:隔离需求用依赖注入或request.state。
追问
app.state与全局变量区别?答:语义上都是进程内单例,state提供统一挂载点与类型约定,便于测试替换。- 多实例部署共享
app.state吗?答:不共享,各进程独立;跨进程一致状态走 Redis/DB。 - 启动期初始化失败怎么办?答:在 lifespan/startup 中抛错使进程启动失败,避免带病上线。
04.7.15.1-047 lifespan 与 startup/shutdown 事件的关系?
一句话结论
lifespan 是 ASGI 标准的应用生命周期处理器,以 yield 分隔启动与关闭两段,替代旧的 @app.on_event("startup")/shutdown 事件;FastAPI 0.11x 仍兼容旧事件写法,但新代码推荐 lifespan 上下文管理器。资源在 yield 前初始化,yield 后清理。
概念解释
- lifespan 由 ASGI 服务器在应用启动与关闭时驱动,早于/晚于任何请求处理。
- 旧事件是 FastAPI 对 Starlette 早期机制的封装,新代码统一 lifespan。
原理流程
- 定义
async def lifespan(app):,yield 前为启动逻辑。 FastAPI(lifespan=lifespan)注册处理器。- 服务器启动执行 yield 前段;关闭时恢复执行 yield 后清理段。
代码或图示
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.client = HttpClient()
yield
await app.state.client.aclose()
app = FastAPI(lifespan=lifespan)
常见误区
- 在 lifespan 里做请求级资源初始化:生命周期只跑一次,请求级资源应由依赖按请求获取。
- 关闭段不做资源释放:连接池、后台线程、客户端不关闭会导致进程退出时资源泄漏。
追问
- 旧
on_event还能用吗?答:0.11x 兼容保留,但属旧写法,迁移期可共存。 - lifespan 抛异常会怎样?答:启动段抛错导致应用启动失败;关闭段异常影响收尾与退出码。
- lifespan 能注册多个吗?答:一个应用一个 lifespan;多个资源在同一上下文内按顺序初始化与逆序清理。
04.7.15.1-048 HTTPException 与 RequestValidationError 何时被包装?
一句话结论
HTTPException 在端点/依赖内主动抛出,由 FastAPI 异常处理器按 status_code 与 detail 生成错误响应;RequestValidationError 是参数/请求体校验失败时框架自动抛出的校验异常,默认处理器返回 422 与结构化错误详情。两者都可注册自定义处理器覆盖默认响应格式。
概念解释
HTTPException携带状态码、detail 与可选 headers;业务短路(未登录、无权限、资源不存在)用它。RequestValidationError继承自ValueError,内部持有 Pydantic 校验错误列表。
原理流程
- 业务代码
raise HTTPException(status_code=404, detail="未找到")。 - 框架异常中间件匹配处理器,生成对应 JSON 响应。
- 校验阶段收集到错误后抛
RequestValidationError,默认处理器包装为 422 响应。
代码或图示
from fastapi import HTTPException, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
@app.exception_handler(RequestValidationError)
async def on_validation(request: Request, exc: RequestValidationError):
return JSONResponse(status_code=422, content={"errors": exc.errors()})
常见误区
- 业务异常直接
raise ValueError:未注册处理器时会变成 500;应抛HTTPException或注册对应异常处理器。 - 自定义 422 处理器后丢掉错误位置信息:保留
exc.errors()中的loc便于前端定位。
追问
HTTPException能携带自定义响应头吗?答:构造时传headers={"X-Error": "..."}。- 校验失败端点会执行吗?答:不会,参数绑定阶段短路,端点函数未被调用。
- 如何统一错误响应结构?答:为
HTTPException、RequestValidationError、兜底Exception分别注册处理器。
04.7.15.1-049 中间件如何注册,与依赖执行先后?
一句话结论
HTTP 中间件用 @app.middleware("http") 注册,接收 request 与 call_next;也可 app.add_middleware(...) 挂载 Starlette 内置中间件(CORS、GZip、TrustedHost 等)。中间件在最外层包裹请求,先于依赖解析进入,晚于依赖清理退出。
概念解释
- 中间件链按注册逆序包裹:后注册的更靠近外层。
- 依赖受路由与参数约束,中间件对所有匹配请求生效。
原理流程
- 注册期把中间件类/函数加入应用中间件栈。
- 请求到达由外到内执行中间件进入逻辑,
call_next进入内层路由。 - 响应生成后由内到外回程,各中间件处理响应。
代码或图示
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com"],
allow_methods=["*"],
)
@app.middleware("http")
async def timing(request: Request, call_next):
response = await call_next(request)
response.headers["X-Process-Time"] = "..."
return response
常见误区
- 中间件注册顺序影响 CORS 等头行为:跨域头必须在最外层能写到响应上,顺序需按中间件栈理解。
- 在中间件进入逻辑里做重计算:所有请求都承担该成本,高频横切逻辑要保持轻量。
追问
- 中间件能按路由跳过吗?答:在中间件内按
request.url.path判断分支,或把细粒度逻辑下沉到依赖。 - 内置中间件列表在哪查?答:Starlette 提供 CORS、GZip、TrustedHost、Session 等,FastAPI 同名导出。
- 中间件异常会被谁捕获?答:异常沿 ASGI 栈上抛,兜底异常处理器统一响应。
04.7.15.1-050 同步路由在依赖链中如何被线程池调度?
一句话结论
def(非 async def)路由与其同步依赖由 FastAPI/AnyIO 丢入线程池执行,事件循环不被阻塞;async def 路由与异步依赖在事件循环内直接调度。框架按函数是否协程函数选择执行容器,同步栈与异步栈可在同一应用混用。
概念解释
- 线程池容量有限,同步阻塞任务过多会排队;线程池是 AnyIO 默认线程池(待确认:验证点:默认线程数与配置项)。
- 同步路由内调用阻塞 IO 占用线程,异步路由内调用阻塞 IO 卡住循环,二者风险面不同。
原理流程
- 注册期判断端点/依赖是否为协程函数。
- 请求期异步可调用直接
await;同步可调用通过线程池运行。 - 线程池结果回传事件循环,继续响应流程。
代码或图示
import requests
@app.get("/sync")
def sync_route():
return requests.get("https://example.com").json() # 线程池
@app.get("/async")
async def async_route():
async with httpx.AsyncClient() as c:
return (await c.get("https://example.com")).json() # 事件循环
常见误区
- 在
async def端点里调用同步阻塞库:事件循环被卡住,所有并发请求排队。 - 以为同步路由自动拥有独立进程:只是线程池线程,受 GIL 与池容量约束。
追问
- 混合路由下线程池耗尽表现?答:同步请求排队延迟上升,异步请求不受直接阻塞但整体吞吐下降。
- 如何把同步调用放进异步端点?答:
asyncio.to_thread或 AnyIO 线程池包装。 - 依赖同步与否影响端点调度吗?答:依赖按自身类型调度,端点按自身类型调度,分别进入对应容器。
04.7.15.1-051 依赖解析在源码哪个阶段完成,签名如何 inspect?
一句话结论
依赖树在路由注册(应用启动)阶段构建:FastAPI 用 inspect.signature 读取端点与依赖的参数注解、默认值,识别 Depends/Security 与参数来源,生成可在请求期执行的解析结构。请求期只执行已构建的依赖树,不再反复分析签名。
概念解释
- 源码侧关键工具位于
fastapi.dependencies.utils:提取类型签名、归类参数、构建依赖子树。 - 启动期分析成本随路由与依赖数量增长,大型应用启动时间需纳入评估。
原理流程
- 路由装饰器被调用时收集端点引用与装饰器参数。
- 框架遍历签名参数,分类为依赖/Path/Query/Header/Cookie/Body。
- 子依赖递归展开,形成请求期可遍历的依赖结构并缓存到路由对象。
代码或图示
import inspect
def sample(a: int, db: Session = Depends(get_db)):
sig = inspect.signature(sample)
for name, param in sig.parameters.items():
print(name, param.annotation, param.default)
常见误区
- 修改依赖函数签名后不重启:启动期缓存的签名不会热更新,需重启进程。
- 依赖使用
*args/**kwargs或动态签名:inspect 无法稳定归类参数,绑定行为不可预期。
追问
- 签名分析失败会在启动时报错吗?答:参数来源无法判定时,注册期或首个请求期抛出明确错误。
- 依赖树缓存在哪个对象上?答:挂在
APIRoute的依赖/参数字段上,随路由表保留。 - 测试中如何替换依赖?答:
app.dependency_overrides[original] = replacement,请求期解析时取用替换项。
04.7.15.1-052 全局依赖对 OpenAPI 鉴权头标注的影响?
一句话结论
全局/路由器依赖若声明了安全方案(如 OAuth2PasswordBearer、APIKeyHeader),其参数会进入对应端点的 OpenAPI security 与参数条目;未做安全声明的普通依赖只参与运行时,不在文档生成鉴权头。敏感内部头不应通过依赖暴露在公开文档中。
概念解释
- OpenAPI 安全方案由安全类依赖的类型与
Securityscopes 推导。 - 文档暴露的头名、查询参数会被前端与第三方看到,需区分公开 API 与内部 API。
原理流程
- 注册期收集路由继承到的全部依赖。
- 识别安全方案类依赖,生成 OpenAPI
securitySchemes与操作级security。 - 普通依赖参数按来源进入文档参数或不展示。
代码或图示
from fastapi.security import APIKeyHeader
api_key = APIKeyHeader(name="X-Internal-Key", auto_error=True)
app = FastAPI(dependencies=[Depends(api_key)])
常见误区
- 内部调试头挂全局依赖后出现在 Swagger:外部可见内部约定,内部服务应关闭公开文档或拆分安全方案。
- 以为全局依赖不影响文档:安全类依赖同样会被 OpenAPI 收集。
追问
- 如何在文档中隐藏某个参数?答:参数声明
include_in_schema=False。 - 安全方案能全局复用吗?答:同一安全类实例被多端点引用,OpenAPI 合并为一个 scheme。
- 关闭文档后依赖还生效吗?答:
docs_url=None只隐藏页面,运行时依赖照常执行。
04.7.15.1-053 include_router 的 default_response_class 与 route_class?
一句话结论
APIRouter 支持 default_response_class 指定默认响应类(如 ORJSONResponse),route_class 自定义路由类以扩展路由行为(如记录耗时、覆写依赖解析)。include_router 可覆盖路由器默认响应类;路由装饰器上的 response_class 优先级最高。
概念解释
default_response_class决定未显式指定响应类时使用的序列化响应类型。route_class继承APIRoute,可在路由层挂钩请求处理与依赖收集,属于高级扩展点。
原理流程
- 路由器创建时记录默认响应类与路由类。
- 每条路由注册时应用路由类构造
APIRoute实例。 - 端点未指定响应类时使用默认响应类序列化返回值。
代码或图示
from fastapi import APIRouter
from fastapi.responses import ORJSONResponse
router = APIRouter(default_response_class=ORJSONResponse)
class TimedRoute(APIRoute):
def get_route_handler(self):
handler = super().get_route_handler()
async def wrapped(request):
return await handler(request)
return wrapped
常见误区
- 自定义
route_class不调用父类方法:破坏依赖解析与响应处理,导致端点行为异常。 - 全局替换响应类后忽略兼容性:自定义响应类需正确处理 JSON 编码、状态码与头。
追问
- 响应类优先级顺序?答:装饰器
response_class> 路由器默认 > 应用默认。 ORJSONResponse收益是什么?答:基于 orjson 的 JSON 序列化,吞吐与内存表现优于标准json。- 路由类能修改依赖列表吗?答:可在构造/处理器层扩展,但需保持 FastAPI 依赖结构完整。
04.7.15.1-054 路由级 dependencies 与端点参数 Depends 的执行顺序?
一句话结论
执行顺序为:全局依赖 → 路由器依赖 → 路由装饰器 dependencies 列表 → 端点函数参数上的 Depends。外层先解析,列表依赖按声明顺序解析,参数依赖在端点调用前注入。列表依赖只跑副作用,参数依赖负责注入对象。
概念解释
- 同层多个依赖按列表顺序解析;子依赖在父依赖之前解析。
- 鉴权类横切逻辑放外层列表依赖,数据对象放参数依赖,职责分层清晰。
原理流程
- 收集路由继承的全部依赖条目,按层级排序。
- 深度优先解析:外层依赖先执行,其结果供内层使用。
- 参数依赖结果注入端点签名,调用端点。
代码或图示
@app.get(
"/items/{id}",
dependencies=[Depends(auth), Depends(perm)],
)
def item(id: int, db: Session = Depends(get_db)):
...
# 顺序:auth → perm → get_db → 端点
常见误区
- 把需要注入值的依赖放进
dependencies列表:列表依赖返回值不进入端点,必须改为参数声明。 - 以为参数依赖先于列表依赖执行:外层列表依赖先解析,可用于提前短路鉴权。
追问
- 外层依赖失败内层还执行吗?答:不执行,异常上抛中断解析。
- 同层依赖能共享结果吗?答:默认
use_cache=True,同一 callable 在请求内共享缓存结果。 - 依赖顺序影响 OpenAPI 吗?答:安全方案与参数条目按解析/声明顺序生成文档。
04.7.15.1-055 网关下 docs/openapi 路径与 root_path 配合?
一句话结论
反向代理把服务挂在子路径下时,浏览器访问的文档 URL 与应用内部路由需要 root_path 对齐:代理剥离前缀转发,应用按内部路径匹配,root_path 告知应用外层前缀,使 Swagger UI 与 openapi.json 链接生成正确。前缀剥离与 root_path 必须两侧一致。
概念解释
- 常见部署:Nginx
/api/→ 应用/;应用root_path="/api"。 - 文档接口本身(
/docs、/openapi.json)也受前缀影响,代理需正确转发。
原理流程
- 代理按 location 剥离外层前缀,转发剩余路径到应用。
- 应用从 ASGI scope 或配置读取
root_path,生成带前缀的文档链接。 - 浏览器请求 Swagger 资源与 openapi 时经代理回到应用。
代码或图示
location /api/ {
proxy_pass http://127.0.0.1:8000/;
}
app = FastAPI(root_path="/api")
常见误区
- 代理不剥离前缀而应用又设
root_path:路径双重前缀,文档与接口 404。 - 只配
root_path不转发/docs与/openapi.json:页面加载但文档接口不可达。
追问
root_path影响业务路由匹配吗?答:不影响匹配,只影响外层基线与文档 URL 生成。- 多版本前缀如何区分?答:每个服务实例按自身外层路径配置,或在网关层统一改写。
- 文档 404 先查什么?答:先核对代理转发规则、
root_path与实际访问前缀是否一致。
04.7.15.1-056 StaticFiles 挂子路径下的相对链接问题?
一句话结论
静态资源挂在子路径(如 /assets/)下时,HTML/CSS/JS 内的资源链接必须使用与挂载点一致的相对或绝对路径。若页面内写死根路径 /static/...,在子路径部署下会 404;多环境部署建议用构建时基线路径或相对路径引用资源。
概念解释
StaticFiles只负责按挂载前缀返回文件,不修改页面内链接。- 前端构建的
base/publicPath需与服务端挂载路径对齐。
原理流程
- 应用
app.mount("/assets", StaticFiles(directory="dist"))。 - 请求
/assets/app.js由静态服务定位dist/app.js返回。 - HTML 内引用若写成
/static/app.js,浏览器向根路径请求,与挂载点不符导致 404。
代码或图示
<!-- 子路径部署下推荐相对路径或按基线拼接 -->
<script src="./app.js"></script>
<link rel="stylesheet" href="./style.css">
常见误区
- 开发环境根路径可用、子路径部署后静态资源全挂:链接写死绝对路径是主因。
- 把 SPA 路由回退交给
StaticFiles:history 模式刷新 404 需 catch-all 端点回退index.html。
追问
- 如何统一多环境基线路径?答:前端构建配置 base 路径,或后端按部署环境注入全局变量。
- 静态文件能加缓存头吗?答:可自定义静态子类或在代理层设置
Cache-Control。 - 目录索引如何返回?答:
html=True时目录请求返回index.html。
04.7.15.1-057 关闭 redirect_slashes 后的行为?
一句话结论
FastAPI(redirect_slashes=False) 关闭斜杠自动重定向:请求路径与路由模板仅尾斜杠不同时不再 307,直接按未匹配处理(404,或方法不符时 405)。API 设计应保证客户端按规范路径请求,不依赖服务端补斜杠。
概念解释
- 默认开启时框架在匹配失败后做一次斜杠重试;关闭后去掉这次重试。
- 对严格路径匹配的内部 API、网关后服务,关闭可避免多余重定向与方法保留问题。
原理流程
- 请求路径进入路由表逐条匹配。
- 关闭重定向后不再尝试加/去尾斜杠二次匹配。
- 无路由命中返回 404/405。
代码或图示
app = FastAPI(redirect_slashes=False)
@app.get("/items/")
def list_items():
...
# GET /items 不再重定向,直接 404
常见误区
- 关闭后客户端仍混用带/不带斜杠的 URL:需在网关或前端统一路径规范。
- 以为关闭重定向影响路径参数转换器:转换器规则不变,只去掉斜杠重试。
追问
- 重定向开关能按路由设置吗?答:作用于应用级,不单条路由配置(待确认:验证点:当前版本是否支持路由级覆盖)。
- 307 关闭后 POST 会被改成 GET 吗?答:根本不再产生重定向,不存在方法改写问题。
- 何时建议关闭?答:对外严格契约 API、网关统一路径规范化之后。
04.7.15.1-058 依赖中读取请求体后再次读取为空的原因?
一句话结论
ASGI 请求体是一次性流式通道:在依赖或中间件里 await request.body()/json() 消费后,receive 通道已无数据,端点或后续依赖再读会得到空体。解决方式是首次读取后把解析结果缓存到 request.state,后续层从 state 取用;或避免在进入端点前读取 body。
概念解释
- Starlette
Request.body()内部会缓存已接收的 body 字节,同一 Request 实例重复调用body()可命中缓存;但跨层包装或直接操作 receive 时缓存不一定生效。 - 表单数据同理,
form()读取后再读会受解析状态影响。
原理流程
- 请求进入依赖,首次读取 body 流并消费消息。
- 解析结果保存到
request.state.parsed_body。 - 端点/后续层从 state 取数据,不再直接读流。
代码或图示
async def read_body(request: Request):
body = await request.body()
request.state.raw_body = body
return body
@app.post("/x")
async def x(request: Request, _: None = Depends(read_body)):
raw = request.state.raw_body # 从缓存取,不再读流
return {"len": len(raw)}
常见误区
- 多层各自
await request.json():第二次解析基于已消费流,得到空或报错。 - 把原始 body 缓存到全局变量:必须挂在
request.state,请求间隔离。
追问
Request自带 body 缓存吗?答:同一实例内body()有缓存机制;跨实例或直接用 receive 需自行保存。- 签名验签需要原始 body 怎么办?答:在依赖内读取原始字节验签,缓存到 state 供端点使用。
- 表单读取后还能读 JSON 吗?答:编码已确定,二者不能在同一请求重复解析。
04.7.15.1-059 请求结束后后台任务、yield 清理、中间件回程的顺序总图?
一句话结论
响应发出后的收尾顺序大致为:端点返回值序列化完成 → 响应体发送 → BackgroundTasks 任务执行 → 各 yield 依赖按解析逆序清理 → 中间件由内到外回程。跨阶段资源释放不要依赖精确先后,关键资源生命周期应由上下文管理器或连接池明确管理。
概念解释
- 后台任务与依赖清理都发生在客户端收到响应之后,不影响响应延迟。
- 异常路径下清理仍需执行,任务异常要内部兜底。
原理流程
- 响应模型序列化并写入 send 通道。
- 框架执行已注册后台任务。
- 恢复各生成器依赖执行清理段。
- 中间件栈回程处理响应与日志。
代码或图示
endpoint return
→ response serialize
→ send response body
→ BackgroundTasks.run()
→ yield deps cleanup (LIFO)
→ middleware outbound
常见误区
- 把必须在响应前完成的收尾写进后台任务/清理段:失败时客户端已收到成功响应,产生不一致。
- 假设清理顺序固定跨版本不变:升级框架版本后应回归验证收尾行为。
追问
- 后台任务失败会影响已发送响应吗?答:响应已发出,任务失败只影响后续动作,需日志告警。
- 多个 yield 依赖清理顺序?答:按解析完成的逆序,类似栈出栈。
- 中间件能感知后台任务结果吗?答:后台任务在内层执行,中间件回程时任务通常已完成,不建议跨层传递任务状态。
04.7.15.1-060 依赖注入与显式传参相比在测试中的取舍?
一句话结论
依赖注入把对象获取与业务逻辑分离,测试时可用 app.dependency_overrides 替换数据库、客户端、鉴权等依赖,无需改动端点代码;显式传参在函数内构造对象则测试需 monkeypatch 全局工厂或暴露构造参数。可测试性是选择 DI 的核心理由之一,但过度依赖注入会增加理解成本。
概念解释
- 替换粒度按依赖 callable 引用匹配,替换项在请求期解析时生效。
- 测试覆盖依赖树时,也要覆盖被替换依赖的子依赖行为。
原理流程
- 生产代码用
Depends(get_db)声明外部对象。 - 测试中
app.dependency_overrides[get_db] = override_db。 - 测试请求经解析取用替换对象,断言业务行为。
代码或图示
def override_db():
yield test_session
app.dependency_overrides[get_db] = override_db
# 测试结束后清理
app.dependency_overrides.clear()
常见误区
- 测试后不清理
dependency_overrides:替换项泄漏到其他测试,造成数据串扰。 - 依赖内直接实例化重资源且无替换入口:测试被迫连真实环境,破坏隔离性。
追问
- 替换依赖需要改端点签名吗?答:不需要,按原始 callable 引用替换即可。
- 类依赖能替换吗?答:可以,按类引用注册 override。
- 除 override 外还有什么测试手段?答:依赖本身写普通函数/类,可直接单测;端点用 TestClient 做集成测试。
本节高频题
- APIRouter 与 app 路由区别(001)
- include_router prefix 拼接(002)
- tags 合并与 OpenAPI 分组(003)
- 路由匹配注册顺序(007)
- redirect_slashes 与 307(008)
- root_path 网关部署(009、055)
- Depends 签名解析与依赖树(016、051)
- use_cache 缓存粒度(017、029)
- yield 依赖清理时机(021、022)
- Security 与 OAuth2PasswordBearer(025、026)
- Annotated 依赖写法演进(028)
- Path/Query/Header/Cookie 取值(031、036)
- Form/File 与 multipart(033、034、040)
- 请求完整生命周期(041)
- 中间件与依赖执行顺序(042、049、054)
- app.state 与 lifespan(046、047)
- 422 校验异常处理(048)
- 同步/异步路由线程池调度(050)
- 请求体一次性读取(058)
- 测试 dependency_overrides(060)