FastAPI中如何正确定义嵌套结构的Pydantic响应模型？

AI 小北

2026-8-6

解决方案

你的问题在于当前定义的响应模型和实际返回的结构不匹配：实际响应是单个对象，包含name字符串和value字符串数组，而非ACL对象的列表。

正确的模型定义

你需要定义一个匹配响应结构的顶层Pydantic模型，把嵌套的value数组字段包含进去：

from fastapi import FastAPI, Depends, HTTPBasic, HTTPBasicCredentials
from pydantic import BaseModel
from typing import List, Literal

security = HTTPBasic()
app = FastAPI()

# 定义匹配响应结构的模型
class ACLResponse(BaseModel):
    # 如果name必须固定为"always the same"，可以用Literal做强制验证
    name: Literal["always the same"]
    value: List[str]

@app.post(
    "/get/acls",  # 注意路径开头要加/，FastAPI要求路径必须以/开头
    response_model=ACLResponse
)
def get_acls(credentials: HTTPBasicCredentials = Depends(security)):
    # 示例返回，会被response_model自动验证
    return {
        "name": "always the same",
        "value": ["ACL1", "ACL2", "ACL3"]
    }

关键说明

路径修正：原路由路径"get/acls"缺少开头的/，FastAPI要求路径必须以/开头，否则会触发路由匹配错误。
模型匹配：ACLResponse完全对应你给出的JSON结构，指定response_model=ACLResponse后，FastAPI会自动验证返回值的结构和类型，不符合规则时会返回422错误。
固定值验证：使用Literal["always the same"]可以强制name字段必须是指定的固定字符串，若不需要该强制验证，将其改为普通str类型即可。
OpenAPI文档：这样定义后，Swagger UI（/docs）和ReDoc（/redoc）会正确展示响应的嵌套结构，包括name字段和value字符串数组的详细定义。