在 APIATO（基于 Laravel）中修改已存在的数据库表时，应避免使用 migrate:fresh 清空全部数据；正确做法是创建新的迁移文件，通过 Schema::table() 对原表进行增量变更，确保历史数据完整保留。
在 apiato 框架中修改已存在的数据库表时，应避免使用 `migrate:fresh` 清空全部数据；正确做法是创建新的迁移文件，通过 `schema::table()` 对原表进行增量变更，确保历史数据完整保留。
APIATO 是一个基于 Laravel 构建的面向 API 的分层架构框架，其数据库迁移机制完全继承自 Laravel。当你已完成初始迁移（如 php artisan migrate）并生成了生产级数据后，绝对不应直接修改已提交的旧迁移文件（如 2023_01_01_000000_create_users_table.php），因为这会破坏迁移历史一致性，导致团队协作异常、线上环境无法安全回滚，甚至引发数据丢失风险。
✅ 正确做法：使用“增量迁移”（Incremental Migration）
为修改现有表结构（例如添加字段、修改列类型、添加索引或外键），请始终执行以下步骤：
-
生成新迁移文件
php artisan make:migration add_phone_to_users_table --table=users
✅ 提示：--table 参数仅作语义提示，不影响实际逻辑；Laravel 不会自动关联表名，需手动编写。
-
在新迁移的 up() 方法中使用 Schema::table()
// database/migrations/2024_05_20_100000_add_phone_to_users_table.php public function up(MigrationBuilder $migration): void { Schema::table('users', function (Blueprint $table) { $table->string('phone')->nullable()->after('email'); $table->index('phone'); // 可选：添加索引 }); } public function down(MigrationBuilder $migration): void { Schema::table('users', function (Blueprint $table) { $table->dropColumn('phone'); }); } -
运行迁移
php artisan migrate
此命令仅执行未运行过的迁移（包括你刚创建的），完全保留所有已有数据，且支持 migrate:rollback 安全回退。
⚠️ 重要注意事项：
- 不要在 up() 中调用 Schema::create() 或 Schema::dropIfExists() 操作已有表，这属于破坏性操作；
- 修改列类型（如 change()）需安装 doctrine/dbal 扩展（Laravel 要求）：
composer require doctrine/dbal
然后在迁移中使用：
$table->string('name', 100)->change(); // 修改长度 - 在 APIATO 中，迁移文件建议统一放在 app/Ship/Migrations（若项目已启用 Ship 层迁移路径），但底层仍由 Laravel 迁移器加载，路径配置需与 config/database.php 中的 migrations 项一致；
- 生产环境部署前，务必在预发布环境充分测试 up() 和 down() 的幂等性与数据安全性。
总结：APIATO 的数据库演进应遵循“不可变迁移历史 + 增量变更”原则。每一次结构调整都对应一个独立、可逆的新迁移文件，这是保障数据安全、团队协同和系统可维护性的基石。
