Doctrine DBAL 中 columnDefinition 变更检测的解决方案

背景介绍

在使用 Doctrine DBAL 进行数据库操作时，开发者经常会遇到需要自定义列定义(columnDefinition)的情况。Doctrine 提供了 columnDefinition 属性，允许开发者完全控制数据库列的 DDL 语句。然而，当前版本的 Doctrine 存在一个限制：它无法自动检测 columnDefinition 属性的变更。

问题分析

当开发者修改了实体类中的 columnDefinition 定义后，Doctrine 的 Schema 比对工具无法识别这种变更。这意味着即使 columnDefinition 发生了变化，Doctrine 也不会生成相应的数据库迁移脚本。这种情况可能导致数据库列定义与实体类定义不一致，从而引发潜在的问题。

解决方案原理

虽然 Doctrine 无法直接检测 columnDefinition 的变更，但它可以检测列注释(comment)的变化。基于这个特性，我们可以实现一个间接的解决方案：

1. 为每个使用 columnDefinition 的列添加一个特殊的注释
2. 注释内容是基于 columnDefinition 内容的哈希值
3. 当 columnDefinition 发生变化时，哈希值也会变化
4. Doctrine 检测到注释变化后，会认为列定义发生了变化

具体实现

1. 定义自定义属性

首先创建一个自定义属性类，用于标记需要特殊处理的列：

#[\Attribute(\Attribute::TARGET_PROPERTY)]
final class ColumnDefinitionHashComment
{
}

2. 在实体类中使用

在实体类中，为需要监控 columnDefinition 变化的属性添加这个自定义属性：

#[ColumnDefinitionHashComment]
#[ORM\Column(
    type: 'integer',
    nullable: false,
    columnDefinition: 'INT GENERATED ALWAYS AS (JSON_VALUE(data, "$.id")) NOT NULL'
)]
private readonly int $relationId;

3. 实现事件订阅器

创建一个事件订阅器，在加载类元数据时为标记的列添加哈希注释：

class ColumnDefinitionHashCommentSubscriber
{
    public function loadClassMetadata(LoadClassMetadataEventArgs $event): void
    {
        $classMetadata = $event->getClassMetadata();

        foreach ($classMetadata->fieldMappings as $fieldName => $fieldMapping) {
            $reflectionProperty = $classMetadata->reflClass->getProperty($fieldName);
            $attributes = $reflectionProperty->getAttributes(ColumnDefinitionHashComment::class);

            if ([] === $attributes) {
                continue;
            }

            $this->addColumnDefinitionCommentHash($classMetadata->getName(), $reflectionProperty, $fieldMapping);
        }
    }

    private function addColumnDefinitionCommentHash(
        string $className,
        ReflectionProperty $reflectionProperty,
        array $fieldMapping
    ): void {
        if (empty($fieldMapping['columnDefinition'])) {
            throw new \LogicException(sprintf(
                '实体字段 %s:%s 必须定义 columnDefinition',
                $className,
                $reflectionProperty->getName()
            ));
        }

        if (false !== strripos($fieldMapping['columnDefinition'], 'comment')) {
            throw new \LogicException(sprintf(
                '实体字段 %s:%s 的 columnDefinition 中不能包含 comment',
                $className,
                $reflectionProperty->getName()
            ));
        }

        // 使用高效的 xxh3 哈希算法
        $hash = hash('xxh3', $fieldMapping['columnDefinition']);
        $fieldMapping['options']['comment'] = sprintf('(columnDefinitionHash:%s)', $hash);
        $fieldMapping['columnDefinition'] .= sprintf(' COMMENT "%s"', $fieldMapping['options']['comment']);
    }
}

实现细节说明

1. 哈希算法选择：使用了 xxh3 算法，这是 PHP 中性能最好的哈希算法之一
2. 注释格式：采用特定格式 (columnDefinitionHash:哈希值)，便于识别和解析
3. 错误处理：确保 columnDefinition 必须存在且不包含注释，避免冲突
4. 数据库兼容性：将注释直接附加到 columnDefinition 的 SQL 语句中，确保在各种数据库中都有效

使用建议

1. 将此订阅器注册到 Doctrine 的事件系统中
2. 仅对确实需要监控 columnDefinition 变化的列使用此方案
3. 在团队开发中，确保所有成员了解此机制，避免直接修改注释
4. 考虑在项目文档中记录此解决方案，方便后续维护

总结

这个解决方案巧妙地利用了 Doctrine 已有的注释变更检测机制，通过添加基于 columnDefinition 内容的哈希注释，间接实现了对 columnDefinition 变更的检测。虽然这是一个"取巧"的方案，但在 Doctrine 原生不支持的情况下，提供了一种可靠的工作方式。开发者可以根据实际需求调整实现细节，如选择不同的哈希算法或注释格式。