企业官网建设流程全解析

干 .NET 的这些年，我最怕遇到的项目不是没有文档的，而是那种“数据库已经跑了好几年，代码层却一穷二白”的系统。表七八十张、外键四面八方、索引一大把，业务却天天在变。你问团队要不要上 .NET 数据库迁移框架，他们只会反问：迁移框架不是给新建项目用的吗？现有库怎么迁移？

这里就牵出一个很关键的词——自动逆向迁移。它指的是：框架能从一张已经存在的数据库结构里，自动反推出实体类、DbContext 配置，甚至把当前结构登记成初始迁移版本。换句话说，你不用从零写代码，也不用一个个手敲表映射，框架帮你把数据库“翻译”回 C#，然后让所有后续的结构变更都进入版本管理。我这两年带团队重构，凡是从老系统搬数据层，靠的都是这套思路。

在 .NET 生态里，能把“自动逆向迁移”这条链路做得最顺手的，我首推 Entity Framework Core（EF Core）——准确说是它的 Scaffold 命令加上 Migrations 体系的组合。这篇文章会把为什么选它、命令怎么用、生成完怎么精修、遇到坑怎么排，全部写清楚。适合想给老项目补数据层、或者想把数据库优先项目平滑切换成代码优先的朋友参考。

1. 为什么说“自动逆向迁移”是刚需

1.1 先分清两种“迁移方向”

在 .NET 里聊数据库迁移，很多人第一反应是 Code First：写实体类，跑 Add-Migration，生成 SQL，Update-Database。这是“正向迁移”。它有个隐含前提——数据库结构从零开始由代码驱动。可现实项目里，数据库往往先于代码存在，或者一直由 DBA 独立维护。这时候你需要的不是从代码生成数据库，而是反过来：数据库已经是标准答案，代码要跟着它走。

这个“反过来”就是 Database First / 逆向工程。EF Core 把这项工作标成了dbcontext scaffold，执行后工具会读取数据库元数据（表、列、主外键、索引、约束），生成一组实体类、一个继承自 DbContext 的上下文类，以及对应的 Fluent API 配置。如果再接上migrations add，就等于把现有结构做成一条基线迁移，之后的每次表结构改动都能像 Code First 一样走版本控制、评审和回滚。

这里我多说一句：很多新手以为“逆向迁移 = 用某个工具生成一次代码”，这是个误区。真正有价值的是“生成 + 版本化管理”的组合。如果只生成代码、不做迁移登记，下一次库结构变了，你又要手动重新生成一遍，而且根本不知道谁改了什么、什么时候改的，代码和数据库的一致性完全靠自觉。只有把当前库结构固化成第一条迁移记录，后续所有变更才真正“纳入轨道”。

1.2 谁最需要自动逆向迁移

不是所有人都需要这套能力。我总结过，下面几类场景最典型：

• 老系统重构/数据层重写：数据库结构成熟，业务逻辑驻留在存储过程或 SQL 里，代码层又老又乱，想用现代 ORM 重写数据访问层。这种情况你不可能手工写几百个实体，逆向生成是唯一的现实路径。
• DBA 主导的公司：DBA 掌握数据库设计权，开发团队只负责消费。定期把库结构逆向回代码，能让代码始终与真实库保持一致，而不是靠团队自己“脑补”实体。
• 跨团队切换技术栈：原来用 Java/PHP，库是 MySQL，现在要迁到 .NET。自动逆向一次能把实体全部生成出来，比手写靠谱太多。
• 快速搭脚手架：新项目还没有完整数据层，但数据库模型已经在建模工具里设计好，逆向生成实体做原型，开发效率极高。

核心判断标准就一条：数据库是否先于代码存在，或者数据库是否始终是唯一可信源。是的话，自动逆向迁移就是刚需，不是可选项。

2. 市面主流 .NET 迁移框架横评

2.1 一张表看懂 5 类框架的定位

我经常被问“既然 EF Core 能做，为什么还有人用 FluentMigrator、DbUp”？答案很简单：它们解决的不是同一个问题。EF Core 是 ORM + 迁移一体，FluentMigrator 和 DbUp 是纯粹的“数据库结构版本管理工具”，不关心你怎么访问数据。把它们放在一张表里看，定位差异非常明显：

看完你就能理解，为什么“支持自动逆向迁移”在 .NET 生态里是个稀缺能力。FluentMigrator、DbUp、Evolve 更像“迁移执行器”，它们假设你手里已经有一份可执行的迁移脚本；而 EF Core 直接把“从数据库反推代码”这件事做成了官方命令，这正好戳中了老项目重构的痛点。

