罗罗编程学习记录
本页内容 展开查看

04.7.15.1 路由依赖注入与请求生命周期

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架

覆盖范围

  • APIRouter 与 include_router 的 prefix/tags/dependencies/responses
  • Depends 依赖解析、use_cache 缓存、yield 依赖的执行与清理时机
  • Annotated 写法演进、类依赖、Security、子依赖链与全局 app.dependencies
  • Path/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 最终调用同一套路由注册逻辑。
  • 路由器是“未挂载的路由集合”,挂载前不参与匹配;挂载后其路由才进入应用路由表。

原理流程

  1. 用 APIRouter() 创建路由器,在其上用装饰器声明端点。
  2. 在主应用中 app.include_router(router) 把路由并入应用。
  3. 注册时路由器上的 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)。

原理流程

  1. 挂载时读取 include_router 的 prefix,默认空字符串。
  2. 遍历路由器内每条路由,把前缀拼到路由 path 前。
  3. 对拼接结果做斜杠规整,生成最终 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 中会出现在多个分组下。

原理流程

  1. 路由器创建时记录 tags,装饰器上再记录路由级 tags。
  2. include_router 合并两层 tags 到每条 APIRoute.tags。
  3. 生成 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)。

原理流程

  1. 挂载时把 include_router 的 dependencies 附加到路由器所有路由。
  2. 路由注册时把装饰器 dependencies 合并到该条路由。
  3. 请求到达后按“全局 → 路由器 → 路由 → 端点参数”的顺序解析依赖树。

代码或图示

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 模型。

原理流程

  1. 在路由装饰器或 include_router 上声明 responses={404: {"model": NotFound, "description": "未找到"}}。
  2. 生成 OpenAPI 时把这些条目合并进该操作的 responses。
  3. 运行时框架不据此做响应校验,真实响应仍由端点返回值决定。

代码或图示

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,逐层合并。

原理流程

  1. 内层路由器先注册自己的路由与子路由器。
  2. 外层 include_router(inner, prefix="/v1") 把前缀拼到内层所有路径前。
  3. 主应用再挂载外层路由器,前缀再次叠加。

代码或图示

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})只约束该段格式,不改变“先注册先匹配”的总规则。

原理流程

  1. 应用启动时把所有 APIRoute 按注册顺序存入 app.routes。
  2. 请求到达后遍历路由表,逐条用路径模式与方法匹配。
  3. 第一条同时匹配路径与 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。

原理流程

  1. 按原始路径遍历路由表,未命中。
  2. 若开启 redirect_slashes,尝试去掉/补上末尾斜杠再匹配一次。
  3. 二次命中则返回 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 子路径、网关统一前缀部署。

原理流程

  1. 代理按规则剥离外层前缀后把请求转给应用,scope["root_path"] 由服务器或配置注入。
  2. 应用路由按 scope["path"](剥离后的路径)匹配。
  3. 生成 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 更直接、性能更好。

原理流程

  1. 路由表中 Mount 条目按前缀匹配,命中后剥离前缀,把 scope 交给子应用。
  2. StaticFiles 在文件系统内定位文件并流式返回。
  3. 未命中文件由 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 内部规范化拦截,正常用法下不能通过 .. 访问根目录外文件。

原理流程

  1. 挂载时记录 directory、html、check_dir。
  2. 请求路径规范化后拼接进 directory,判定是否落在根目录内。
  3. 文件存在则按扩展名返回 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 是“贪婪剩余段”,必须放在路径末尾,否则会吞掉后续字面段。

原理流程

  1. 路由注册时把路径模板编译为匹配规则,转换器对应段模式。
  2. 请求路径按段匹配,int 段要求全数字,path 段吸收剩余斜杠。
  3. 匹配成功后把段值交给参数绑定层,按类型注解转换校验。

代码或图示

@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 在同一应用内应唯一,否则反查命中不确定。

原理流程

  1. 注册路由时记录 route.name(默认取端点函数名)。
  2. 调用 url_path_for 按 name 找到路由模板。
  3. 用传入的关键字参数填充模板中的路径段,返回生成的路径。

