链式调用的核心是每个构建方法必须 return self。select()、where() 等方法需追加条件而非覆盖，to_sql() 应返回 SQL 字符串与参数元组，并在校验缺失字段或表时抛出明确异常。
链式调用的核心是 return self
Python 中实现链式调用，关键不是语法糖，而是每个修改状态的方法都必须 return self。如果漏掉这句，调用链会在第一次方法后中断。比如 select() 方法内部改了 self._fields，但没返回 self，后续的 where() 就会报 AttributeError: 'NoneType' object has no attribute 'where'。
常见错误是把「执行查询」和「构建查询」混在一起：比如在 execute() 里直接运行 SQL 并返回结果，那它就无法再链式调用。正确做法是把执行单独剥离，让构建类只负责组装，最后用一个明确的 to_sql() 或 run() 收口。
-
select()、from_()、where()、order_by()这类构建方法，一律return self - 避免在构建方法中做副作用操作（如连接数据库、发 HTTP 请求）
- 如果需要预校验（比如字段名是否合法），放在方法开头，失败时抛异常，而不是静默吞掉或返回新实例
如何安全地累积查询条件（特别是 where）
where() 是最容易出错的地方：用户可能连续调用多次，期望是 AND 合并，但若每次都覆盖 self._where，就会丢掉前面的条件。必须设计成「追加」而非「重置」。
推荐用列表存原始条件片段（如 [("age > ?", 25), ("status = ?", "active")]），而不是拼接字符串。这样既保留参数化能力，又方便后续生成 SQL 和绑定参数。
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 每次
where()调用应向self._where_clauses列表追加元组(sql_snippet, *params) - 不要在
where()内部调用str.format()或%拼接——这会引入 SQL 注入风险 - 如果支持 OR 分组，需额外提供
or_where()或where_group()方法，内部用嵌套结构管理逻辑层级
to_sql() 必须分离 SQL 字符串与参数
最终生成的 SQL 不能把参数硬塞进去，否则失去防注入能力。to_sql() 应返回两个值：sql_string 和 params_tuple，由调用方决定怎么交给数据库驱动（比如传给 cursor.execute(sql, params)）。
示例行为：
builder = QueryBuilder().select("id", "name").from_("users").where("age > ?", 30).where("active = ?", True)
sql, params = builder.to_sql()
# sql → "SELECT id, name FROM users WHERE age > ? AND active = ?"
# params → (30, True)-
to_sql()不应触发实际查询，只做纯字符串组装和参数扁平化 - 字段名、表名若来自用户输入，需白名单校验或用反引号包裹（如
f"`{table}`"），防止关键字冲突 - ORDER BY、GROUP BY 的字段也建议走同套校验，避免传入恶意子查询片段
别忽略空状态和边界情况
刚初始化的实例，to_sql() 调用时若没调过 select() 或 from_()，应该明确报错，而不是吐出语法错误的 SQL。这类检查要放在 to_sql() 开头，而不是等数据库驱动报错——后者错误信息难定位。
- 检查
self._fields是否为空，是则 raiseValueError("Missing SELECT fields") - 检查
self._table是否为 None，是则 raiseValueError("Missing FROM table") - WHERE 条件为空时，
to_sql()不应留着孤立的WHERE关键字 - 如果支持 JOIN，要注意 ON 条件缺失时的默认行为（报错？忽略？）——选报错更安全
链式调用看着流畅，但每一步的隐式状态依赖都很深。最易被忽略的是「中间态合法性」：没人规定用户必须按 select→from→where 顺序调，所以每个构建方法都要能独立容忍不完整状态，而把最终校验压到 to_sql() 这个出口点。