2.2 为什么最终我推荐 EF Core 的组合拳

如果你去搜国外社区的讨论，会发现还有不少人推荐“EF Core Power Tools”这个 VS 扩展。它本质上是给 EF Core 逆向工程套了一层可视化界面，能勾选表、预览生成结果、一键覆盖，底层还是dbcontext scaffold。这说明 EF Core 的逆向能力已经不是实验性功能，而是官方维护、生态认可的主力路径。

那为什么不推荐自己拼“T4 模板 + DbUp”呢？我也试过，拼出来是能用，但成本全在后端维护。数据库结构一变，你要重新跑模板、检查生成的代码有没有编译错、确认脚本版本和实体版本对得上，每个环节都要自己写胶水代码。EF Core 的优势在于闭环：scaffold 重新生成代码，migrations 记录差异，database update或migrations script负责落地，三步是一套工具链。出了问题，社区讨论、文档、AI 辅助都能直接命中，排查成本远低于自研方案。

顺带说一句，如果你的项目还停留在 .NET Framework 3.5 那种老环境，这套现代工具链基本跑不起来——dotnet ef要求 SDK 级别的新运行时。建议先把目标框架升到 .NET 6 或 .NET 8（两者都是 LTS），再谈逆向迁移，否则你在老框架里找一个“能自动逆向迁移的框架”，可选空间几乎为零。

3. 实操：让 EF Core 从现有库自动生成整套代码

3.1 环境准备：一条命令装好工具链

首先确保本机有 .NET SDK（建议 6.0 以上，生产环境推荐 .NET 8 LTS）。然后打开命令行安装 EF 工具：

dotnet tool install --global dotnet-ef dotnet ef --version

接着准备一个空项目（类库或 Web 项目都行），我习惯先建类库承载数据层：

dotnet new classlib -n MyApp.Data cd MyApp.Data dotnet add package Microsoft.EntityFrameworkCore dotnet add package Microsoft.EntityFrameworkCore.Design dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Microsoft.EntityFrameworkCore.Design这个包一定不能少，它提供 scaffold 和 migrations 的设计时支持。如果连的是 PostgreSQL，就把 SqlServer 换成Npgsql.EntityFrameworkCore.PostgreSQL；MySQL 则常用Pomelo.EntityFrameworkCore.MySql。工具版本尽量和项目包版本保持一致，否则偶尔会出现一些很魔幻的行为差异，比如“找不到 provider”之类的提示。如果你遇到 NuGet 拉包失败、网络超时报错，先检查 NuGet 源是否可达，基本都能定位。

3.2 反向前，先“读库”三件事

动手前不要急着敲命令，先把数据库摸清楚。我每次都会做三件事：

1. 确认 schema：SQL Server 默认是 dbo，PostgreSQL 可能还有多个 schema。你生成的实体落在哪个命名空间，连接串怎么配，都受这个影响。
2. 圈出表范围：系统表（比如__EFMigrationsHistory）、日志表、临时表都要排除。用-t参数只挑业务表，避免生成一堆用不上的实体文件。
3. 标记特殊对象：视图、无主键表、计算列、rowversion 列，这些对象在逆向时可能要手动补 Key 或加额外配置。

我第一次逆向一个 200 多张表的老库，没过滤直接跑，生生生成了 400 多个类文件。结果一半没用上，编译还因为无主键表出现问题。后来我把习惯改成：先从information_schema里拉一遍表清单，把模块相关的表分批选出来，再生成。这个过程不需要多聪明，就是多看几眼，能省后面好几个小时的清理时间。

3.3 scaffold 命令逐参数拆解

核心命令（SQL Server 示例）长这样：

dotnet ef dbcontext scaffold \ "Server=.;Database=ShopDB;User Id=sa;Password=YourPass;TrustServerCertificate=True" \ Microsoft.EntityFrameworkCore.SqlServer \ --output-dir Models \ --context-dir Data \ --context ShopDbContext \ --namespace MyApp.Models \ --context-namespace MyApp.Data \ --table Orders --table Customers --table OrderItems \ --no-onconfiguring \ --use-database-names \ --data-annotations \ --force

每个参数都有它存在的理由，我挑重点说：

关于连接串还有一个安全小技巧：别把连接串直接写在命令里，命令历史会把它记下来。Linux/macOS 可以这样：

export CONN="Server=.;Database=ShopDB;User Id=sa;Password=YourPass;TrustServerCertificate=True" dotnet ef dbcontext scaffold "$CONN" Microsoft.EntityFrameworkCore.SqlServer --output-dir Models ...

