Doctrine实体映射需三要素：类加@Entity注解、命名空间路径注册进配置、字段用@Column等显式声明；缺一即被忽略或查不到数据。
Doctrine实体映射不是“写完类就自动生效”，关键在于三件事：类必须被正确标注、命名空间路径要注册进配置、字段需显式声明映射规则。漏掉任一环，doctrine:schema:update 就会忽略它，查询也返回 null。
实体类必须加 @Entity 并配好基础注解
Doctrine 不扫描所有 PHP 类，只认带 @ORM\Entity 的类，且必须配合 @ORM\Table（哪怕空参数）。主键和字段也得逐个标注：
- 主键字段必须同时有
@ORM\Id和@ORM\GeneratedValue（自增）或明确指定生成策略 - 每个持久化属性都要用
@ORM\Column，不能只写public $name; - 属性必须是
private或protected，public 属性不被识别 - 字符串类型建议加
length，比如@ORM\Column(type="string", length=255)
映射方式要跟 Doctrine 版本对齐
Symfony 6.4+ 和 Doctrine ORM v3 默认启用 PHP 8 Attributes，不是传统 PHPDoc 注解：
- 配置里
type: attribute是强制项，不能写annotation - 实体中要用
#[ORM\Entity]这种语法，不是@ORM\Entity - 确保装的是
doctrine/annotations:^2.0，v3.x 不兼容旧注解解析 - 每个文件顶部加
use Doctrine\ORM\Mapping as ORM;
doctrine.yaml 必须注册实体路径
即使类写对了，没在配置里告诉 Doctrine 去哪找，它也看不见：
-
mappings.App.dir指向'%kernel.project_dir%/src/Entity' -
mappings.App.prefix设为'App\Entity' -
mappings.App.type必须是attribute（v3 要求） - 如果用了子命名空间（如
App\Entity\Blog\Post），路径和 prefix 要保持一致
关联关系不能只写注解，还得补全细节
一对多、多对一这些常见关系，光写 @ORM\OneToMany 不够，容易查不到数据：
- 目标实体类名必须完整（如
targetEntity: App\Entity\Comment） - 双向关联时，
mappedBy和inversedBy要配对，字段名是对方实体的属性名，不是数据库列名 - 外键字段要显式用
@ORM\JoinColumn，否则可能生成冗余字段或报错 - 避免 N+1：需要关联数据时，用
join查询或addSelect()预加载，别靠懒加载自动触发
