应使用 Self 类型提示确保链式调用类型正确，避免硬编码类名；filter 推荐统一用 **kwargs 以支持 IDE 提示；每次调用须返回新实例防止状态污染；build() 仅生成 SQL 和参数，不执行查询，且允许后续链式调用。
为什么直接 return self 会破坏类型提示
很多初学者写链式调用时，在每个方法末尾写 return self，结果发现 IDE（如 PyCharm 或 VS Code + Pylance）无法推导后续方法的补全，甚至报错 Cannot access member "filter" for type "object"。这是因为 Python 的静态类型检查器默认把 self 当作当前类的实例，而链式调用中你可能希望返回的是“同一个构建器实例”，但类型系统并不知道这个实例在调用后仍具备所有方法——尤其当你混用泛型或继承时。
解决的关键不是“让 return self 更聪明”，而是显式告诉类型系统：这个方法返回的是和调用者**同类型**的实例。
- 用
from typing import Self（Python 3.11+），或from __future__ import annotations+Self（3.7+） - 避免返回
QueryBuilder这种硬编码类名，它在子类中会失效 - 如果兼容旧版本 Python，可用
TypeVar('T', bound='QueryBuilder')配合-> T
filter() 和 where() 方法该不该接受字典或可变参数
常见设计分歧：是让 filter(name="Alice", age__gt=30) 还是 filter({"name": "Alice", "age__gt": 30})？前者更 Pythonic，后者更容易从 JSON 或 Web 请求中解包。但两者底层处理逻辑完全不同。
真正影响的是扩展性和错误反馈：
立即学习“Python免费学习笔记（深入）”；
- 关键字参数方式天然支持 IDE 参数名提示，拼错
age_gt会被立即标红 - 字典方式便于动态构造条件（比如从 request.query_params 构建），但字段名拼写错误只能到运行时报错
- 混合支持不推荐：既收
**kwargs又收conditions: dict，会让类型签名混乱，filter({})和filter()行为不一致 - 建议统一用
**kwargs，需要动态传入时用builder.filter(**request_dict)
如何安全地累积查询条件而不污染原始实例
链式调用最怕“意外共享状态”。比如 q1 = builder.filter(age=25); q2 = builder.filter(name="Bob")，结果 q1 里也出现了 name 条件——这说明你在原地修改了内部条件列表，而不是创建新实例。
安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。
必须保证每次调用都返回一个**独立副本**：
- 不要用
self._conditions.append(...)，改用new_builder = self.__class__(**self._init_args)再设置新条件 - 如果条件结构复杂（如嵌套 AND/OR），用
copy.deepcopy(self._tree)不够高效，应设计不可变节点（如AndNode(left, right)） - 对性能敏感场景（如高频构建），可延迟合并：只记录操作栈，
build()时一次性解析，避免中间对象反复拷贝
build() 方法输出 SQL 还是执行查询
严格来说，build() 只应做一件事：生成最终查询结构（SQL 字符串、参数元组、或 ORM 查询对象）。执行（.execute() / .all()）必须是另一个独立动作。
否则会导致三个实际问题：
- 无法复用构建逻辑：你不能把
builder.filter(x).order_by(y).build()传给测试 mock，因为 build 已触发执行 - 事务控制失效：想把多个查询包进一个
with transaction:，但build()自己 commit 了 - 调试困难：SQL 打印不出，因为被封装在执行流程里；想看生成的语句，还得 patch execute
所以标准接口应该是：builder.filter(...).order_by(...).build() → (sql: str, params: tuple)，再由上层决定怎么用。
容易被忽略的一点是：build 后是否允许继续链式调用？答案是**应该允许**——构建器本身是不可变的，build 不改变它，所以 builder.filter(a).build(); builder.filter(b).build() 是合法且高效的。