代码或图示

@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、审计日志、全局鉴权。
  • 路由器/路由级依赖做模块内分组鉴权;参数依赖负责向端点注入具体对象。

原理流程

  1. 请求匹配到路由后,收集该路由继承到的全部依赖(全局、路由器、路由、参数)。
  2. 按层级与顺序构建依赖树,从外层开始递归解析。
  3. 某层抛异常则中断解析,异常向上交给异常处理器。

代码或图示

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 方法区分。

原理流程

  1. 启动时各路由器按 include_router 顺序把路由追加进 app.routes。
  2. 请求遍历表,路径模式与方法同时匹配才选中。
  3. 发现某端点 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 生成,请求期做实际调用与注入。
  • 依赖本身的参数也会被同样分析,因此天然形成可递归的依赖树。

原理流程

  1. 注册路由时,FastAPI 调用 get_typed_signature 提取端点与依赖的参数注解与默认值。
  2. 对每个参数判断类型:Depends/Security 继续展开为子依赖,其余按参数来源(Path/Query/Body 等)绑定。
  3. 请求到达后按依赖树深度优先解析,叶子先执行,结果注入上层参数。

代码或图示

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 之间不共享。

原理流程

  1. 请求开始时创建本次请求的依赖结果缓存(dict)。
  2. 解析到某依赖时先查缓存:命中直接取,未命中执行并写入缓存。
  3. 请求结束缓存随上下文销毁,下一个请求重新解析。

代码或图示

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 关闭请求内缓存,每次引用该依赖都重新执行并生成新实例。适用于依赖必须每次独立、不能共享可变状态的场景;代价是重复解析与资源获取开销,高频端点需评估。

概念解释

  • 与默认缓存相反:关闭后同一请求内两个参数引用同一依赖,得到两个独立实例。
  • 常见于需要独立事务、独立临时资源或每次读取最新值的依赖。

原理流程

  1. 解析依赖时跳过缓存查询,直接执行 callable。
  2. 每次引用都生成新结果,不写入共享缓存。
  3. 带 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 等声明,形成对象内的子依赖。
  • 实例方法可在端点内调用,把数据访问逻辑收敛到依赖对象内。

原理流程

  1. 注册期读取类 __init__ 签名,归类各参数来源。
  2. 请求期先解析 __init__ 所需子依赖,再调用类构造器生成实例。
  3. 实例作为参数值注入端点,端点调用其方法完成业务。

代码或图示

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 缓存,子依赖被多个上层引用时在同请求内共享。

概念解释

  • 依赖链是树不是链:一个依赖可被多个父依赖引用,子依赖结果被复用。
  • 层级越深,启动期签名分析与请求期解析成本越高,应控制依赖层数。

原理流程

  1. 端点参数依赖进入解析队列,读取其签名中的子依赖。
  2. 递归解析子依赖直至叶子(无可再展开的 Depends)。
  3. 叶子结果回注上层,逐层构造;每层结果写入各自请求缓存。

代码或图示

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 依赖适合管理数据库会话、连接、临时文件等请求级资源。

概念解释

  • 机制类似上下文管理器:进入时获取资源,退出时释放,由框架在请求生命周期内驱动。
  • 清理在响应序列化之后、请求完全结束之前运行,因此不能再向响应写入内容。

原理流程

  1. 解析到生成器依赖后,框架迭代执行到第一个 yield,把产出值注入上层。
  2. 端点执行、响应序列化与发送完成。
  3. 框架恢复生成器执行 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 包裹端点调用。
  • 清理段不应依赖端点业务状态,避免因异常路径下状态不完整而出错。

原理流程

  1. 端点执行中抛出异常,异常沿调用栈向上传播。
  2. 框架在收尾阶段恢复各 yield 依赖生成器,触发 finally/清理段。
  3. 清理完成后原始异常交给 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,否则卡住事件循环。

原理流程

  1. 注册期识别依赖函数是否为协程函数。
  2. 请求期异步依赖直接 await 解析与收尾;同步依赖丢入线程池执行。
  3. 资源清理段按对应容器恢复生成器执行。

