PyPika 不校验字段类型，所有字面量须手动包装为 LiteralValue 或 Parameter；标识符须用 Field/Table 构造；逻辑运算符需用 &、|、~；JOIN 后同名字段须显式别名；select(*) 应避免。
PyPika 查询对象不校验字段类型，直接拼 SQL
PyPika 本质是字符串构建器，Query、Field、Table 都不持有类型信息。你传 "user_id" 或 42 给 select()，它照单全收，不会报错，也不会自动转义或加引号——除非你显式调用 cast() 或用 Parameter。
常见错误现象：拼出 SELECT name, 123 FROM users（本意是字符串字面量），或把 datetime 对象直接塞进 where() 导致 SQL 报错 column "2024-01-01" does not exist。
- 所有字面量值（字符串、数字、布尔、
None）必须手动包装为LiteralValue或用Parameter占位 - 日期/时间建议统一用
Parameter，避免时区和格式歧义：Q.where(T.created_at == Parameter("%s")) - 字段名、表名、函数名等标识符，务必用
Field("name")或Table("users")构造，别用裸字符串
想用类型提示？得靠 wrapper 类 + 类型存根
PyPika 原生不支持 typing，Query.select() 返回 Query，没法标注返回字段类型。强行加 -> Query[UserRow] 没用，IDE 不识别，mypy 也不认。
可行做法是写薄层封装：定义一个 TypedQuery 类，内部持有一个 Query 实例，并在 select() 方法里做参数校验 + 返回泛型代理对象。但注意——这不改变生成的 SQL，只帮你提前发现字段名拼错、类型不匹配等问题。
立即学习“Python免费学习笔记（深入）”；
- 字段名校验可基于已知表结构（如从 SQLAlchemy
Table或 Pydantic model 提取字段名列表） - 对
select()中每个参数做isinstance(x, (Field, Function, LiteralValue))判断，非合规项抛TypeError - 类型存根文件（
pypika-stubs/__init__.pyi）可以补全方法签名，但无法推导运行时字段类型
WHERE 条件里混用 Python 运算符容易翻车
==、!=、> 在 PyPika 里被重载为 SQL 比较操作符，但 and/or/not 不行——它们是 Python 关键字，不能重载。直接写 where(T.a == 1 and T.b > 2) 会先算 Python 表达式，结果是 False 或 True，再传给 where()，最终生成无效 SQL。
正确写法只能用 PyPika 提供的逻辑组合器：&（AND）、|（OR）、~（NOT）。
-
T.a == 1 & T.b > 2→ 生成WHERE a = 1 AND b > 2 -
~(T.status == "draft")→ 生成WHERE NOT (status = 'draft') - 括号不能省：
T.a == 1 & T.b > 2 | T.c == "x"优先级混乱，必须写成(T.a == 1 & T.b > 2) | T.c == "x"
JOIN 后字段名冲突时，别依赖自动别名
PyPika 不会自动为 JOIN 后同名字段加表前缀。比如 users JOIN posts ON users.id = posts.user_id，两个表都有 id 字段，select("*") 会生成 SELECT *, *（语法错误），而 select(users.id, posts.id) 会生成 SELECT users.id, posts.id —— 看似 OK，但某些数据库驱动（如 psycopg2）读取结果时可能只暴露最后一个 id 字段。
真正安全的做法是显式指定别名，尤其是涉及聚合或跨表同名字段时。
- 用
users.id.as_("user_id")和posts.id.as_("post_id") - 避免
select("*")，哪怕只是开发阶段；生产查询必须明确列出字段 - 如果用
Query.from_(users).join(posts).on(...)，记得在select()前调用distinct()防止隐式笛卡尔积放大
类型安全不是 PyPika 的设计目标，它只管拼得对不对，不管语义合不合理。真要强类型，得自己套一层约束，或者换用更重的 ORM。但只要守住字段构造、字面量包装、逻辑运算符、别名这四条线，就能避开 90% 的 runtime SQL 错误。
