FastAPI+SQLAlchemy+Pydantic返回数据ValidationError问题排查

问题根源 #

SQLAlchemy一对多关系返回的specs是InstrumentedList对象，而非Python原生list。Pydantic的list[CpuSpecs]字段无法识别这个自定义集合类型，因此触发type_error.list校验错误。

三种可行解决方案 #

1. 在CRUD层转换为原生list

查询到数据后，直接把InstrumentedList转成Python标准list，再返回给接口：

# crud/cpu.py
def get_cpu(db: Session, cpu_id: int):
    cpu = db.query(Cpus).filter(Cpus.id == cpu_id).first()
    if cpu:
        # 将InstrumentedList转为原生list
        cpu.specs = list(cpu.specs)
    return cpu

这种方式简单直接，无需修改Pydantic模型，适合数据量不大的场景。

2. 给Pydantic模型添加类型兼容并开启smart_union

在Schema中允许specs字段同时接受InstrumentedList和原生list，开启smart_union让Pydantic自动处理类型转换：

# cpu_schemas.py
from pydantic import BaseModel, ConfigDict
from sqlalchemy.ext.associationproxy import InstrumentedList
from cpu_model import CpuSpecs

class CpuSpecsSchema(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    spec_name: str
    spec_value: str

class CpuSchema(BaseModel):
    model_config = ConfigDict(from_attributes=True, smart_union=True)
    id: int
    cpu_name: str
    # 允许两种类型，smart_union会自动转换
    specs: list[CpuSpecsSchema] | InstrumentedList[CpuSpecs]

3. 使用Pydantic字段验证器统一处理

通过自定义验证器，在数据进入Pydantic校验前自动转换InstrumentedList：

# cpu_schemas.py
from pydantic import BaseModel, ConfigDict, field_validator
from sqlalchemy.ext.associationproxy import InstrumentedList
from cpu_model import CpuSpecs

class CpuSpecsSchema(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    spec_name: str
    spec_value: str

class CpuSchema(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    cpu_name: str
    specs: list[CpuSpecsSchema]

    @field_validator('specs', mode='before')
    def convert_instrumented_list(cls, value):
        # 检查是否为InstrumentedList，是则转为原生list
        if isinstance(value, InstrumentedList):
            return list(value)
        return value

这种方式适合全局统一处理多个类似的关联字段，扩展性更强。

内容的提问来源于stack exchange，提问作者Konstantin Schavlev