代码或图示

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,生产代码优先使用命名函数。

概念解释

  • 框架对可调用对象统一走签名分析,不区分函数还是实例方法。
  • 可调用实例适合携带配置状态,例如初始化时注入阈值、客户端等。

原理流程

  1. Depends 保存可调用引用与 use_cache 等参数。
  2. 解析期读取该可调用对象签名并构建子依赖树。
  3. 请求期调用可调用对象取得结果并注入。

代码或图示

# 命名函数(推荐)
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 传播。

原理流程

  1. 端点参数用 Security(oauth2_scheme, scopes=[...]) 声明。
  2. 注册期把 scopes 写入该操作的安全要求,生成 OpenAPI security 条目。
  3. 请求期执行安全依赖,校验令牌与 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,由依赖自行处理可选认证。

原理流程

  1. 请求到达,框架执行安全依赖实例。
  2. 读取 Authorization 头,按 Bearer 前缀拆分出令牌。
  3. 头缺失/格式不符时按 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 实例、服务对象)直接注入,不需要模型转换。

原理流程

  1. 依赖 callable 返回结果对象。
  2. 框架按端点签名参数名把结果放入调用参数。
  3. 调用端点函数,注解仅作为类型提示与文档依据。

代码或图示

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 风格可读性更好。

原理流程

  1. 框架读取参数注解:若是 Annotated 类型,从中提取 Depends/Query 等元数据。
  2. 若无 Annotated,则从参数默认值读取依赖声明。
  3. 两种来源合并后构建同一依赖树。

代码或图示

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 即使逻辑相近也分别缓存,不按返回值内容去重。

原理流程

  1. 子依赖首次被解析时结果写入请求缓存。
  2. 另一父依赖解析到同一 callable 时命中缓存。
  3. 两个父依赖收到同一对象引用。

代码或图示

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 封装 ASGI scope/receive,提供 headers、query_params、cookies、json() 等接口。
  • 注入的 Response 是端点最终响应的载体,依赖内设置的头会保留到响应。

原理流程

  1. 依赖签名中出现 Request 类型注解,框架识别为请求对象注入。
  2. 出现 Response 类型注解时注入响应对象引用。
  3. 依赖内读取请求信息或写入响应头/ 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 可缺失,由默认值或可选注解处理。

原理流程

  1. 注册期按参数声明(Path/Query/Header/Cookie)归类来源。
  2. 请求期从对应位置读取原始字符串。
  3. 按类型注解做转换与约束校验,失败收集为 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 结构。

原理流程

  1. 注册期统计端点 Body 参数数量与模型。
  2. 单模型:请求体直接解析为该模型;多模型:按参数名构造外层 dict 分别解析。
  3. 解析失败在对应字段位置收集 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,进入生产镜像时一并安装。

原理流程

  1. 注册期检测到 Form/File 参数,标记端点需要表单解析。
  2. 请求到达后框架调用 multipart 解析器读取表单字段与文件流。
  3. 字段绑定为普通值,文件绑定为 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 模式一次性载入内存,文件大时直接抬高内存峰值。

原理流程

  1. multipart 解析器识别文件部分。
  2. 注解 UploadFile:包装为上传文件对象,元数据与句柄随对象暴露。
  3. 注解 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 响应。

原理流程

  1. 注册期把约束收集到参数 Schema。
  2. 请求期取值后按约束逐项校验。
  3. 全部通过才注入端点;任一失败收集错误并返回 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,错误体含字段级详情。

一句话结论

Header 参数名默认把 Python 下划线 _ 转为 HTTP 中划线 -(如 x_token 对应 X-Token);可用 alias 指定真实头名覆盖。Cookie 名区分大小写,直接按声明名从 request.cookies 读取,不做下划线转换。

概念解释

  • HTTP 头惯例使用中划线,Python 标识符只能用下划线,框架做名称映射以符合两侧惯例。
  • 若真实头名本身含下划线,需用 alias 显式声明避免被转换。

原理流程

  1. 注册期记录参数名与是否设置 alias。
  2. 未设 alias 时把下划线替换为中划线作为头名查找。
  3. 命中后按类型注解转换注入。

