migrate

/migrate

内容

适用于三种变更类型的统一迁移工作流，其中 EF Core 架构迁移是主要流程：

1. EF Core 架构 — 检查待处理的模型变更，生成描述性命名的迁移，检查 SQL 中的数据丢失和锁定风险，并在应用时记录回滚路径。
2. .NET 版本升级 — 分阶段升级 TFM/SDK/包，并在每个阶段进行验证。
3. NuGet 更新 — 一次更新一个包，逐步进行，以便始终能确定问题的来源。

共同原则：应用前先验证，始终准备回滚计划，每一步之后都要测试，每个迁移只包含一个逻辑变更。

适用场景

• 修改实体类、DbContext 配置或关系之后
• “添加迁移”“更新数据库”“创建迁移”“新建表”“重命名列”
• 生成 SQL 脚本供 DBA 审查时
• “升级到 .NET 10”“版本升级”“.NET 升级”
• “升级 nuget”“更新包”“依赖项更新”、存在易受攻击的包警报时

操作方法

首先对请求进行分类：架构变更 → 流程 A；框架升级 → 流程 B；包更新 → 流程 C。然后从头到尾遵循相应流程。

流程 A：EF Core 架构迁移（主要流程）

步骤 1：评估当前状态

dotnet ef migrations list --project <InfraProject> --startup-project <ApiProject>

检查是否有待处理的迁移，以及未纳入迁移的模型变更。

步骤 2：审查模型变更

使用 MCP 工具，而不是读取整个文件：

find_symbol(name: entity or DbSet)        -- locate the changed entity
get_type_hierarchy(typeName: entity)      -- check TPH/TPT/TPC inheritance changes
find_references(symbolName: property)     -- assess downstream query impact

确认变更属于一个逻辑单元。如果不是，请拆分为多个迁移——混合迁移会导致回滚只能全部执行或全部撤销。

步骤 3：生成迁移

名称应描述变更，而不是实体：Add|Remove|Rename|Modify + WhatChanged。

# GOOD
dotnet ef migrations add AddOrderShippingAddress --project <Infra> --startup-project <Api>
# BAD — names the entity, not the change
dotnet ef migrations add Order

步骤 4：审查生成的 SQL

database update 没有试运行标志——生成幂等脚本并阅读，以预览变更：

dotnet ef migrations script --idempotent --project <Infra> --startup-project <Api>

标记并报告：

• DROP COLUMN / DROP TABLE — 确认数据丢失是有意的
• ALTER COLUMN 类型变更 — 检查是否会造成精度损失或截断
• 对大型表执行 ALTER — 提示锁定时长风险
• 新增不可为 null 的列 — 需要为现有行设置默认值

如果重命名或重新设置类型时必须保留数据，请使用包含原始 SQL 的多步迁移：

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.AddColumn<string>("ContactEmail", "Customers", nullable: true);
    migrationBuilder.Sql("UPDATE \"Customers\" SET \"ContactEmail\" = \"Email\"");
    migrationBuilder.AlterColumn<string>("ContactEmail", "Customers", nullable: false);
    migrationBuilder.DropColumn("Email", "Customers");
}

步骤 5：应用并验证

dotnet ef database update --project <Infra> --startup-project <Api>
dotnet build && dotnet test   # integration tests catch schema mismatches

步骤 6：记录回滚方案

dotnet ef database update <PreviousMigrationName> --project <Infra> --startup-project <Api>
dotnet ef migrations remove --project <Infra> --startup-project <Api>   # if unapplying from code

绝不要修改已应用的迁移——应创建新的迁移。

流程 B：.NET 版本升级

1. 评估 — 使用 get_project_graph 列出所有 TFM；标记版本不一致的情况。
2. 升级前检查 — 所有测试均通过，没有待处理的 EF 迁移，已检查依赖项与目标版本的兼容性，并已创建专用分支（分支本身就是回滚计划）。
3. 更新 global.json — 设置 SDK 版本，并使用 "rollForward": "latestMinor"。
4. 更新 TFM — 在 .csproj 或 Directory.Build.props 中设置 <TargetFramework>net10.0</TargetFramework> 和 <LangVersion>14</LangVersion>。
5. 更新包 — 执行 dotnet outdated --upgrade Major --include Microsoft.*，然后构建并修复问题。
6. 采用新功能 — 根据 knowledge/dotnet-whats-new.md 使用 TimeProvider、HybridCache、主构造函数和集合表达式。
7. 验证 — 执行 dotnet build、dotnet test、dotnet format --verify-no-changes。

流程 C：NuGet 包更新

1. 审计 — 执行 dotnet list package --outdated 和 dotnet list package --vulnerable。存在漏洞的包需要紧急处理：更新、测试、部署。
2. 分类 — 补丁版本（可批量更新）、次要版本（一次更新一个）、主要版本（一次更新一个，并先阅读发行说明）。
3. 逐步更新 — 每次更新一个包，然后在更新下一个包之前执行 dotnet build && dotnet test。批量更新会导致无法确定故障来源。
4. 检查适配性 — 添加新包之前，请查阅 knowledge/package-recommendations.md；优先使用 .NET 内置替代方案。要从 MediatR 迁出（自 v13 起采用商业许可证）？请遵循 knowledge/mediatr-to-mediator-migration.md 中的分步指南。
5. 回滚 — 使用 git revert 撤销包版本升级；绝不要为了弥补问题而降级其他包。

使用的 MCP 工具

• find_symbol / find_references — 定位实体，评估架构更改的影响
• get_type_hierarchy — TPH/TPT/TPC 的实体继承关系
• get_project_graph — 升级版本前审计 TFM
• get_diagnostics — 迁移生成或升级后捕获警告

示例

User: /migrate

Claude: Checking migration state...
  Last applied: 20250710_AddOrderTable
  Model changes detected: new ShippingAddress property on Order entity.

  Creating migration: AddOrderShippingAddress
  Reviewing SQL (dotnet ef migrations script --idempotent)...
  - ALTER TABLE "Orders" ADD "ShippingStreet" text NULL
  - ALTER TABLE "Orders" ADD "ShippingCity" text NULL
  No data loss. No locking risk. Safe to apply.

  Applying migration... Done. Build: green. Tests: 34/34 passed.

  Rollback (if needed):
  dotnet ef database update AddOrderTable --project src/Infrastructure --startup-project src/Api

相关内容

• ef-core — 实体配置、查询模式、迁移内部机制
• /verify — 迁移工作后的完整验证流程
• /checkpoint — 在有风险的迁移前提交一个安全状态