FastAPI项目结构中大型复杂数据库查询代码的存放位置规范

你参考的官方全栈FastAPI项目本身是按职责做的分层设计，没有强制要求必须单独新建queries文件夹，具体放置方式可以根据查询的复杂度和归属来定，核心是保持现有目录的职责一致性，不要让同类型代码散落在多个位置。

优先适配现有CRUD层的场景 #

官方项目默认的app/crud/目录从来不是只能放简单增删改查，所有和数据读写相关的逻辑本来就归属于这一层：

• 如果复杂查询和单领域模型强绑定，哪怕是多表联查，只要逻辑核心围绕某个主模型，直接放到对应模型的crud文件里即可，比如用户维度的关联查询就写到crud_user.py中，和基础CRUD放在一起，后续维护时找对应模型的数据逻辑不用跨目录。
• 如果是跨多个模型的聚合查询，但整体复杂度不高、复用场景有限，直接在crud目录下新建对应业务域的文件即可，比如统计类查询放crud_stats.py、报表类查询放crud_report.py，不需要额外新建顶层目录，所有数据操作逻辑统一收口在crud目录，对原有项目结构的侵入性最低。

适合单独新建queries目录的场景 #

如果你的项目里复杂查询占比很高，存在大量跨多域联查、窗口函数、原生SQL、CTE递归查询这类和普通单表CRUD复杂度差异极大的逻辑，可以在app根目录下新建queries目录，但必须提前做好明确的边界约定：

• crud目录只保留单表操作、简单两三个表关联的基础读写逻辑
• queries目录专门存放跨域聚合、复杂统计、定制化SQL查询类代码
• 绝对不要两边混放同类型逻辑，不然后续维护时找一段查询要翻好几个目录，反而降低扩展性

通用避坑原则 #

• 不要把复杂查询逻辑直接写在app/api/下的路由文件里，路由层只负责参数校验、请求响应编排、权限校验，所有数据读写逻辑全下沉到数据层，避免后续复用时重复写相同的查询逻辑。
• 不管查询逻辑放在哪个目录，都要保持函数职责单一，统一接收数据库会话作为入参，返回ORM模型或者Pydantic序列化对象，不要在查询函数里掺杂请求解析、响应格式化的非数据层逻辑。
• 重复使用的联表、过滤条件可以抽成公共的查询组件，不要在每个函数里重复拼接相同的SQL片段。

参考目录结构 #

app/
├── api/                # 路由层：请求响应处理、权限校验
├── crud/               # 数据操作层：基础CRUD、归属明确的模型关联查询
│   ├── crud_user.py
│   ├── crud_order.py
│   └── crud_stats.py   # 轻量跨模型聚合查询可放此处
├── queries/            # 可选：复杂查询占比高时新建，存放重度聚合、原生SQL逻辑
│   ├── dashboard_queries.py
│   └── report_sql.py
├── models/             # ORM表模型
├── schemas/            # Pydantic请求/响应模型
└── db/                 # 数据库连接、会话配置

不存在强制的行业统一标准，核心判断依据是：同职责代码就近放置，目录边界约定清晰，不要为了分类而分类破坏原有项目已经跑通的结构约定。

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