Scramble项目兼容旧版MySQL数据库的解决方案

背景介绍

Scramble是一个用于生成API文档的Laravel扩展包。在实际使用过程中，当项目需要连接旧版本MySQL数据库(5.7以下)时，可能会遇到"Unknown column 'generation_expression' in 'field list'"的错误。这是因为新版Laravel的数据库语法解析器默认会查询一些新版MySQL才支持的字段，而旧版数据库不存在这些字段。

问题分析

在Laravel框架中，数据库Schema语法解析器(Schema Grammar)负责生成查询数据库结构的SQL语句。新版Laravel的MySqlGrammar类会默认查询包括generation_expression在内的多个字段，这些字段在MySQL 5.7及以上版本才存在。

当Scramble尝试分析控制器和模型时，如果模型连接的是旧版MySQL数据库，就会因为查询了不存在的字段而导致整个服务器挂起。

解决方案

自定义LegacyMySqlGrammar

我们可以通过继承Laravel的MySqlGrammar类并重写相关方法来解决兼容性问题：

namespace App\Database\Grammar;

use Illuminate\Database\Connection;
use Illuminate\Database\Schema\Grammars\MySqlGrammar;
use Illuminate\Support\Facades\Log;

class LegacyMySqlGrammar extends MySqlGrammar
{
    public function __construct(?Connection $connection = null)
    {
        if ($connection) {
            parent::__construct($connection);
        }
    }

    public function compileColumns($schema, $table): string
    {
        return sprintf(
            'select column_name as `name`, data_type as `type_name`, column_type as `type`, '
            . 'collation_name as `collation`, is_nullable as `nullable`, '
            . 'column_default as `default`, column_comment as `comment`, '
            . '\'\' as `expression`, extra as `extra` '
            . 'from information_schema.columns where table_schema = %s and table_name = %s '
            . 'order by ordinal_position asc',
            $schema ? $this->quoteString($schema) : 'schema()',
            $this->quoteString($table)
        );
    }

    public function __call($method, $parameters)
    {
        if (str_contains($method, 'Column') || str_contains($method, 'column')) {
            Log::warning("Column-related method {$method} called - might need override");
        }

        return parent::__call($method, $parameters);
    }
}

这个自定义语法解析器主要做了以下改进：

1. 重写了compileColumns方法，使用兼容旧版MySQL的查询语句
2. 移除了对新版MySQL特有字段(generation_expression等)的查询
3. 添加了__call方法处理可能的列相关方法调用

注册自定义语法解析器

接下来需要创建一个服务提供者来注册我们的自定义语法解析器：

namespace App\Providers;

use App\Database\Grammar\LegacyMySqlGrammar;
use Illuminate\Database\Events\ConnectionEstablished;
use Illuminate\Support\ServiceProvider;

class LegacyDatabaseServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->app['events']->listen(ConnectionEstablished::class, function (ConnectionEstablished $event) {
            $connectionName = $event->connection->getName();

            if (in_array($connectionName, ['oldmysql'])) {
                $grammar = new LegacyMySqlGrammar($event->connection);
                $event->connection->setSchemaGrammar($grammar);
            }
        });
    }
}

这个服务提供者会在数据库连接建立时检查连接名称，如果是我们指定的旧版MySQL连接('oldmysql')，就使用自定义的语法解析器。

启用服务提供者

最后，在config/app.php的providers数组中注册这个服务提供者：

'providers' => [
    // 其他服务提供者...
    App\Providers\LegacyDatabaseServiceProvider::class,
],

实现原理

这个解决方案的核心思想是"向下兼容"。通过自定义数据库语法解析器，我们：

1. 拦截了Laravel默认的数据库结构查询
2. 替换为兼容旧版MySQL的查询语句
3. 确保只查询旧版数据库支持的字段
4. 通过事件监听机制在适当的时候应用这些修改

这种方法不会影响新版MySQL的使用，同时为旧版数据库提供了兼容性支持。

注意事项

1. 此方案主要解决的是数据库结构查询的兼容性问题
2. 如果项目中使用了其他新版MySQL特有的功能，可能需要额外处理
3. 建议在测试环境中充分验证后再应用到生产环境
4. 长期来看，升级MySQL数据库才是根本解决方案

通过这种定制化方式，我们可以在不升级MySQL的情况下，使Scramble项目能够正常分析包含旧版MySQL模型的控制器，生成API文档。