代码或图示

@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 的第二个及以后参数存放。
  • 别名复用可统一全局约束,例如分页大小、搜索串长度。

原理流程

  1. 框架提取参数注解中的 Annotated 元数据。
  2. 与默认值中的声明合并去重。
  3. 生成参数 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 按标准格式校验。
  • 枚举参数限定在枚举成员范围内,序列化时取成员值。

原理流程

  1. 从查询串/路径段取出原始字符串或字符串列表。
  2. Pydantic 按注解类型做转换与约束校验。
  3. 成功注入枚举/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(原始输入)。
  • 嵌套模型与列表元素各自独立校验,错误位置链保持完整。

原理流程

  1. 请求体解析为外层模型,逐层递归校验嵌套字段。
  2. 某字段失败时把路径追加到错误 loc。
  3. 全部错误收集后由 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 不能并列。

原理流程

  1. 注册期扫描参数来源,判定端点编码类型。
  2. 请求按声明编码读取对应部分。
  3. 编码与实际 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 路由系统之上。
  • 各阶段失败都会被对应异常处理器捕获,转换为错误响应。

原理流程

  1. 服务器接收请求,构造 scope(路径、方法、头、客户端)与收发通道。
  2. 穿过应用注册的中间件,进入路由器匹配路由。
  3. 解析 Query/Path/Header/Cookie/Body 与依赖树,注入端点参数。
  4. 执行端点,拿到返回值;有响应模型则裁剪校验并序列化。
  5. 响应发出后收尾:后台任务执行、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。
  • 依赖与具体路由/参数绑定,适合鉴权、会话、资源获取。

原理流程

  1. 请求进入中间件栈,由外到内依次执行进入逻辑。
  2. 到达路由器匹配端点,解析依赖树。
  3. 端点执行完返回响应,依赖清理收尾。
  4. 响应沿中间件栈由内到外回程处理。

代码或图示

@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 是请求级临时存储,供中间件与依赖之间传递数据。

原理流程

  1. ASGI 服务器把 scope/receive 交给应用。
  2. 框架构造 Request(scope, receive),把原始 dict/通道包装成属性与方法。
  3. 业务代码通过 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 对象直接外泄。

原理流程

  1. 端点返回值传入响应处理流程。
  2. 若为 Response 子类实例:直接作为最终响应。
  3. 否则按 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 实现为准,复杂资源释放不要依赖跨阶段顺序)。

概念解释

  • 后台任务适合发邮件、写日志、触发非关键通知;不能放失败会影响主响应结论的逻辑。
  • 任务在请求上下文内运行,异常需自行捕获,避免拖垮收尾流程。

原理流程

  1. 端点把 BackgroundTasks 注入参数,通过 add_task 注册可调用对象与参数。
  2. 响应主体发出后,框架依次执行已注册任务。
  3. 依赖生成器在收尾阶段被恢复执行清理段。

代码或图示

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,不是分布式共享存储,跨进程状态需用外部缓存/数据库。

原理流程

  1. 应用启动时在 lifespan 或模块加载期初始化共享对象,挂到 app.state。
  2. 请求内通过 request.app.state 读取共享对象。
  3. 请求结束不清理 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。

原理流程

  1. 定义 async def lifespan(app):,yield 前为启动逻辑。
  2. FastAPI(lifespan=lifespan) 注册处理器。
  3. 服务器启动执行 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 校验错误列表。

原理流程

  1. 业务代码 raise HTTPException(status_code=404, detail="未找到")。
  2. 框架异常中间件匹配处理器,生成对应 JSON 响应。
  3. 校验阶段收集到错误后抛 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 等)。中间件在最外层包裹请求,先于依赖解析进入,晚于依赖清理退出。

概念解释

  • 中间件链按注册逆序包裹:后注册的更靠近外层。
  • 依赖受路由与参数约束,中间件对所有匹配请求生效。

原理流程

  1. 注册期把中间件类/函数加入应用中间件栈。
  2. 请求到达由外到内执行中间件进入逻辑,call_next 进入内层路由。
  3. 响应生成后由内到外回程,各中间件处理响应。

