因为项目小、依赖要少、结构固定、无需复杂关系，data mapper 模式解耦领域对象与数据库，模型无框架痕迹、sql 可控、调试定位准；实体只持数据，mapper 负责 crud 与映射，靠 ispersisted() 区分 insert/update，白名单字段安全映射。
为什么不用 Eloquent 或 Doctrine 而要手写轻量级 ORM？
因为项目小、依赖要少、数据库结构固定、不需要复杂关系加载或迁移能力。Data Mapper 模式正好满足——它把领域对象（如 User）和数据库表完全解耦，不靠继承（不像 Active Record），更适合控制权明确、可测试性强的场景。
核心代价是多一层映射定义，但换来的是：模型类彻底无框架痕迹、SQL 可控、调试时容易定位到哪一行出问题。
如何定义实体类与 Mapper 类的最小契约？
实体类只管数据持有，不碰数据库；Mapper 类负责查、插、改、删，并知道怎么把实体转成 SQL 参数、再把结果集塞回实体。两者之间不能互相引用，靠接口或约定通信。
-
User类只需 public 属性或 getter/setter，不依赖任何基类 -
UserMapper构造函数接收PDO实例，内部用prepare()+execute()，避免拼接 SQL - 必须约定主键字段名（如统一叫
id），否则save()无法判断 INSERT 还是 UPDATE - 实体属性名和数据库字段名默认一致；若不一致，用数组映射（如
['user_name' => 'name']）在 Mapper 里处理
怎样让 save() 自动区分 INSERT 和 UPDATE？
靠主键是否为空——但注意：null、0、''、未设置都得区分清楚。PHP 的 empty() 会把 0 当假值，导致 ID=0 的记录被当成新记录插入，这是高频翻车点。
实操建议：
- 在实体类中加一个
isPersisted()方法，显式返回$this->id !== null && $this->id != 0（假设 ID 是非零正整数） - Mapper 的
save()先调$entity->isPersisted()，再决定走INSERT还是UPDATE - INSERT 后用
$pdo->lastInsertId()回填实体id，否则下次save()还是 INSERT - UPDATE 语句必须带
WHERE id = ?，且参数绑定严格按顺序，别漏掉id
查询结果怎么安全映射回实体而不污染对象状态？
不能直接 foreach ($row as $k => $v) $obj->$k = $v —— 万一数据库字段多了个 deleted_at，而实体没这个属性，就会触发 __set() 或报错；更糟的是，如果实体用了 __set() 做类型转换，外部数据可能绕过校验。
推荐做法：
- Mapper 内部用白名单字段映射：
$allowed = ['id', 'name', 'email']，遍历$row时只取这些 key - 构造新实体：
new User($row['id'], $row['name'], $row['email'])，而不是复用已有对象 - 如果实体用数组构造，确保构造函数对缺失字段设默认值（如
$email = ''），避免 Notice - 批量查询返回
array_map包装的实体数组，别返回 PDOStatement 或原始数组
真正难的不是写完，而是每次加字段时同步改三处：数据库表、实体属性、Mapper 映射白名单——这里没有银弹，靠文档和单元测试守住。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
