如何在FastAPI请求体模型与依赖项间共享字段且避免重复耦合

问题背景 #

现有FastAPI代码：

from fastapi import FastAPI, Depends, Body
from pydantic import BaseModel
import uvicorn

app = FastAPI()

class BS(BaseModel):
    x: str
    y: str

def dep1(x: str = Body()):
    print(x)
    return x

@app.post("/")
def main(b: BS, d = Depends(dep1)) -> BS:
    print(b)
    print(d)
    return b

uvicorn.run(app, host="0.0.0.0", port=8000)

当前生成的请求JSON Schema要求同时传嵌套的b.x和根级x：

{
  "b": {
    "x": "string"
  },
  "x": "string"
}

需要实现依赖的x与端点请求体的b.x复用同一个根级x，最终请求结构为：

{
"x": "string"
}

限制条件：

• 不能使用原始Request对象（Starlette的stream()存在竞态条件）
• 依赖不能直接使用BS模型（需复用在不同模型的端点，仅x为公共字段）
• 不能新增额外请求体字段

可行方案 #

通过定义公共基础模型实现字段复用，让依赖和业务模型共享同一个字段定义，FastAPI会自动合并请求体Schema，避免重复字段。

代码示例 #

from fastapi import FastAPI, Depends
from pydantic import BaseModel, Optional
import uvicorn

app = FastAPI()

# 公共基础模型：封装所有端点共享的x字段
class CommonX(BaseModel):
    x: str

# 业务返回模型：继承公共模型，添加业务字段y（若y为后端生成，可设为非必填）
class BS(CommonX):
    y: Optional[str] = None

# 复用依赖：基于公共模型获取x，可用于任意需要x字段的端点
def dep1(common: CommonX = Depends()):
    print(common.x)
    return common.x

@app.post("/", response_model=BS)
def main(req: CommonX, d = Depends(dep1)) -> BS:
    print(req)
    print(d)
    # 后端生成y字段（根据业务逻辑调整）
    return BS(x=req.x, y="backend_generated")

uvicorn.run(app, host="0.0.0.0", port=8000)

方案说明 #

1. 公共模型复用：CommonX封装了所有端点共享的x字段，依赖dep1通过注入CommonX获取x，保证依赖可以无缝复用在任意需要x字段的端点，无需绑定特定业务模型。
2. 请求体合并：FastAPI会自动识别CommonX和业务模型的继承关系，合并请求体Schema，仅保留根级的x字段，不会生成重复字段。
3. 灵活适配业务：若业务需要返回包含y的模型，只需让返回模型继承CommonX并添加y字段；若仅需x作为请求参数，直接使用CommonX作为请求体即可。

为什么其他方案不可行 #

• 直接在依赖中使用x: str = Body()：会让FastAPI将x识别为独立的根级字段，与业务模型的嵌套字段共存，导致Schema出现重复x。
• 使用原始Request对象：存在Starlette stream()的竞态条件风险，不符合限制要求。
• 依赖直接绑定BS模型：会导致依赖无法复用在其他业务模型的端点，违背复用需求。

内容的提问来源于stack exchange，提问作者Liner Colt8