Windows PowerShell 则用$env:CONN="..."。生成完之后记得从环境变量里清掉。这个细节不算难，但踩过密码被提交到 Git 历史这种坑的人都知道多难受。

3.4 生成之后：把现有库登记为迁移基线

Scaffold 出来的实体和 DbContext，本质上是一份“快照”，不是“迁移”。要让这套代码变成可延续的版本管理体系，还需要三步。

第一步，把连接串挪到配置文件里。如果生成时没加--no-onconfiguring，生成的 DbContext 里会有一段optionsBuilder.UseSqlServer("...")，这行代码里的密码会跟着你进代码库，必须删掉或改成从appsettings.json读取。

第二步，在程序入口注册 DbContext：

builder.Services.AddDbContext<ShopDbContext>(opt => opt.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

第三步，生成基线迁移：

dotnet ef migrations add InitialCreate

这里是个大坑，我必须单独拎出来讲：如果数据库已经存在且结构一致，直接跑dotnet ef database update会把所有 CreateTable 再执行一遍，报“对象已存在”。正确做法是，在已有库上先把这条迁移“登记”进历史表，而不实际执行建表：

INSERT INTO __EFMigrationsHistory (MigrationId, ProductVersion) VALUES (N'20240101000000_InitialCreate', N'8.0.0');

MigrationId 里的时间戳前缀要和实际生成的迁移文件名一致，ProductVersion 填你用的 EF Core 版本。之后所有结构变更都正常走 Add-Migration + database update，空环境部署时 InitialCreate 仍负责全量建表，两条路径互不干扰。这个技巧我在多个项目里验证过，是最省心的基线接入方式。

4. 逆向生成只是开始，二次精修才是交付关键

4.1 先定目录，再动手改

Scaffold 生成的代码有很明显的“机器味”，表现在命名统一但琐碎、配置全部堆在 OnModelCreating 里、实体和配置混在一个目录。为了长期维护，我建议生成之后立刻整理成固定结构：

MyApp.Data/ ├── Entities/ # 实体类，尽量保持生成原样 ├── Configurations/ # 独立的 IEntityTypeConfiguration 配置类 ├── Migrations/ # 迁移文件 └── ShopDbContext.cs

具体做法：把实体按业务命名整理到 Entities 目录；把 OnModelCreating 里那一大坨 Fluent API 拆到各个XxxConfiguration.cs文件里，然后在 OnModelCreating 最顶部加一行：

modelBuilder.ApplyConfigurationsFromAssembly(typeof(ShopDbContext).Assembly);

这行代码会自动扫描程序集里所有IEntityTypeConfiguration实现，逐个应用。以后每个表一份配置，review 的时候只打开对应文件就行，不用在几百行的 OnModelCreating 里翻来翻去。

4.2 用 partial 类给生成代码“留后门”

Scaffold 每次重新生成都会覆盖文件。你如果直接在实体类上加业务属性、注释、辅助方法，下次结构一变重新生成，全没了。我的经验是：实体类保持生成原样，把业务扩展写在 partial 类里。

生成的实体本来就是public partial class Order，你可以在另一个文件里另写一份：

namespace MyApp.Models; public partial class Order { public decimal TotalAmountWithTax => SubTotal + TaxAmount; public bool IsPaid => PaidAt.HasValue; }

这样即使哪天数据库结构变了，重新 scaffold，业务代码也不会被冲掉。同样的逻辑也适用于 DbContext，但 DbContext 我更建议直接手工维护，因为它里面的配置逻辑是高度个性化的，重生成的情况不多。

4.3 高频精修点：精度、并发列、软删除、序列化循环

逆向生成的代码能编译通过，不代表它能直接上线。我在实际项目里几乎每次都要处理下面这几个高频问题：

• decimal 字段精度：数据库里可能定义成numeric(18,2)，但生成的 Fluent 配置不一定带具体精度。SQL Server 下建议手动补HasPrecision(18,2)，否则迁移时可能产生类型不一致的警告。
• rowversion / 并发令牌：如果表里有 rowversion 列，别忘了给对应属性加IsRowVersion()或在实体上加[Timestamp]。漏掉的话，并发更新检测等于没做，线上就会出现“明明按了两次提交结果都成功”的诡异问题。
• 软删除列：很多表有is_deleted或deleted_at，实体生成后不会自动加过滤。你可以在 OnModelCreating 里统一处理：

modelBuilder.Entity<Order>().HasQueryFilter(e => !e.IsDeleted);

• JSON 序列化循环：订单和订单明细互相导航，挂到 WebAPI 上序列化会直接炸。正规做法是返回 DTO，把实体和传输模型分开；临时救急可以在配置里把循环引用忽略掉：

builder.Services.AddControllers() .AddJsonOptions(opt => opt.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles);

但 DTO 才是长久之计，这个别偷懒。

4.4 按业务域拆 DbContext，别一张大表走到黑

200 张表的库如果全塞进一个 DbContext，启动时初始化几百个实体关系，每次迁移生成的文件也又长又难 review，团队协作还容易起冲突。我更建议按业务域拆分：订单域一个OrderDbContext，客户域一个CustomerDbContext，各自独立建 migrations。Scaffold 时用-t参数挑对应的表。

拆的代价是跨域查询不能直接 join，需要通过应用层聚合、接口调用或者数据库视图解决。但它带来的收益非常明显：每条迁移记录变短、模块之间耦合下降、发布能按域独立推进。接手老库重构时，我一般先问清楚这个库会被多少个团队动，再决定拆几个上下文。十个表以内的库不拆，一个库三五个团队动，拆成三五个上下文都不嫌多。

5. 常见问题与排查技巧实录

5.1 症状速查表

逆向迁移过程中遇到的问题，七成都能从下面这张表里找到对应解法：

5.2 我踩过的最深的三个坑

第一个坑是无主键表。老库总有一两张日志表没有主键，Scaffold 会把它们跳过，但报表逻辑还在用。处理办法：要么和 DBA 商量给表补一个自增主键（推荐），要么在代码里用原生 SQL 查询，别硬着头皮生成实体。强扭的瓜不甜，无主键表塞进 EF Core 的状态跟踪体系只会一直出问题。

第二个坑是schema 多且杂。SQL Server 里有sales.orders、log.audit这种带 schema 的表，Scaffold 默认只扫默认 schema，导致漏表。命令里可以加--schema sales --schema log，或者去掉过滤全扫一遍再筛选。生成之后要留意实体上会自动带[Table("orders", Schema = "sales")]，这个特性千万别删，删了映射就错位了。

第三个坑是视图和计算列。视图没有主键是常态，生成出来没 Key 会被 EF 当成没法查询的实体。要么手动指定 HasKey，要么干脆把视图包成一个查询方法，不走 DbSet。计算列更隐蔽——它在读模型里有值，但写模型里不能 Insert 和 Update，EF 默认可能会尝试写入，导致运行时异常。遇到计算列，要在配置里标注ValueGeneratedOnAddOrUpdate()或者DatabaseGenerated相关设置。

5.3 几个值得固化的日常习惯

• 生成代码永远放到独立 Git 分支上做 review。Scaffold 一次可能改动几百个文件，直接往主干推容易淹没其他正常的代码提交。
• 每次重新生成前，先备份当前代码目录，或者先在干净目录跑生成再拷贝回来。--force会覆盖同名文件，你手工精修过的部分可能就没了。
• 生产库发布前，用dotnet ef migrations script输出 SQL，而不是盲跑database update。脚本可以交给 DBA 审，评审通过再执行，这也是很多公司对生产环境的基本要求。
• 数据库结构大改之后，先跑一遍编译 + 短查询，确认 DbContext 还能正常工作，再动业务代码。逆向生成的实体和实际库之间如果有 drift，最好尽早暴露。

6. 我现在的标准工作流模板

如果让我把现在做老库迁移的流程总结成一个可复用的模板，大概是这样的：

1. 环境准备：安装 dotnet-ef，创建数据类库项目，添加 Design 和对应 Provider 包。
2. 读库：拉表清单，圈业务范围，标记无主键表和视图。
3. Scaffold：按模块分批执行，指定表白名单，加--no-onconfiguring和--use-database-names。
4. 整理：拆目录、拆 Configuration、手工补精度、并发列、软删除过滤。
5. 基线：migrations add InitialCreate，已有库手工登记历史记录，不重复建表。
6. 交付：用migrations script生成 SQL 给 DBA 审，同时写一个小自检程序验证 DbContext 能正常查询。
7. 收尾：把数据库当前结构的 DDL 导出一份存档，和第一版迁移脚本放一起，以后如果出现“谁把字段改了”的争议，直接对比存档就行。

这套流程看起来步骤多，但走过一轮后就是肌肉记忆，每次花的时间主要不是敲命令，而是“读库”和“精修”，这两个环节才是决定质量的关键。

我个人体会最深的其实是：自动逆向迁移真正省下的不是那几小时的字段翻译时间，而是让团队重新建立了“数据库结构是唯一事实源”的纪律。数据库改了，代码有明确路径去同步；代码改了，有迁移历史兜底。这种确定性，比任何炫酷框架都值钱。如果你正守着老库犯难，不妨就从今天这条 scaffold 命令开始试。