FastAPI dataclass作为Query依赖时alias别名不生效问题

这是pydantic.dataclasses.dataclass和FastAPI依赖解析逻辑不兼容导致的：

• 你代码里用的@dataclass装饰器是从pydantic.dataclasses导入的，这类dataclass在构造类结构时，会把字段上赋值的Query(None, alias="q")直接当成普通字段默认值处理，不会保留它作为FastAPI查询参数的元信息（包括你配置的别名、参数校验规则等）。
• FastAPI执行Depends(Catz)解析依赖时，根本读不到qqq字段配置了别名q，甚至不会把这个字段识别为需要从URL查询参数提取值的字段。无论你传qqq=H还是q=H，最终实例化出来的query.qqq永远是默认值None，触发你代码里的空值判断被赋值为空字符串，自然就出现参数完全不生效、返回全量结果的问题。
• 没配别名的Cats接口能正常跑只是巧合：FastAPI解析Pydantic dataclass类型的依赖时，会默认按字段名去匹配同名查询参数，刚好字段名qqq和你传的参数名一致，所以能拿到传入值——本质上它根本没读取到你写的Query(None)配置。

三选一即可，第一种改动最小：

• 替换为Python标准库的dataclass：把导入语句从from pydantic.dataclasses import dataclass改成from dataclasses import dataclass。标准库dataclass不会篡改字段上携带的Query元信息，FastAPI可以正常识别别名配置，改完之后访问/productz/?q=H就能正确返回过滤后的HDD结果。

  # 只需要修改导入行，其余代码不用动
  from dataclasses import dataclass
  

• 换用Pydantic BaseModel定义查询参数结构，FastAPI对BaseModel的参数元数据识别是原生支持的，同样可以正常读取alias配置。
• 如果必须使用Pydantic dataclass，就不要在字段上直接声明Query，单独编写依赖函数手动完成参数提取和别名映射即可。

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