如何在FastAPI中以Query参数形式传递列表的列表？

要实现接收可选的、内部列表固定为2个字符串的嵌套列表Query参数，FastAPI原生对嵌套列表的Query解析支持有限，但可以通过两种实用方式实现：

方法一：自定义依赖项+Pydantic验证（推荐，传参更友好） #

这种方式允许用户通过逗号分隔的字符串传递内部列表，再通过依赖项解析并验证格式，传参简洁直观。

步骤1：定义Pydantic验证模型 #

用conlist约束内部列表必须包含恰好2个字符串：

from pydantic import BaseModel, conlist
from typing import Optional, List
from fastapi import FastAPI, Query, Depends

app = FastAPI()

# 验证内部列表必须是2个字符串
class SectionPair(BaseModel):
    __root__: conlist(str, min_length=2, max_length=2)

步骤2：创建解析依赖项 #

负责将Query参数解析为嵌套列表，并触发格式验证：

def parse_sections(
    sections: Optional[List[str]] = Query(None, description="格式示例：sections_to_consider=string1,string2&sections_to_consider=string3,string4")
) -> Optional[List[List[str]]]:
    if not sections:
        return None
    
    # 将每个逗号分隔的字符串拆分为子列表
    parsed_sections = [item.split(",") for item in sections]
    
    # 用Pydantic验证每个子列表的格式
    for pair in parsed_sections:
        SectionPair(__root__=pair)
    
    return parsed_sections

步骤3：在接口中使用依赖项 #

@app.get("/process-sections")
async def process_sections(
    sections_to_consider: Optional[List[List[str]]] = Depends(parse_sections)
):
    return {"received_sections": sections_to_consider}

调用示例

请求URL：

/process-sections?sections_to_consider=string,string2&sections_to_consider=string3,string4

返回结果：

{
  "received_sections": [
    ["string", "string2"],
    ["string3", "string4"]
  ]
}

若传递不符合格式的参数（如sections_to_consider=single-string），会自动返回422验证错误。

方法二：直接使用Pydantic嵌套约束（原生Query格式） #

这种方式利用Pydantic的嵌套类型约束，无需额外解析逻辑，但传参需遵循FastAPI对嵌套列表的Query参数格式，相对繁琐。

from pydantic import conlist
from typing import Optional, List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/process-sections")
async def process_sections(
    sections_to_consider: Optional[List[conlist(str, min_length=2, max_length=2)]] = Query(None)
):
    return {"received_sections": sections_to_consider}

调用示例

请求URL需按索引传递每个元素：

/process-sections?sections_to_consider[0][0]=string&sections_to_consider[0][1]=string2&sections_to_consider[1][0]=string3&sections_to_consider[1][1]=string4

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