使用Pydantic 2与FastAPI依赖注入时遇‘Input should be a valid list’错误

核心问题 #

1. Pydantic 2.x验证器使用错误：你在Pydantic 2.5.1中仍使用了旧版的@validator装饰器，该装饰器在Pydantic 2.x中已被弃用，改用@field_validator，旧装饰器会导致字段解析时出现异常行为。
2. 参数来源冲突：接口路径中的role_id参数与UserInput模型中的role_id字段重名，结合旧验证器的问题，触发了列表字段的解析错误。

修正后的代码 #

方案1：替换为Pydantic 2.x的field_validator，拆分参数来源 #

from pydantic import BaseModel, field_validator
from fastapi import HTTPException, APIRouter

approuter = APIRouter()

class UserInput(BaseModel):
    uids: list[str]

    @field_validator('uids')
    def validate_uid_length(cls, v):
        for uid in v:
            if len(uid) != 16:
                raise ValueError("uids must be a list of 16 character strings")
        return v

@approuter.post("/role/add_user/{role_id}")
async def handle_user_ids(role_id: str, data: UserInput):
    # 单独验证路径参数role_id
    if len(role_id) != 16:
        raise HTTPException(status_code=400, detail="role_id must be 16 characters long")
    try:
        return {"message": f"Successfully processed user IDs for role {role_id}"}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

方案2：保留模型内的完整验证，明确参数映射 #

from pydantic import BaseModel, field_validator
from fastapi import Depends, HTTPException, APIRouter, Path
from typing import Annotated

approuter = APIRouter()

class UserInput(BaseModel):
    role_id: str
    uids: list[str]

    @field_validator('role_id')
    def validate_role_id_length(cls, v):
        if len(v) != 16:
            raise ValueError("role_id must be 16 characters long")
        return v

    @field_validator('uids')
    def validate_uid_length(cls, v):
        for uid in v:
            if len(uid) != 16:
                raise ValueError("uids must be a list of 16 character strings")
        return v

@approuter.post("/role/add_user/{role_id}")
async def handle_user_ids(
    role_id: Annotated[str, Path()],
    data: UserInput = Depends()
):
    try:
        # 手动合并路径参数与请求体数据并验证
        validated_data = UserInput(role_id=role_id, **data.dict())
        return {"message": f"Successfully processed user IDs for role {validated_data.role_id}"}
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

关键说明 #

• 直接声明data: UserInput时，FastAPI仅从请求体解析数据；使用data: UserInput = Depends()时，会从**所有参数来源（路径、查询、请求体）**收集数据，极易引发参数冲突。
• Pydantic 2.x中@validator仅作向后兼容，官方强烈推荐@field_validator，其对列表等复杂类型的验证逻辑更稳定。

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