migration-workflow

迁移工作流

核心原则

1. 应用前先检查 — 应用到任何数据库之前，务必先检查生成的迁移 SQL。dotnet ef migrations script 会显示确切的 SQL。切勿盲目应用。
2. 始终准备回滚方案 — 每次迁移都要有回滚方案。对于 EF Core：dotnet ef database update <PreviousMigration>。对于包：使用 git revert。对于 .NET 版本：通过分支回滚。应用前先记录回滚方案。
3. 迁移后测试 — 每个迁移步骤后都要运行完整测试套件。会导致测试失败的迁移尚未完成。使用 Testcontainers 的集成测试可以发现真实的数据库问题。
4. 每次迁移只做一项更改 — 每个 EF Core 迁移都应对应一项逻辑更改（添加表、重命名列、添加索引）。在一次迁移中包含多项无关更改，会让回滚变得不可能。
5. 增量更新 — 一次更新一个包，然后构建、测试。一次更新一个目标框架，然后构建、测试。切勿批量处理无关更改 — 出现问题时，你需要知道是哪个更改导致的。

模式

EF Core 迁移工作流

安全创建和应用数据库迁移的分步工作流。

步骤 1：检查当前状态

# List all migrations and their status
dotnet ef migrations list --project src/Infrastructure --startup-project src/Api

# Verify the database is at the expected migration
dotnet ef database update --project src/Infrastructure --startup-project src/Api -- --dry-run

步骤 2：创建迁移 使用能说明更改内容的描述性名称，而不是实体名称：

# GOOD — Describes the change
dotnet ef migrations add AddOrderShippingAddress --project src/Infrastructure --startup-project src/Api
dotnet ef migrations add RenameCustomerEmailToContactEmail --project src/Infrastructure --startup-project src/Api
dotnet ef migrations add AddIndexOnOrderCreatedAt --project src/Infrastructure --startup-project src/Api

# BAD — Describes the entity, not the change
dotnet ef migrations add Order
dotnet ef migrations add UpdateCustomer

步骤 3：检查生成的 SQL

# Generate the SQL script for review
dotnet ef migrations script --idempotent --project src/Infrastructure --startup-project src/Api

# Or generate from a specific migration
dotnet ef migrations script PreviousMigration AddOrderShippingAddress --project src/Infrastructure --startup-project src/Api

检查以下内容：

• ⚠️ 数据丢失：DROP COLUMN、DROP TABLE、会导致精度损失的列类型更改
• ⚠️ 长时间锁定：对大型表执行 ALTER TABLE，但未并发创建索引
• ⚠️ 默认值：新增的非空列需要为现有行设置默认值

步骤 4：处理数据丢失警告 如果 EF Core 警告可能存在数据丢失：

// In the migration file — explicitly handle data transformation
protected override void Up(MigrationBuilder migrationBuilder)
{
    // Step 1: Add new column as nullable
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);

    // Step 2: Copy data from old column
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");

    // Step 3: Make non-nullable after data is copied
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);

    // Step 4: Drop old column
    migrationBuilder.DropColumn("Email", "Customers");
}

步骤 5：应用并验证

# Apply to development database
dotnet ef database update --project src/Infrastructure --startup-project src/Api

# Run tests to verify
dotnet test

步骤 6：回滚（如有需要）

# Rollback to previous migration
dotnet ef database update PreviousMigrationName --project src/Infrastructure --startup-project src/Api

# Remove the failed migration from code
dotnet ef migrations remove --project src/Infrastructure --startup-project src/Api

NuGet 依赖项更新工作流

安全更新 NuGet 包且不破坏构建的流程。

步骤 1：审核当前状态

# List all outdated packages
dotnet list package --outdated

# Check for vulnerable packages
dotnet list package --vulnerable

步骤 2：对更新分类

• 补丁更新（1.0.0 → 1.0.1）：安全，仅包含错误修复。一次性更新所有补丁版本。
• 次要版本更新（1.0.0 → 1.1.0）：通常安全，包含新功能。一次更新一个。
• 主要版本更新（1.0.0 → 2.0.0）：预计存在破坏性更改。一次更新一个，并阅读发行说明。

步骤 3：增量更新

# Patch updates — batch is safe
dotnet outdated --upgrade Patch

# Minor updates — one at a time
dotnet add src/Api/Api.csproj package Serilog.AspNetCore --version 9.1.0
dotnet build
dotnet test

