Symfony实体是带行为契约的数据模型，须脱离Doctrine正常运行；属性私有、命名语义化；字段映射需显式声明类型与约束；关联关系、主键策略等必须手动配置准确。
Symfony 实体不是“数据库表的镜像”，而是**带行为契约的数据模型**——它既描述结构，也承载业务语义。直接把数据库字段一比一搬进 PHP 类，是绝大多数新手踩的第一个坑。
实体类怎么写才不算错？
核心判断标准：能不能脱离 Doctrine 正常实例化、调用方法、参与业务逻辑？如果去掉 @ORM\* 注解后整个类就崩了，说明你把它写成了“注解容器”，而不是实体。
- 属性必须是
private，且不暴露原始数据库字段名（比如别叫$user_name，应叫$name） - 所有字段映射必须通过
@ORM\Column显式声明类型和约束，type="string"不等于数据库VARCHAR(255)—— 要配length=255，否则迁移时可能被截断 -
@ORM\Id+@ORM\GeneratedValue必须成对出现，且仅用于主键；自增整型别漏掉strategy="AUTO"，否则插入会报Column 'id' cannot be null - 不要在实体里写
echo、var_dump或直接调用$em->flush()—— 这是控制器或服务层的事
为什么 make:entity 生成的代码不能直接用？
命令行工具只做骨架填充，它不会判断你的业务意图。比如你加一个 status 字段，它默认给 @ORM\Column(type="string")，但实际你可能需要的是枚举（type="string", options={"enum": ["draft","published"]}）或布尔（type="boolean"），类型错会导致查询结果异常、迁移失败，甚至数据静默丢失。
- 生成后务必检查每个字段的
type和options是否匹配真实需求 -
nullable=true不等于“可为空”就该加——比如deletedAt可空合理，但createdAt加了就违背时间戳语义 - 关系字段（如
ManyToOne）不会自动加onDelete="CASCADE"，得手动补，否则外键约束失效 - 生成的 getter/setter 缺少类型声明（PHP 7.4+ 推荐加
: ?string等），IDE 和静态分析工具会误判
映射失败的典型错误现象有哪些？
不是报错才叫失败。很多问题在开发期藏得深，上线后才爆发：比如列表页突然变慢、搜索结果漏数据、API 返回 null 而不是空数组。
-
Notice: Undefined index: id—— 实体没设@ORM\Id，Doctrine 找不到标识符 -
Class App\Entity\Product is not a valid entity or mapped super class—— 忘了@ORM\Entity，或命名空间路径与src/Entity/目录不一致 - 执行
php bin/console doctrine:schema:update --dump-sql没输出任何 SQL —— 实体没被 Doctrine 扫描到，检查doctrine.orm.mappings配置是否包含你的命名空间 - 关联查询返回
null却没报错 ——JoinColumn的referencedColumnName写错了（比如写成user_id而不是id）
什么时候该用 YAML/XML 而不是注解？
不是“更高级”，而是“更隔离”。注解把映射逻辑和业务逻辑耦合在同一个文件里，当团队里有 DBA 审核表结构、或你需要为同一套实体适配多个数据库（MySQL/PostgreSQL/SQLite）时，注解就硬编码死了。
- YAML 更适合 DBA 协作场景：
config/doctrine/Product.entity.yaml可单独交由他人评审 - XML 在大型遗留项目中更常见（Symfony 2 时代遗留），迁移成本高但稳定性强
- PHP 配置方式极少用，除非你明确要动态生成元数据（比如多租户 Schema 切换）
- 混合使用（部分注解 + 部分 YAML）会被 Doctrine 忽略——它只认一种格式，以配置文件中
mappings.type为准
Product 是商品？还是库存单位？还是销售 SKU？名字一样，映射方式、关联关系、甚至是否该有 @ORM\InheritanceType，全都不一样。 
