Symfony中实现字段唯一性验证需用@UniqueEntity注解，注意加密字段须增设哈希字段、复合约束需PHP与数据库双层配置、软删除需自定义repositoryMethod排除逻辑删除记录。
在 Symfony 中实现字段唯一性验证，核心是用 @UniqueEntity 注解配合 Doctrine 实体定义，但实际落地时需注意加密字段、软删除、复合约束等常见场景的特殊处理。直接加注解不等于生效，关键在于验证时机、数据形态和数据库层面的协同。
基础用法：单字段唯一验证
最常用的方式是在实体类顶部添加 @UniqueEntity，指定要校验的字段名（对应属性名）：
- 确保该字段在数据库中已建唯一索引（如 MySQL 的
UNIQUE KEY），否则仅靠 PHP 层验证无法防止并发插入冲突； - 字段名必须是实体属性名，不是数据库列名（除非显式映射了
columnName）； - 若字段允许为空（
nullable=true），建议加上ignoreNull=true，避免多个NULL被误判为重复。
加密字段的唯一性：不能直接验证密文
当字段被 @Encrypted（或类似加密机制）标记时，@UniqueEntity 默认失效——因为验证器拿到的是明文，而数据库存的是密文，二者无法比对。
- 推荐做法是增设一个同源哈希字段（如
emailHash），在setEmail()中同步计算并赋值，再对这个哈希字段加@UniqueEntity； - 哈希应加盐（如拼接实体类名或固定字符串），防止彩虹表攻击；
- 哈希字段本身不加密，只用于唯一性比对，不影响主字段的安全性。
多字段组合唯一：用 UniqueConstraint + UniqueEntity
业务常需“用户名+租户ID”或“产品+客户”组合唯一。这时需两层保障：
- PHP 层：在
@UniqueEntity的fields中传入数组，如fields={"username", "tenantId"}； - 数据库层：用 Doctrine 的
#[ORM\UniqueConstraint]显式声明复合唯一约束，例如：
#[ORM\UniqueConstraint(name: 'uq_user_tenant', columns: ['username', 'tenant_id'])]； - 注意：列名（
columns）必须是数据库字段名，不是 PHP 属性名。
软删除场景下的唯一性绕过问题
启用软删除（如 deletedAt 字段）后，数据库里仍存在“逻辑已删”的记录，@UniqueEntity 默认会查出它们，导致新数据无法保存。
- 解决方式是自定义
repositoryMethod，在 Repository 中写一个方法，查询时排除已软删除的记录； - 然后在
@UniqueEntity中引用它：repositoryMethod="findActiveByUsername"； - 该方法返回
null或实体，验证器据此判断是否冲突。
