Laravel 迁移外键重复列问题解决

问题解析：SQLSTATE[42S21] 错误成因

在 Laravel 数据库迁移过程中，当尝试添加外键并执行 php artisan migrate:fresh 命令时，有时会遇到 SQLSTATE[42S21]: Column already exists: 1060 Duplicate column name 'id_rso' 这样的错误。这个错误明确指出，在尝试创建表时，某个列（例如 id_rso）被重复定义了。

根据提供的迁移代码片段：

public function up()
{   
    Schema::enableForeignKeyConstraints();
    Schema::create('dso', function (Blueprint $table) {
        $table->string('id_dso',30);
        $table->unsignedBigInteger('id_rso'); // 第一次定义
        $table->foreignId('id_rso')->constrained('rso'); // 第二次定义
        // ... 其他列 ...
    });
}

问题的根源在于 id_rso 列被定义了两次：

1. $table->unsignedBigInteger('id_rso');：这行代码会创建一个名为 id_rso 的 UNSIGNED BIGINT 类型的列。
2. $table->foreignId('id_rso')->constrained('rso');：foreignId() 方法是 Laravel 8 及更高版本中引入的便捷方法。它不仅会创建一个符合外键要求的 UNSIGNED BIGINT 类型的列，还会自动添加外键约束。

因此，当这两行代码同时存在时，数据库会尝试创建两次 id_rso 列，从而导致“列已存在”的错误。

foreignId 的正确使用姿势

foreignId() 方法的引入，正是为了简化外键的定义过程。它封装了创建列和添加约束的逻辑，使得代码更加简洁和语义化。

要解决上述“重复列”错误，正确的做法是只使用 foreignId()->constrained() 方法来定义外键列。此方法会智能地完成以下两步操作：

1. 创建与关联表主键类型兼容的 UNSIGNED BIGINT 类型列。
2. 为该列添加外键约束，指向指定表的主键。

代码示例与对比

错误的迁移代码（导致重复列错误）：

// app/database/migrations/xxxx_xx_xx_xxxxxx_create_dso_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateDsoTable extends Migration
{
    public function up()
    {   
        Schema::enableForeignKeyConstraints(); // 启用外键约束，通常推荐保留
        Schema::create('dso', function (Blueprint $table) {
            $table->string('id_dso', 30);
            $table->unsignedBigInteger('id_rso'); // 错误：此行不应与 foreignId 同时使用
            $table->foreignId('id_rso')->constrained('rso'); // 正确：但与上一行重复
            $table->smallInteger('id_focus');
            $table->smallInteger('id_wilayah');
            $table->smallInteger('id_grup_wilayah');
            $table->string('nama_dso', 50);
            $table->string('created_by', 50)->nullable();
            $table->timestamp('created_date', $precision = 0);
            $table->string('modified_by', 50)->nullable();
            $table->timestamp('modified_date', $precision = 0)->nullable()->default(null);
            $table->boolean('status')->default(true);
            $table->timestamps(); // 添加 created_at 和 updated_at
            $table->primary('id_dso');
        });
    }

    public function down()
    {
        Schema::dropIfExists('dso');
    }
}

修正后的迁移代码（避免重复列错误）：

// app/database/migrations/xxxx_xx_xx_xxxxxx_create_dso_table.php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateDsoTable extends Migration
{
    public function up()
    {   
        Schema::enableForeignKeyConstraints(); // 启用外键约束，通常推荐保留
        Schema::create('dso', function (Blueprint $table) {
            $table->string('id_dso', 30);
            // 只使用 foreignId() 来定义外键列，它会自动创建 UNSIGNED BIGINT 类型的列并添加约束
            $table->foreignId('id_rso')->constrained('rso'); 
            $table->smallInteger('id_focus');
            $table->smallInteger('id_wilayah');
            $table->smallInteger('id_grup_wilayah');
            $table->string('nama_dso', 50);
            $table->string('created_by', 50)->nullable();
            $table->timestamp('created_date', $precision = 0);
            $table->string('modified_by', 50)->nullable();
            $table->timestamp('modified_date', $precision = 0)->nullable()->default(null);
            $table->boolean('status')->default(true);
            $table->timestamps(); // 添加 created_at 和 updated_at
            $table->primary('id_dso');
        });
    }

    public function down()
    {
        Schema::dropIfExists('dso');
    }
}

通过移除 unsignedBigInteger('id_rso') 这一行，我们确保了 id_rso 列只被定义一次，从而避免了 Duplicate column name 错误。

理解 foreignId 的内部机制

foreignId() 方法是 Laravel 框架为了提高开发效率而提供的一个语法糖。它默认会生成一个名为 [column_name] 的 UNSIGNED BIGINT 类型列。当与 constrained() 方法链式调用时，它会进一步：

1. 自动推断关联表的名称。如果 constrained() 没有参数，它会尝试根据列名（例如 id_rso）推断出表名（rso）。
2. 将外键约束指向关联表的主键（通常是 id）。

如果你需要更精细地控制外键列的类型或约束，例如关联的不是 id 列，或者需要自定义外键名称，你仍然可以使用传统的 unsignedBigInteger()->foreign()->references()->on() 链式调用。但对于大多数标准的外键关联，foreignId()->constrained() 是最推荐和简洁的方式。

注意事项与最佳实践

• Schema::enableForeignKeyConstraints(): 在 up() 方法中调用 Schema::enableForeignKeyConstraints() 是一个好的习惯，尤其是在执行复杂迁移（如先删除表再创建，或者涉及大量外键操作）时，它可以确保外键约束在操作完成后被重新启用，避免数据不一致。虽然它不是导致本例中重复列错误的直接原因，但它是数据库迁移中的重要组成部分。
• 迁移顺序： 在定义外键时，务必确保被引用的表（例如本例中的 rso 表）的迁移文件在引用表（dso 表）的迁移文件之前运行。Laravel 会根据迁移文件名中的时间戳来决定执行顺序。
• 回滚操作： 在 down() 方法中，通常建议使用 Schema::dropIfExists('table_name') 来安全地回滚迁移。对于外键，Laravel 会在删除表时自动处理其相关的外键约束。

总结

当在 Laravel 迁移中遇到“重复列”错误，尤其是在定义外键时，首先检查是否同时使用了 unsignedBigInteger() 和 foreignId() 来定义同一个列。记住，foreignId() 方法已经包含了创建 UNSIGNED BIGINT 列的逻辑，因此只需使用 foreignId()->constrained('关联表名') 即可正确且简洁地定义外键。遵循这一最佳实践，将有助于避免常见的迁移错误，并使你的 Laravel 数据库操作更加顺畅和高效。