作为一个写代码写了十来年的老家伙，我深知“数据库反向生成实体”这几个字的含金量。尤其是当项目表数量动辄几十上百张，手写实体类纯属给自己上刑。SmartDapper.UI 就是干这个的。它本质上是一个可视化代码生成器，连上数据库，勾选表，点几下鼠标，一套整齐的实体类代码就给你吐出来了。这篇文章我不会给你讲那些虚头巴脑的架构，就实打实地拆解一下这个工具的设计逻辑、核心实现，以及我在实际开发中踩过的那些坑，希望能给正在折腾类似工具或者想提升开发效率的朋友一些参考。
1. 做这个工具之前，我每天都在跟实体类较劲
1.1 手写实体类的“三座大山”
我相信大部分 .NET 开发者都有过这种经历：数据库设计文档倒是挺全，但真正要落地写代码的时候，看着那几十张表，心里就开始发怵。第一座大山是重复劳动，无非就是public int Id { get; set; }这种属性定义，一张表少说七八个字段，多则二三十个，全手敲下来，手指头都能磨出茧子。第二座大山是极易出错，字段类型对应错、可空标记漏掉、字段名大小写不规范，这些问题在编译期根本发现不了，等程序跑起来报 SqlException 的时候，你再去一行行对数据库结构，那种感觉很酸爽。第三座大山是维护困难，数据库结构一变更，实体类就得手动同步，万一忘了，运行时就是各种奇怪的映射错误。
我们当时项目用的是 SmartDapper 这套轻量级 ORM 框架，它本身很灵活，SQL 执行和控制力都很好，但缺点也明显，就是实体类写法比较规范，比如字段名驼峰命名、可空类型必须标注清晰，否则映射就会出问题。团队里新来的同学经常因为实体类写得不规范导致各种隐晦的 bug，排查起来特别费劲。
1.2 SmartDapper 的定位与实体类的“规范枷锁”
SmartDapper 说白了就是一个介于原始 ADO.NET 和重量级 ORM（比如 EF Core）之间的东西。它不会帮你自动管理实体跟表的关系，而是让你自己写 SQL，然后通过自定义的映射规则，把查询结果动态绑定到实体对象上。这种方式自由度极高，特别适合查询逻辑复杂、需要精细控制 SQL 的团队。
但也正因为这个“自由度”，反向生成实体类的要求就变得异常严格。你得保证：实体类名跟表名能对应上，属性名跟字段名能对应上，类型必须完全匹配。比如数据库里某个字段是decimal(18,2)，你给映射成double，查出来的金额可能就出现精度偏移了。再比如datetime2这种类型，如果实体里用的是老旧的DateTime，虽然大部分情况下能兼容，但遇到边界值就很容易踩坑。
所以 SmartDapper.UI 这个工具核心任务，不只是生成一堆{ get; set; }那么简单，它得深入理解数据库的元数据结构，然后通过严谨的规则生成一套完全适配 SmartDapper 映射要求的实体代码。这让它天然区别于网上那种千篇一律的 T4 模板，后者只能生成一个“能用”的壳，而我们追求的是“好用”且有规范保障的实体层。
1.3 为什么非要加个 “UI” 界面
有人可能会问，命令行工具dotnet tool或者脚本不也能生成吗，加个 UI 是不是有点多余？其实不然。我们团队早期确实用过命令行版本的代码生成器，但很快发现了问题：参数太多太抽象，比如要手动指定连接字符串、命名空间、要排除哪些表，一不小心记不住参数就会写错。而且命令行工具是“黑盒”操作，生成前看不到数据库里的实际表结构，心里没底。
后来我们决定做一个带界面的版本，核心诉求就三个：第一，能实时看到数据库里的表清单和字段预览，做到“所见即所得”；第二，所有配置选项都是勾选式的，降低上手门槛，新同学培训十分钟就能用；第三，生成结果可以即时预览，不满意直接调整规则重新生成。这个“可视化交互”的思路，就是 SmartDapper.UI 与普通代码生成器最大的区别。
2. 核心设计思路：反向生成这件事到底怎么落地
2.1 从建连到出码的完整链路
先梳理一下 SmartDapper.UI 的核心工作流程，这条链路是所有功能的骨架，理清它，你就明白这个工具在设计层面的取舍。
第一步是连接数据库。工具通过 ADO.NET 的标准连接方式，支持 SQL Server、MySQL、PostgreSQL、Oracle 等主流数据库。连接字符串不用手写，通过界面拆分成“服务器地址”“数据库名”“账号密码”等独立字段，自动拼接。这样做的好处是屏蔽了不同数据库之间连接字符串写法的差异。比如 SQL Server 要指定Data Source、Initial Catalog，而 MySQL 则是Server、Database，如果让用户自己填，很容易因为格式问题连接不上。
第二步是读取元数据。连接成功后，工具会从数据库的信息模式（如 SQL Server 的INFORMATION_SCHEMA视图，MySQL 的information_schema.COLUMNS表，PostgreSQL 的pg_catalog系列视图）中，把所有表、视图、字段、主键、外键、默认值等信息抓取并缓存起来。这里有个细节，不能直接 SELECT * 去读表数据，因为数据可能很大，而且我们只需要结构，不需要内容。
第三步是规则映射。读取到的原始字段类型、名称、可空性，需要转换成 C# 的类型、属性名和特性标注。这一步就是工具的核心逻辑，涉及一套映射配置，后面会详细说。
第四步是代码生成。基于映射结果，使用模板引擎拼接出完整的实体类代码。这里没有用 T4，因为 T4 的语法对非 Windows 环境不够友好，而且在 UI 程序里嵌入调用麻烦。我们用的是一个轻量级模板引擎，几乎就是把常见的代码片段固化下来，然后用模型数据去渲染。
第五步是预览与导出。生成结果先在 UI 右侧的文本预览区展示，确认没问题后，可以一键把所有文件输出到指定目录，并且按文件夹分好类。
2.2 类型映射表：数据库类型到 C# 类型的换算规则
说到 “类型映射”，这是整个反向生成的核心技术点。数据库里的类型五花八门，跟 C# 的类型并不是一一对应的，稍有不慎就会生成出运行期才爆雷的代码。我列一下 SmartDapper.UI 里实际采用的映射规则，大家可以对照参考，这部分算是我踩坑踩出来的经验：
| 数据库类型（以SQL Server为例） | C# 类型 | 可空性处理 | 备注说明 |
|---|---|---|---|
| int | int | Nullable<int> 若允许为空 | 常规整型，没问题 |
| bigint | long | Nullable<long> 若允许为空 | 大整型，别用 int 接，会溢出 |
| smallint | short | Nullable<short> 若允许为空 | 小整型，用 int 浪费也不算错，但规范起见用 short |
| tinyint | byte | Nullable<byte> 若允许为空 | 注意范围是 0-255 |
| bit | bool | Nullable<bool> 若允许为空 | 数据库布尔 |
| decimal/numeric | decimal | Nullable<decimal> 若允许为空 | 强制用 decimal，不能用 double/float，精度会丢 |
| money/smallmoney | decimal | Nullable<decimal> 若允许为空 | 同上，金额一律 decimal |
| float | double | Nullable<double> 若允许为空 | 数据库 float 对应 C# double |
| real | float | Nullable<float> 若允许为空 | 数据库 real 对应 C# float |
| date | DateTime | Nullable<DateTime> 若允许为空 | 日期 |
| datetime | DateTime | Nullable<DateTime> 若允许为空 | 老式日期时间 |
| datetime2 | DateTime | Nullable<DateTime> 若允许为空 | 精度更高，用 DateTime 也能存 |
| datetimeoffset | DateTimeOffset | Nullable<DateTimeOffset> 若允许为空 | 带时区时间，别用 DateTime |
| time | TimeSpan | Nullable<TimeSpan> 若允许为空 | 时间段 |
| char/nchar | string | string 本身可空 | 定长字符串 |
| varchar/nvarchar | string | string 本身可空 | 变长字符串，最常用 |
| text/ntext | string | string 本身可空 | 长文本，旧类型，尽量提醒转 nvarchar(max) |
| varbinary/image | byte[] | byte[] 本身可空 | 二进制 |
| uniqueidentifier | Guid | Nullable<Guid> 若允许为空 | 全局唯一标识 |
| xml | string | string 本身可空 | XML 也当字符串处理，省心 |
这里特别注意几点。第一，如果数据库字段允许为空，值类型生成的实体属性就要标注为可空（Nullable<T>），这不仅是为了避免赋值报错，更是为了在 JSON 序列化和业务逻辑里明确传达“可能没值”的语义。第二，decimal的精度和位数，比如decimal(18,2)，不能光生成一个decimal就完事，最好在生成的特性（如[Column(TypeName="decimal(18,2)")]）里体现出来，这样在 EF Core 之类的场景里也能正确建表映射。SmartDapper 虽然不走 EF 那套，但保留这个标注绝对没坏处。
2.3 命名与规范处理：表名转类名，字段名转属性名
类型映射解决了“什么类型”的问题，接下来就要解决“叫什么名字”的问题。数据库里的表名和字段名习惯通常是PascalCase（如UserInfo）或者snake_case（如user_info），甚至有人用全大写加下划线USER_INFO。但 C# 编码规范里，类名和属性名推荐用PascalCase，我们必须有一套健全的转换规则。
SmartDapper.UI 的处理方式分几步。第一步是分词，把表名按_、空格、驼峰边界拆成单词数组。比如product_order_detail会拆成["product", "order", "detail"]，ProductOrderDetail也会拆成同样结果。第二步是规范化，排除掉常见的无意义前缀，比如某些团队习惯表名带t_、tb_前缀，字段名带f_、col_前缀，这块做成可配置选项，用户根据自己公司规范决定去不去掉。第三步是拼接，把处理后的单词首字母大写，然后按PascalCase拼起来，得到最终的类名或属性名。比如product_order_detail最终生成ProductOrderDetail。
但这里还有个细节容易踩坑，就是字段名刚好是 C# 关键字的情况。比如数据库里有个字段叫event（MySQL 很常见），生成public string event { get; set; }必然编译不过。工具的解决方案是自动追加一个@前缀，变成public string @event { get; set; }，这样既保留了原始字段名，又能通过编译。此外还有字段名是date、string、object这类跟类型撞车的情况，处理逻辑一样。
3. 实操之旅：从连库到出码，一步一步来
3.1 第一步：配置数据库连接
打开 SmartDapper.UI，首先看到的就是数据库连接配置面板。这地方没什么花哨的，就是填信息。但有一点比较人性化，它内置了常见数据库的连接串模板。比如你选了 SQL Server，下方会自动生成一个标准连接串占位符，你只需要替换服务器名和数据库名即可；选 MySQL 时，如果本地装了驱动，甚至支持只填Server、UserId、Password三件套，自动补齐其余的默认参数。
连接信息填好以后，务必点一下“测试连接”按钮。我之前见过不少同事，直接跳过测试点击下一步，结果弹出个数据库不存在或者权限不足的报错，又回头改半天配置。这里我建议：如果连接的是生产库或共享开发库，尽量用只读权限的账号去连，工具只读结构，不需要增删改的权限，既安全又不影响他人。
连接成功后，左侧列表会立刻显示当前库中的所有表（默认过滤掉系统表）。有的库表特别多，比如几百张，如果你清楚自己要哪些表，可以直接在顶部搜索框输入关键词模糊过滤，大大提升定位效率。
3.2 第二步：勾选需要生成的表并查看字段细节
在表列表里，每一行前边都有一个复选框，你可以勾选一张表，也可以全选。勾选之后，点击该表名称，右侧的字段预览区会展示这张表的详细结构：列名、数据类型、长度、精度、是否允许为空、是否为主键、默认值、备注信息等。这个预览区域非常有用，它让你在生成代码之前，就能直观核对这张表到底有哪些字段，类型长什么样，避免代码生成完才发现字段不对。
在字段预览区下方，还有一个“字段映射预览”，这个区域更高级。它不是显示原始的数据库字段信息，而是实时显示这张表经过规则转换后，生成的 C# 属性名、C# 类型、可空标注、默认值等。你可以在这里就检查出问题。比如某个字段叫USER_NAME，生成后属性名是否符合你的预期，如果不对，可以去全局规则里调整。
我实际操作时的建议是：先别急着全选所有表，建议先勾选 1 到 2 张比较有代表性的表（比如包含各种数据类型、有主外键关系的表），生成出来预览一下，看看整体效果是否符合团队规范。确认没问题后，再全选所有表批量生成。不要一上来就梭哈，否则生成的几百个实体类里，可能混杂着大量不符合要求的代码，后续返工更痛苦。
3.3 第三步：设置命名空间与生成选项
生成代码之前，需要在右侧配置面板里把参数填好。这一块如果理解透彻，能省很多事。
第一个核心选项是“实体类命名空间”，比如MyProject.Domain.Entities。后续生成的代码里，顶部的namespace就会用这个值。
第二个是“是否生成特性标注”。如果你打算同时使用 EF Core 这类需要特性标注的框架，或者想让自己手写的 SQL 映射器能识别表名映射，建议勾上生成[Table("product_order_detail")]这类特性，确保实体类名和真实表名之间没有歧义。对于 SmartDapper 的使用场景，即使不生成这个特性其实也能正常工作，因为映射规则可以独立配置，但保留它能让实体信息更完整，自文档化程度更高。
第三个是“是否生成可空引用类型标注（NRT）”。如果你的项目开启了 .NET 的 Nullable 上下文（<Nullable>enable</Nullable>），那么所有引用类型属性都会自动加上?，比如public string? Name { get; set; }。这能大幅降低空引用警告，同时提醒调用者注意值可能为空。如果项目还没启用 NRT，这块建议先别勾，不然生成的代码可能编译不通过。
第四个是“是否包含数据库备注”。勾选后，工具会读取字段的扩展属性作为 XML 注释写入实体类中，比如/// <summary> 用户姓名 </summary>。强烈建议勾上，注释就是代码的说明书，后续维护的人（包括三个月后的自己）会感谢你这个决定。
第五个是“只生成数据实体还是同时生成查询对象”。我们后来发现，日常开发中除了直接映射表的实体，经常还需要专门用来接收查询结果的 DTO。SmartDapper.UI 的进阶功能就是支持生成一个“仅包含指定字段”的查询 DTO 类，这在复杂报表查询里很实用，但前提是要在表字段预览区手动勾选需要的字段。默认情况下，这个功能是关闭的，保证初学者的使用简单。
3.4 第四步：批量生成与文件输出
配置都设置好后，点击“生成代码”按钮，工具就会把前面读取到的表结构数据逐一送入模板引擎，渲染出完整代码。这个过程很快就完成了，即使几百张表，也就是一眨眼的功夫。生成的代码在右侧预览区默认展示第一张表的实体类。
预览区下面有个“选择查看其他实体”的下拉框，可以快速切换查看不同表的生成结果。确认一切无误后，点“导出到文件夹”，选择一个空目录，工具会按照“每个实体一个 .cs 文件”的方式输出，文件命名跟类名保持一致。如果你的项目是按模块分的文件夹，还可以在导出时设置“子文件夹前缀”，比如把跟order相关的实体批量放进Orders子目录，这个功能在处理大型项目时尤其好用。
文件导出后，我建议你第一时间把整个目录拖进 IDE 里编译一遍，看看有没有生成错误。虽然工具已经内置了很多防护措施，但毕竟数据库的类型是千奇百怪的，总有一些你没见过的情况可能导致模板渲染出错或者生成代码不合规。编译是最直接的验证手段。
4. 问题排查与避坑手册：那些年我踩过的反向生成大坑
4.1 最容易踩到的六类问题
根据我的实际使用和给团队做内训的经历，用这类工具最容易踩的坑，基本集中在下面几类，我整理成表格方便速查：
| 问题现象 | 根本原因 | 排查思路与解决方案 |
|---|---|---|
| 生成的属性类型跟数据库对不上 | 自定义类型、枚举列、或者数据库版本的差异，导致工具无法识别 | 打开字段映射预览，手动修正该字段的 C# 类型；工具里支持“自定义类型映射字典”来解决不常见类型 |
| 部分表在列表里看不到 | 连接账号的权限不足，只能看到部分表；或者工具默认过滤了视图 | 检查账号权限；在工具设置里打开“显示视图”选项 |
生成代码里字符串没加?（可空标注丢失） | 项目启用了 NRT，但生成选项没勾选 | 去生成选项勾选“生成可空引用类型标注”，重新生成 |
| 表名或字段名带特殊字符，生成的代码编译报错 | 名称包含$、#、空格，或者直接就是关键字 | 工具会自动追加@前缀或转义字符，但如果手动建表不规范，需要先在数据库端改掉名字 |
| decimal 字段生成后变成了 double | 映射规则里没配置，走了默认值分支 | 在类型映射配置页里，把所有decimal/numeric统一映射到decimal |
| 同一张表批量生成多次后代码文件重复 | 输出目录没清空，或生成时没选“覆盖模式” | 导出时选择“清空目录后导出”或确认覆盖选项，避免文件堆积 |
上面这些坑，每一个我都亲眼见过团队里的同事踩过，而且几类问题还经常交叉出现，排查起来确实很费精力。最有效的预防手段就是前面提到的：先小范围生成，预览确认规范后再批量生成。
4.2 实测案例：同名字段在不同数据库中的表现差异
不得不说，同一个工具连不同数据库，也会因为数据库本身的特性而出现一些意想不到的差异。举个例子，我们一个项目同时用了 SQL Server 和 PostgreSQL 两套库。
SQL Server 里的uniqueidentifier类型生成的 Guid 属性一点问题没有。但 PostgreSQL 里对应的类型叫uuid，我们的类型映射里没提前配置，结果生成出来的属性类型成了string，虽然能用，但总感觉不够优雅，而且跟 SQL Server 那边的实体类型不一致，导致跨库数据迁移时还需要特判。
还有一个差异点是默认值的处理。SQL Server 的表字段默认值会在元数据里显示为((getdate()))，而 PostgreSQL 则是now()。如果我们直接把默认值当成常量生成到代码里，那肯定是不对的。这里工具做了“智能判断”—— 检测到getdate()、now()、CURRENT_TIMESTAMP这类函数默认值，就在生成的代码里加一个DateTime.Now的属性初始值，而不是把函数体本身塞进去。这个细节，是我们在几次版本迭代之后才打磨完善的，做类似工具的朋友可以留意下这个点。
4.3 版本迭代中的经验沉淀
开发 SmartDapper.UI 的过程中，我最大的体会是：这类工具没有完美的“一键生成”，它永远需要跟着团队的编码规范演进。第一版只做了基础的类型映射和命名转换，后来我们引入了 NRT，马上就发现需要适配可空标注。再后来有的团队开始从 Dapper 迁移到 EF Core，我们发现生成的实体类还需要加上主键特性[Key]。每次需求变化，都意味着工具要加新的选项、新的规则。
所以，如果你们团队也想搞一个内部的反向生成工具，我的建议是不要一开始就追求功能大而全，先把最基础的“生成可用的实体类”这条链路跑通，然后通过收集使用反馈不断迭代。最重要的是把“规则”和“模板”做成可配置、可替换的，否则改一个命名规范就得改核心代码，那后面会非常痛苦。SmartDapper.UI 的内部设计中，类型映射和命名规则都做成了独立的规则引擎，通过 JSON 配置就能调整，这一点为后期维护省了太多力气。
我个人在实际使用中最喜欢的一个小功能是“生成前后差异对比”。因为我的表结构经常微调，字段加加减减，如果重新生成整个实体类，就等于把我手工改过的代码也覆盖了。后来工具加了一个“对比生成”功能，它会把新生成的代码和本地的旧文件做差异对比，只把结构变化的部分高亮显示，我就能精准知道哪里变了，再决定要不要手动改回去。这个小功能听起来不起眼，但确实能省掉很多次误操作的恢复时间。
最后再分享一个经验：代码生成工具是提升效率的利器，但它也是一把双刃剑。它生成的代码质量，完全取决于你给它配置的规则质量。使用的时候一定要带着“审查”的心态去看生成的代码，不要盲目相信工具的输出。毕竟，数据库设计好不好，字段命名规不规范，这些底层的质量问题，工具没法帮你解决。它只是帮你把“差劲的数据库结构”翻译成“差劲的实体类代码”的过程变得更快了而已。工具的价值在于自动化，而好的实体类设计，永远需要人来把控。