# Major updates — one at a time with careful review
dotnet add src/Api/Api.csproj package WolverineFx
dotnet build  # Fix compilation errors
dotnet test   # Fix behavioral changes

步骤 4：参考包推荐 添加新包前，请检查 knowledge/package-recommendations.md：

• 是否有内置的 .NET 替代方案？（例如，使用 HybridCache，而非第三方缓存）
• 该包是否在积极维护？
• 它是否符合 kit 的推荐？

步骤 5：验证

dotnet build   # Clean compilation
dotnet test    # All tests pass

.NET 版本迁移工作流

从较旧的 .NET 版本升级到 .NET 10 的结构化流程。

步骤 1：评估当前状态

→ get_project_graph
  List all projects and their target frameworks.
  Flag: mixed TFMs, test projects on different versions.

步骤 2：迁移前检查清单

• 当前版本上的所有测试均通过
• 没有待处理的 EF Core 迁移
• 已检查依赖项与 .NET 10 的兼容性
• 已为迁移工作创建分支

步骤 3：更新 global.json

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestMinor"
  }
}

步骤 4：更新目标框架 更新每个 .csproj（如果统一配置，则更新 Directory.Build.props）：

<PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <LangVersion>14</LangVersion>
</PropertyGroup>

步骤 5：更新包

# Update all Microsoft.* packages to 10.x
dotnet outdated --upgrade Major --include Microsoft.*
dotnet build  # Fix compilation issues

步骤 6：采用新功能 参考 knowledge/dotnet-whats-new.md：

• 将 DateTime.Now/DateTime.UtcNow 替换为 TimeProvider
• 使用 HybridCache，而非 IDistributedCache
• 在适用情况下，将类转换为主构造函数
• 使用集合表达式：int[] x = [1, 2, 3]
• 在属性访问器中使用 field 关键字

步骤 7：验证

dotnet build                    # Clean build
dotnet test                     # All tests pass
dotnet format --verify-no-changes  # Formatting consistent

然后运行 project-setup 技能中的健康检查工作流，以建立新的基线。

反模式

未检查 SQL 就应用迁移

# BAD — Blindly applying
dotnet ef database update
# Oops, dropped a column with 10 million rows of data

# GOOD — Review first, then apply
dotnet ef migrations script --idempotent > review.sql
# Read review.sql, check for DROP, ALTER, data loss
dotnet ef database update

一次性更新所有包

# BAD — Update everything, pray it works
dotnet outdated --upgrade Major
dotnet build  # 47 errors — which package caused this?

# GOOD — One at a time, build after each
dotnet add package WolverineFx
dotnet build && dotnet test  # ✅
dotnet add package Serilog --version 5.0.0
dotnet build && dotnet test  # ❌ — Serilog 5.0 broke the sink config

迁移后跳过测试

# BAD
dotnet ef database update  # "It compiled, ship it"

# GOOD
dotnet ef database update
dotnet test  # Run FULL test suite, especially integration tests
# Integration tests with Testcontainers will catch schema mismatches

在一次迁移中包含多项无关更改

# BAD — Three unrelated changes in one migration
dotnet ef migrations add UpdateEverything
# Contains: new table + renamed column + dropped index
# Rollback is all-or-nothing for three unrelated changes

# GOOD — One change per migration
dotnet ef migrations add AddShippingAddressTable
dotnet ef migrations add RenameCustomerEmailColumn
dotnet ef migrations add DropUnusedOrderIndex
# Each can be rolled back independently

决策指南

场景	工作流	关键步骤
新建数据库表	EF Core 迁移	创建实体 + 配置 + 迁移
重命名列	EF Core 迁移	检查 SQL，确保保留数据
添加索引	EF Core 迁移	检查大型表是否会出现长时间锁定
数据转换	EF Core 迁移 + 原始 SQL	使用 SQL 语句自定义 Up()
过时的包	NuGet 更新	每次更新一个包，每次更新后都进行构建和测试
有漏洞的包	NuGet 更新（紧急）	立即更新、测试并部署
.NET 版本升级	.NET 迁移	分阶段进行，共 1-4 阶段，每个阶段都进行验证
添加新包	NuGet 更新	先检查 package-recommendations.md
ExecuteUpdateAsync 与迁移的选择	视情况而定	迁移用于架构；ExecuteUpdateAsync 用于运行时批量更新数据
修改现有迁移	如果已应用，绝不可修改	改为创建新的迁移