Doctrine ORM 中实现全局 DEFERRED_EXPLICIT 变更跟踪策略

在 Doctrine ORM 的实际应用中，变更跟踪策略(Change Tracking Policy)是一个关键概念，它决定了 ORM 如何检测实体对象的变更。默认情况下，Doctrine 使用 DEFERRED_IMPLICIT 策略，这意味着 ORM 会自动跟踪所有实体的变更。然而，在某些特定场景下，开发者可能需要更精细的控制。

DEFERRED_EXPLICIT 策略的优势

DEFERRED_EXPLICIT 策略要求开发者显式调用 persist() 方法标记需要持久化的实体。这种策略特别适合以下场景：

1. 财务类应用需要运行模拟计算，但不希望临时计算结果被自动持久化
2. 需要精确控制哪些变更应该被保存到数据库
3. 避免意外修改导致的数据不一致
4. 提高系统可预测性和可维护性

实现全局 DEFERRED_EXPLICIT 的挑战

虽然 Doctrine 允许在每个实体类上使用 @ChangeTrackingPolicy 注解设置 DEFERRED_EXPLICIT 策略，但在大型项目中，手动为所有实体添加这一注解既繁琐又容易遗漏。我们需要一种机制来确保所有相关实体都遵循这一策略。

解决方案：自定义元数据加载监听器

通过创建 Doctrine 事件监听器，我们可以在类元数据加载时强制执行 DEFERRED_EXPLICIT 策略。以下是实现这一功能的关键点：

1. 监听 loadClassMetadata 事件
2. 检查实体是否已经设置了 DEFERRED_EXPLICIT 策略
3. 根据命名空间过滤需要检查的实体
4. 在开发环境中抛出异常以提醒开发者

use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
use Doctrine\ORM\Event\LoadClassMetadataEventArgs;
use Doctrine\ORM\Events;
use Doctrine\ORM\Mapping\ClassMetadataInfo;
use Doctrine\ORM\Mapping\MappingException;

#[AsDoctrineListener(event: Events::loadClassMetadata)]
final readonly class ChangeTrackingPolicySubscriber
{
    public function __construct(
        private array $includedNamespaces = [],
        private array $excludedNamespaces = [],
    ) {
    }

    public function loadClassMetadata(LoadClassMetadataEventArgs $event): void
    {
        $classMetadata = $event->getClassMetadata();
        // 跳过嵌入式类和映射超类
        if ($classMetadata->isEmbeddedClass || $classMetadata->isMappedSuperclass) {
            return;
        }
        
        // 已设置 DEFERRED_EXPLICIT 策略的跳过检查
        if ($classMetadata->changeTrackingPolicy === ClassMetadataInfo::CHANGETRACKING_DEFERRED_EXPLICIT) {
            return;
        }

        // 确保反射类可用
        if (!$classMetadata->getReflectionClass()) {
            return;
        }

        // 命令行生成代码时跳过检查
        if (PHP_SAPI === 'cli') {
            foreach ($_SERVER['argv'] ?? [] as $arg) {
                if (str_starts_with(strtolower($arg), 'make:')) {
                    return;
                }
            }
        }

        $fqcn = $classMetadata->getReflectionClass()->getName();

        // 检查是否在包含的命名空间中
        $isIncluded = false;
        foreach ($this->includedNamespaces as $includedNamespace) {
            if (str_starts_with($fqcn, $includedNamespace)) {
                $isIncluded = true;
                break;
            }
        }

        if (!$isIncluded) {
            return;
        }

        // 检查是否在排除的命名空间中
        if ($this->excludedNamespaces) {
            foreach ($this->excludedNamespaces as $excludedNamespace) {
                if (str_starts_with($fqcn, $excludedNamespace)) {
                    return;
                }
            }
        }

        // 抛出异常提醒开发者
        throw new MappingException(sprintf('实体 %s 必须设置变更跟踪策略为 DEFERRED_EXPLICIT', $fqcn));
    }
}

实际应用建议

1. 命名空间配置：通过 includedNamespaces 和 excludedNamespaces 参数精确控制需要检查的实体范围

2. 开发环境检查：建议仅在开发环境中启用严格检查，生产环境可适当放宽以避免性能影响

3. 逐步迁移：对于已有项目，可以先用监听器识别问题，再逐步修复

4. 单元测试：为关键业务逻辑添加测试，确保显式持久化不会遗漏重要变更

总结

通过自定义元数据加载监听器，我们实现了 Doctrine ORM 中 DEFERRED_EXPLICIT 策略的全局强制执行。这种方法结合了灵活性和严格性，既满足了财务类应用对数据变更的精确控制需求，又通过自动化检查降低了人为遗漏的风险。对于需要高度可控持久化行为的应用场景，这是一个值得考虑的解决方案。