Doctrine实体关系映射需确保配置、映射与查询三层咬合：多对多须显式预加载；继承映射需yaml类型匹配attribute、基类标注InheritanceType与DiscriminatorColumn；API Platform子类须独立标注ApiResource；带排序字段的中间表须改用OneToMany关联中间实体。
Doctrine 实体关系映射不是“配完就能用”，而是“配错一步，查不到数据、报 Class is not a valid entity、甚至 SQL 报错”。关键不在语法对不对，而在策略选得准不准、配置和代码写法是否咬合、查询时有没有绕过懒加载陷阱。
多对多关系中 movie.actors 为空？一定是没预加载
即使 @ORM\ManyToMany 注解写得完全正确，$movie->getActors() 在控制器里直接调用仍可能返回空 ArrayCollection。这不是 bug，是 Doctrine 懒加载的默认行为——它只在你第一次访问集合时才发 SQL，而那时上下文可能已丢失（比如模板渲染阶段）。
-
findAll()不会自动加载关联实体，它只查主表； - 必须用
createQueryBuilder()显式leftJoin('m.actors', 'a')+addSelect('a')，否则a不进结果集，代理对象不初始化； - 漏掉
addSelect('a')是最常见错误，光leftJoin不够，Doctrine 不会把Actor实例塞进结果里； - 如果只查单条电影，用
->select('m', 'a')+->getOneOrNullResult()，结果是数组，需取$result['m']和$result['a']；
继承映射报 “Class is not a valid entity”？先看配置类型是否匹配
PHP 8+ 项目用 #[ORM\Entity] 属性（attributes），但 doctrine.yaml 里若还写着 type: annotation，Doctrine 就根本找不到类——连扫描都不扫，直接报这个错。
- 检查
config/packages/doctrine.yaml中mappings.App.type必须是attribute，不是annotation或xml； - 基类必须加
#[ORM\InheritanceType('JOINED')]或'SINGLE_TABLE'，且#[ORM\DiscriminatorColumn]字段名和类型要和数据库一致； -
#[ORM\DiscriminatorMap]的键（如'person'）必须全小写，值（如Person::class）必须是完整类名； - 子类不能漏掉
#[ORM\Entity]，哪怕它继承自抽象基类；
API Platform 中继承实体不显示？子类必须单独加 #[ApiResource]
基类 Party 加了 #[ApiResource]，不代表 Person 和 Organization 自动注册路由。API Platform 只认被显式标注为资源的类。
- 每个具体子类（
Person、Organization）都必须有自己独立的#[ApiResource]； - 基类保持
abstract，且不要加#[ApiResource]，否则会生成一个无法实例化的端点； - 若用
SINGLE_TABLE策略，基类可加#[ApiResource]，但需确保discriminator_field被正确暴露，否则过滤失效； - 子类的
#[ApiResource]可带参数，比如security或pagination_enabled，按需差异化控制；
中间表带排序字段（如 serial_number）？别用 ManyToMany，改用两个 OneToMany
Doctrine 的 @ORM\ManyToMany 不支持中间表自定义字段。一旦你需要 product_categories.serial_number 这种排序字段，就必须拆成三张实体：Product、Category、ProductCategory（中间实体）。
- 删除
Product::$categories上的@ORM\ManyToMany； - 新建
ProductCategory实体，含product_id、category_id、serial_number字段，并配@ORM\ManyToOne分别指向 Product 和 Category； - 在
Product中定义@ORM\OneToMany(mappedBy="product")关联到ProductCategory； - 查询时用
->addOrderBy('pc.serial_number')，排序逻辑就落在中间实体上，干净可控；
真正卡住人的从来不是语法记不住，而是 Doctrine 在“配置层”“映射层”“查询层”三者之间存在隐式契约——少对一环，运行时才报错，而且错误信息往往不指明根源。
