Ubiquity ORM 初始化必须在 Router::start() 之前完成，否则模型无法识别表结构或报 Undefined property 错误；缓存键需手动含条件签名，失效须配合模型事件手动清除；PHP 8.1+ 属性类型须与数据库严格对齐。
Ubiquity 的 ORM 初始化必须在 Router::start() 之前完成
Ubiquity 的 DbModel 和自动映射依赖全局数据库连接配置，如果先调用路由启动再初始化 ORM，会导致模型类无法识别表结构或抛出 Undefined property: Ubiquity\orm\Orm::$db 错误。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在
index.php或入口文件中，确保Ubiquity\orm\Orm::configure()和Ubiquity\orm\Orm::useCache(true)在Ubiquity\router\Router::start()之前执行 - 缓存启用后，ORM 默认使用 APCu（PHP ≥7.0）；若环境无 APCu，需显式指定驱动，例如：
Ubiquity\cache\CacheManager::setDriver('files') - 避免在控制器里重复调用
Orm::configure()—— 多次配置会覆盖连接参数，导致后续查询连错库
用 findOne() 和 findAll() 时，缓存键默认不包含 WHERE 条件的动态值
Ubiquity ORM 的缓存机制对方法级结果做键值管理，但 findOne() 和 findAll() 的缓存键默认只基于模型名和方法名，不自动拼接查询条件（如 ['name'=>'admin']）。这意味着相同模型的多次不同条件查询可能命中同一缓存，返回错误数据。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 手动构造带条件签名的缓存键：用
md5(serialize($conditions))生成唯一标识，再传给findOne()的$cacheKey参数 - 示例：
User::findOne(['email'=>$email], true, 'user_by_email_'.md5($email))—— 第二个参数true表示启用缓存，第三个为显式键名 - 注意：
findAll()不支持直接传$cacheKey，需改用Query::byDql()或封装一层带缓存逻辑的静态方法
缓存失效策略必须配合模型事件手动触发
Ubiquity 不提供自动缓存穿透或写后失效（write-through / write-behind），更新/删除模型实例时，对应缓存不会自动清除。常见现象是：数据库已更新，但 findOne() 仍返回旧值。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在模型类中重写
afterUpdate()和afterDelete()方法，调用Ubiquity\cache\CacheManager::delete($key) - 若使用通配符缓存（如前缀
user_*），需搭配支持通配删除的驱动（Redis 可行，APCu 不行）；否则只能按具体键逐个删 - 避免在事务中延迟清理缓存——若事务回滚，缓存已被误删，导致下次读取为空
PHP 8.1+ 下启用属性类型声明时，Ubiquity 模型字段需与数据库类型严格对齐
Ubiquity 2.4+ 支持 PHP 属性类型（如 public int $id），但 ORM 映射层不会自动类型转换。当数据库字段是 VARCHAR 却声明为 int，或 TIMESTAMP 声明为 string，会导致 TypeError 或静默截断。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 优先使用
mixed或不声明类型，交由 ORM 的cast配置处理；如确需类型，用#[Column(type: 'integer')]显式标注，并保持与 DB 类型一致 - 日期字段统一用
DateTimeInterface类型 +#[Column(type: 'datetime')]，避免字符串解析失败 - 检查
Ubiquity\orm\Orm::getMapper()->getColumns()输出，确认字段类型映射是否符合预期，尤其注意 MySQL 的TINYINT(1)常被误当布尔，实际应映射为bool并启用cast
缓存键设计和 ORM 生命周期绑定是 Ubiquity 里最容易漏掉的两环；一个写错，整个数据一致性就不可信。
