Litestar中如何复用查询参数类并兼容API文档？

方案一：给数据类字段添加查询参数元数据 #

如果你的查询参数数据类基于dataclasses.dataclass定义，可通过为字段配置metadata标记为查询参数，同时让API文档正确识别每个参数：

from dataclasses import dataclass, field
from litestar.params import Query

# 可复用的查询参数数据类
@dataclass
class UserQuery:
    id: int | None = field(
        default=None,
        metadata={"query": {"description": "筛选用户ID", "required": False}}
    )
    username: str | None = field(
        default=None,
        metadata={"query": {"description": "筛选用户名", "required": False}}
    )
    email: str | None = field(
        default=None,
        metadata={"query": {"description": "筛选邮箱", "required": False}}
    )

在视图函数中直接使用该类作为参数，Litestar会自动将每个字段解析为独立的查询参数，OpenAPI文档也会同步展示所有参数：

from litestar import get

@get("/users")
async def list_users(filters: UserQuery) -> dict:
    # 直接调用filters.id、filters.username等参数进行逻辑处理
    return {"filtered_users": [], "applied_filters": vars(filters)}

方案二：使用Litestar DTO配置查询参数 #

如果查询参数基于Pydantic的BaseModel定义，可通过DTO（数据传输对象）明确指定模型作为查询参数使用，确保API文档生成正确：

from pydantic import BaseModel
from litestar.dto import DTOConfig, PydanticDTO

# 可复用的Pydantic查询模型
class UserQuery(BaseModel):
    id: int | None = None
    username: str | None = None
    email: str | None = None

# 配置DTO为查询参数模式
class UserQueryDTO(PydanticDTO[UserQuery]):
    config = DTOConfig(query=True)

在视图函数中指定dto参数并使用模型：

from litestar import get

@get("/users", dto=UserQueryDTO)
async def list_users(filters: UserQuery) -> dict:
    return {"filtered_users": [], "applied_filters": filters.dict()}

关键注意事项 #

• 所有查询参数字段必须设置默认值或标记为可选类型，因为GET请求的查询参数均为可选
• 使用dataclass时，需通过dataclasses.field配置metadata，不能直接给字段赋值默认值加注解
• 确保Litestar的OpenAPI插件处于启用状态（默认已启用），否则API文档无法展示查询参数

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