代码或图示

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 卡住循环,二者风险面不同。

原理流程

  1. 注册期判断端点/依赖是否为协程函数。
  2. 请求期异步可调用直接 await;同步可调用通过线程池运行。
  3. 线程池结果回传事件循环,继续响应流程。

代码或图示

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:提取类型签名、归类参数、构建依赖子树。
  • 启动期分析成本随路由与依赖数量增长,大型应用启动时间需纳入评估。

原理流程

  1. 路由装饰器被调用时收集端点引用与装饰器参数。
  2. 框架遍历签名参数,分类为依赖/Path/Query/Header/Cookie/Body。
  3. 子依赖递归展开,形成请求期可遍历的依赖结构并缓存到路由对象。

代码或图示

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 安全方案由安全类依赖的类型与 Security scopes 推导。
  • 文档暴露的头名、查询参数会被前端与第三方看到,需区分公开 API 与内部 API。

原理流程

  1. 注册期收集路由继承到的全部依赖。
  2. 识别安全方案类依赖,生成 OpenAPI securitySchemes 与操作级 security。
  3. 普通依赖参数按来源进入文档参数或不展示。

代码或图示

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,可在路由层挂钩请求处理与依赖收集,属于高级扩展点。

原理流程

  1. 路由器创建时记录默认响应类与路由类。
  2. 每条路由注册时应用路由类构造 APIRoute 实例。
  3. 端点未指定响应类时使用默认响应类序列化返回值。

代码或图示

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。外层先解析,列表依赖按声明顺序解析,参数依赖在端点调用前注入。列表依赖只跑副作用,参数依赖负责注入对象。

概念解释

  • 同层多个依赖按列表顺序解析;子依赖在父依赖之前解析。
  • 鉴权类横切逻辑放外层列表依赖,数据对象放参数依赖,职责分层清晰。

原理流程

  1. 收集路由继承的全部依赖条目,按层级排序。
  2. 深度优先解析:外层依赖先执行,其结果供内层使用。
  3. 参数依赖结果注入端点签名,调用端点。

代码或图示

@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)也受前缀影响,代理需正确转发。

原理流程

  1. 代理按 location 剥离外层前缀,转发剩余路径到应用。
  2. 应用从 ASGI scope 或配置读取 root_path,生成带前缀的文档链接。
  3. 浏览器请求 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 需与服务端挂载路径对齐。

原理流程

  1. 应用 app.mount("/assets", StaticFiles(directory="dist"))。
  2. 请求 /assets/app.js 由静态服务定位 dist/app.js 返回。
  3. 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、网关后服务,关闭可避免多余重定向与方法保留问题。

原理流程

  1. 请求路径进入路由表逐条匹配。
  2. 关闭重定向后不再尝试加/去尾斜杠二次匹配。
  3. 无路由命中返回 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() 读取后再读会受解析状态影响。

原理流程

  1. 请求进入依赖,首次读取 body 流并消费消息。
  2. 解析结果保存到 request.state.parsed_body。
  3. 端点/后续层从 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 依赖按解析逆序清理 → 中间件由内到外回程。跨阶段资源释放不要依赖精确先后,关键资源生命周期应由上下文管理器或连接池明确管理。

概念解释

  • 后台任务与依赖清理都发生在客户端收到响应之后,不影响响应延迟。
  • 异常路径下清理仍需执行,任务异常要内部兜底。

原理流程

  1. 响应模型序列化并写入 send 通道。
  2. 框架执行已注册后台任务。
  3. 恢复各生成器依赖执行清理段。
  4. 中间件栈回程处理响应与日志。

代码或图示

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 引用匹配,替换项在请求期解析时生效。
  • 测试覆盖依赖树时,也要覆盖被替换依赖的子依赖行为。

原理流程

  1. 生产代码用 Depends(get_db) 声明外部对象。
  2. 测试中 app.dependency_overrides[get_db] = override_db。
  3. 测试请求经解析取用替换对象,断言业务行为。

代码或图示

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)