DoctrineMigrationsBundle 3.4版本迁移状态显示异常问题分析

问题背景

DoctrineMigrationsBundle是Symfony生态中管理数据库迁移的重要组件。在3.4版本发布后，开发者反馈在开发环境的调试工具栏中，所有已执行的迁移都被错误地标记为"未执行"状态，尽管数据库中的迁移表确实包含所有迁移记录。

问题现象

升级到3.4版本后，开发者观察到以下异常现象：

1. 在Symfony的Web调试工具栏中，所有迁移显示为未执行状态
2. 数据库中的migration表确认包含所有迁移记录
3. 控制台命令doctrine:migrations:list能正确显示已执行的迁移
4. 执行doctrine:make:migration时错误提示有未执行的迁移

根本原因分析

经过深入排查，发现问题源于3.4版本引入的SchemaFilterListener组件。该监听器默认启用了数据库模式资产过滤器(schema assets filter)，导致在Web环境下：

1. 迁移元数据存储(TableMetadataStorage)初始化时无法正确识别迁移表
2. isInitialized标志始终为false
3. 获取已执行迁移列表时返回空数组

具体来说，TableMetadataStorage在检查表是否存在时，调用了DBAL的listTableNames方法，而该方法内部使用了资产过滤器，导致迁移表被错误过滤。

技术细节

问题的核心在于资产过滤器的应用范围不当：

1. 过滤器设计初衷：用于限制模式操作(如表创建/更新)仅作用于特定表
2. 实际影响：在Web环境下也应用了过滤器，导致迁移表被排除
3. 预期行为：过滤器应仅在执行模式更新/验证命令时启用

解决方案

开发团队提出了两种解决方案：

1. 临时方案：在需要检查迁移状态的代码中手动禁用过滤器

$config = $connection->getConfiguration();
$trueSchemaAssetsFilter = static fn() => true;
$previousFilter = $config->getSchemaAssetsFilter() ?? $trueSchemaAssetsFilter;
$config->setSchemaAssetsFilter($trueSchemaAssetsFilter);

try {
    // 执行迁移状态检查
} finally {
    $config->setSchemaAssetsFilter($previousFilter);
}

2. 永久修复：调整SchemaFilterListener的默认行为，改为：

• 默认禁用过滤器
• 仅在特定命令(如schema:update, schema:validate)中启用

最佳实践建议

对于使用DoctrineMigrationsBundle的开发者：

1. 升级策略：建议升级到包含修复的3.4.1版本
2. 自定义命令：如需在自定义命令中检查迁移状态，确保正确处理过滤器
3. 健康检查：如果端点依赖迁移状态，需要确认状态检查逻辑不受过滤器影响

总结

此问题展示了框架组件间微妙的交互影响。资产过滤器的引入本意是好的，但由于应用范围过广导致了意外行为。开发团队通过调整默认行为和精确控制过滤器应用场景，既保留了功能价值，又解决了兼容性问题。这也提醒我们在设计类似功能时，需要仔细考虑各种使用场景的影响。