FastAPI查询参数的Depends依赖被忽略问题排查

你的代码存在两个核心问题，导致UUID验证依赖被忽略：

1. 类型不匹配导致依赖无法触发
   你在in_ids的类型注解中声明为list[str] | None，但依赖parse_uuids的参数却是str类型。FastAPI会优先按照Query指定的类型解析参数，将传入的id参数解析为list[str]，而依赖期望接收str，类型不匹配时FastAPI会直接跳过依赖执行，自然不会触发验证逻辑。

2. 空输入的解析逻辑漏洞
   当你传入GET /activities?id=时，空字符串会被Query（类型为list[str]）解析为包含空字符串的列表[""]，但你的依赖只处理str类型的输入，根本不会接收到这个值，验证逻辑完全没机会执行。

方案一：让依赖接收列表类型参数 #

调整依赖的参数类型与Query解析结果一致，同时处理空元素的情况：

from uuid import UUID
from fastapi import Depends, HTTPException, Query, Annotated
from typing import Any, List

async def parse_uuids(uuids: List[str]) -> List[UUID]:
    result = []
    for uuid_str in uuids:
        if not uuid_str.strip():
            raise HTTPException(status_code=400, detail="Invalid UUID format: empty string not allowed")
        try:
            result.append(UUID(uuid_str.strip()))
        except ValueError:
            raise HTTPException(status_code=400, detail=f"Invalid UUID format: {uuid_str}")
    return result

@list_router.get(path="/activities", response_model=ActivitySchema)
async def get_activities(
    in_ids: Annotated[
        List[str] | None,
        Query(
            alias="id",
            description='Must be UUID or comma separated UUIDs',
            explode=False  # 自动将逗号分隔的字符串拆分为列表
        ),
        Depends(parse_uuids)
    ] = None
) -> Any:
    pass

方案二：保持依赖接收字符串类型 #

调整Query的类型为str | None，让依赖直接处理原始字符串：

from uuid import UUID
from fastapi import Depends, HTTPException, Query, Annotated
from typing import Any, Optional

async def parse_uuids(uuids: Optional[str]) -> List[UUID]:
    if not uuids or not uuids.strip():
        raise HTTPException(status_code=400, detail="UUID parameter cannot be empty")
    try:
        return [UUID(uuids.strip())]
    except ValueError:
        try:
            return [UUID(u.strip()) for u in uuids.split(",") if u.strip()]
        except ValueError:
            raise HTTPException(status_code=400, detail="Invalid UUID format")

@list_router.get(path="/activities", response_model=ActivitySchema)
async def get_activities(
    in_ids: Annotated[
        Optional[str],
        Query(
            alias="id",
            description='Must be UUID or comma separated UUIDs'
        ),
        Depends(parse_uuids)
    ] = None
) -> Any:
    pass

• 必须保证依赖的参数类型与Query注解的类型完全匹配，FastAPI才会正确传递参数并执行依赖验证。
• 主动处理空输入或空元素的情况，避免绕过验证逻辑。
• 使用explode=False可以让FastAPI自动将逗号分隔的字符串解析为列表，简化多UUID的处理流程。

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