Doctrine ORM 是 PHP 生态中最成熟、功能最丰富的对象关系映射工具之一，它不只帮你把数据库表映射成类，更提供了实体管理、复杂查询构建、事务控制、生命周期回调等企业级能力。用好 Doctrine，关键不在“会不会装”，而在“怎么设计实体”、“怎么写高效查询”、“怎么避免 N+1”和“怎么与现代 PHP 项目（如 Symfony 或 Laravel）协同”。
实体设计：从数据库结构出发，但不止于字段映射
Doctrine 实体不是数据库表的简单镜像，而是业务概念的载体。定义时需兼顾数据完整性、可读性和扩展性。
- 用 @Entity 和 @Table 明确声明实体身份与表名，避免依赖默认命名规则
- 主键推荐使用 @Id + @GeneratedValue(strategy="IDENTITY")（MySQL/Auto-increment）或 strategy="UUID"（分布式友好）
- 关联字段优先用 mappedBy / inversedBy 显式指定拥有方，避免双向关系错乱；一对多尽量让“多”的一方维护外键
- 敏感字段（如密码）加 @Exclude（配合 JMS Serializer）或用 private $plainPassword + 自定义 setter 控制逻辑
DQL 与 QueryBuilder：别在控制器里拼 SQL 字符串
Doctrine 提供两种安全、可复用的查询方式：DQL（类 SQL 的面向对象查询语言）和 QueryBuilder（链式构造器）。它们都由 EntityManager 解析，自动参数化、防注入、支持缓存。
- DQL 适合结构稳定、复用少的查询，例如：SELECT u FROM App\Entity\User u WHERE u.status = :status，参数用 $query->setParameter('status', 'active')
- QueryBuilder 更适合动态条件（如后台筛选），例如：$qb->where($qb->expr()->eq('u.status', ':status'))->andWhere($qb->expr()->like('u.name', ':name'))
- 分页别手写 LIMIT/OFFSET，用 Paginator（use Doctrine\ORM\Tools\Pagination\Paginator;）封装，它会自动优化 COUNT 查询
性能避坑：N+1、懒加载、批量操作一个都不能松懈
Doctrine 默认启用懒加载（Lazy Loading），方便开发却极易引发 N+1 查询问题——查 100 个用户，再遍历取每个用户的 Profile，就会触发 101 次查询。
立即学习“PHP免费学习笔记（深入）”；
- 关联数据必须一次性获取？用 join + addSelect 预加载：$qb->leftJoin('u.profile', 'p')->addSelect('p')
- 想彻底禁用懒加载（尤其 CLI 或 API 场景）？配置 proxyAutoGenerate: false 并设 fetch="EAGER"（慎用，易过度加载）
- 批量插入/更新别循环 persist + flush，改用 EntityManager::flush() 一次提交，或对海量数据用 Connection::executeStatement() 直连执行原生语句
集成现代项目：Symfony 原生支持，Laravel 可桥接
Symfony 开箱即用 Doctrine（doctrine/doctrine-bundle），配置、迁移、命令全打通。Laravel 虽默认用 Eloquent，但可通过 laravel-doctrine/orm 包接入，共享服务容器与事件系统。
- Symfony 中，实体放在 src/Entity/，仓库放 src/Repository/，自定义方法直接写在 Repository 类里，用 $this->getEntityManager() 获取实例
- Laravel 使用 Doctrine 时，建议将 Entity 和 Repository 放入独立目录（如 app/Doctrine/Entity），通过 Service Provider 绑定到容器，并重写 DB::connection() 的解析逻辑以隔离 Eloquent
- 无论哪种框架，数据库迁移统一用 doctrine:migrations，别混用框架自带迁移工具，避免版本漂移
