sqlalchemy-code-review

SQLAlchemy 代码审查

快速参考

问题类型	参考资料
Session 生命周期、上下文管理器、异步 Session	references/sessions.md
relationship()、延迟加载、N+1、joinedload	references/relationships.md
select() 与 query()、ORM 开销、批量操作	references/queries.md
Alembic 模式、可逆迁移、数据迁移	references/migrations.md

审查清单

• Session 使用上下文管理器（with、async with）
• 不跨请求或线程共享 Session
• 正确关闭／清理 Session
• relationship() 使用恰当的 lazy 策略
• 显式使用 joinedload／selectinload 以避免 N+1
• 不在循环中进行延迟加载（N+1 查询）
• 使用 SQLAlchemy 2.0 select() 语法，而非旧版 query()
• 批量操作使用 bulk_insert/bulk_update，而非 ORM 循环
• 异步 Session 使用恰当的异步上下文管理器
• 迁移可通过 downgrade() 回滚
• 数据迁移使用 op.execute()，而非 ORM 模型
• 正确排列迁移依赖项

检查关卡（SQLAlchemy 专用）

每发现一项与 SQLAlchemy 相关的问题，都要运行一次。在能够定位到 file:line（参见 review-verification-protocol）后、问题发布前运行。如果某步骤未满足通过条件，不要按当前表述断言该问题——应收集证据、撤回、降低严重程度或改写为问题。

关卡 1 — Session 作用域与生命周期

步骤	操作	通过条件
1a	打开创建或注入 Session 的模块（不要凭记忆判断）。	为 Session、sessionmaker、async_session 或返回 Session 的工厂／Depends() 提供 file:line。
1b	如果声称存在泄漏、跨请求共享或缺少清理：追踪 Session 的作用域（上下文管理器、try／finally、中间件）。	引用带有 file:line 范围的作用域代码段；如果查看后确认作用域正确，则撤回。

关卡 2 — N+1、延迟加载、预加载

步骤	操作	通过条件
2a	找到循环或重复调用位置（ORM 属性访问、循环中的 execute）。	为循环或热点路径提供 file:line。
2b	如果声称存在 N+1：指出每次迭代都会执行的关联关系或查询模式。	提供带 file:line 的关联关系或每次迭代执行的 SQL 模式；如果不明确，则改写为问题。

关卡 3 — 迁移（Alembic）

步骤	操作	通过条件
3a	打开修订文件（例如 versions/ 下的文件，或项目的 Alembic 布局中的文件）。	提供相对于仓库的路径以及 revision／upgrade／downgrade 的 file:line。
3b	如果声称 downgrade() 有问题或数据迁移存在风险：指出涉及的 op.*／op.execute()。	为该文件中每个声称有问题的操作提供代码片段或行范围，否则撤回。

何时加载参考资料

• 审查 Session 的创建／清理 → sessions.md
• 审查模型关联关系 → relationships.md
• 审查数据库查询 → queries.md
• 审查 Alembic 迁移文件 → migrations.md

审查问题

1. 是否使用上下文管理器正确管理所有 Session？
2. 是否正确配置关联关系以避免 N+1 查询？
3. 查询是否使用 SQLAlchemy 2.0 select() 语法？
4. 所有迁移是否都可回滚并经过适当测试？