元数据驱动的 ORM 设计报告：从 XML 映射到代码化 Map 体系

本文基于源码分析梳理一套元数据驱动 ORM 的设计：从早期 XML 映射到代码化 Map 体系，再到主从表、外部数据源与自动建表等扩展机制，并给出与主流 ORM 的对比及适用场景建议。

一、缘起与设计目标

1.1 起始于 2002 年

该平台 ORM 设计起始于 2002 年，起因是探索可复用的企业应用框架技术。当时需要一套能够：

• 统一描述「数据表 ↔ 实体类」的映射关系；
• 在多种数据库（SQL Server、Oracle、MySQL 等）上复用同一套业务代码；
• 支撑快速搭建管理类应用（增删改查、列表查询、主从表编辑）。

EntityDBAccess.cs 文件头注释仍保留着创建时间标记：

1.2 设计目标（与市面 ORM 的差异点）

该平台 ORM 从一开始就不是「纯数据访问层」，而是面向企业低代码应用的元数据框架：

这一取向决定了后续 该引擎、该引擎、低代码表单、组织结构等模块均可在同一套元数据上叠加能力，而不必重复定义字段语义。

二、演进历程：XML → Map / Attr / Attrs

2.1 第一阶段：XML 描述映射（约 2002）

早期版本用 XML 文件表达数据表与实体类的完整关系。Map.GenerMap(string xml) 方法至今仍保留这一能力：读取 XML 中的 Base、Attr、SearchAttr、Dtl、Dot2Dot 等节点，动态构建 Map 对象。

XML 方案的优点是映射与代码解耦、便于工具生成；缺点是调试困难、版本管理成本高、缺乏编译期检查。

2.2 第二阶段：Map / Attr / Attrs 类（约 2003）

2003 年，架构改造为以 Map、Attr、Attrs 三个核心类在 C# 代码中描述映射，成为至今沿用的主路径。

实体子类通过重写 EnMap 属性返回自己的 Map 定义。以组织结构中的 Emp（用户）为例：

代码化 Map 带来了编译期类型安全（字段常量类如 EmpAttr）、IDE 跳转、与业务逻辑同仓版本管理等优势，XML 路径退居兼容与工具导入用途。

三、核心架构

3.1 类层次与职责

目录结构（引擎内核命名空间）：

3.2 数据承载：Row 弱类型模型

实体字段值不直接映射为 C# 自动属性，而是存放在 Row（继承 Hashtable） 中，通过 GetValByKey / SetValByKey 读写：

设计意图：

• 低代码场景下字段可运行时增删，无需重新编译实体类；
• 主表、从表、流程表单共用同一套读写 API；
• 业务类仍可封装强类型属性（如 Emp.Name），内部转调 GetValStringByKey。

3.3 持久化流水线

3.4 主键策略

通过实体基类约定主键字段名：

FieldType 枚举进一步区分字段逻辑角色：普通、主键、外键、枚举、主键+外键、关联文本、虚拟字段等。

四、超越字段映射：BP 扩展能力

原始 ORM 仅解决「数据库列 ↔ 实体属性」映射；该平台 BP 层在此基础上扩展为应用元数据框架。

4.1 字段逻辑类型（FieldType / FieldTypeS）

Attr.ToMapAttr 与 MapAttr.HisAttr 构成代码 Map ↔ 库表 MapAttr 双向转换桥梁，使设计态（设计器保存到 Sys_MapAttr）与运行态（GenerMap() 动态生成 Map）保持一致。

4.2 控件类型映射（UIContralType）

Attr 不仅记录 MyDataType（存储类型），还记录 UIContralType（呈现控件）：

• 基础：TB（文本框）、DDL（下拉）、CheckBok、RadioBtn
• 流程/公文：HandWriting（签名）、FrmImgAth（图片附件）、GovDocFile（正文）、JobSchedule（进度图）
• 移动端：MapPin、MobilePhoto、Location

低代码表单设计器将控件配置写入 Sys_MapAttr，运行时 MapDtl.GenerMap() 遍历 MapAttrs 调用 map.AddAttr(mapAttr.HisAttr) 合成完整 Map，从而一份元数据同时驱动持久化与 UI 渲染。

4.3 主表—从表映射（EnDtl）

Map.AddDtl 声明主实体下的从表集合：

• refKey：从表中外键列（如 FK_Node）；
• DtlEditerModel：批量编辑、查询编辑、自定义 URL 等模式；
• 流程表单明细（MapDtl）、组织结构子面板均基于此机制。

4.4 一对多 / 多对多映射（AttrOfOneVSM）

Map.AttrsOfOneVSM 描述「一」端实体与「多」端实体通过中间表（MM 表）的关联，例如用户维护所属部门：

支持树形部门、平铺面板等多种维护 UI（Dot2DotModel），直接生成部门-人员维护界面，无需手写关联 CRUD。

4.5 外部数据源（SFTable / SFDBSrc）

• SFTable：定义下拉/列表的外部数据来源（本库 SQL、跨库、WebService、Java 处理器等）；
• SFDBSrc：多数据源连接配置，使 Map 可指定 DBSrc 指向非本地库；
• 字段通过 UIBindKey 关联 SFTable，实现不建物理外键列也能绑定外部数据的下拉选项。

4.6 自动 DDL（CheckPhysicsTable）

实体在 Insert/Update 失败时可触发 CheckPhysicsTable()：按 Map.Attrs 定义自动创建表或扩展列长。这使低代码「先画表单、后建表」成为可能，也是与「迁移脚本驱动」的 ORM 的显著差异。

4.7 查询与权限扩展

Map 还承载：

• SearchNormals / SearchFKEnums：列表页查询条件；
• HisRefMethods：实体关联功能（修改密码、部门角色维护等）；
• UAC：插入/删除/更新/查看权限；
• AddHidden：数据范围过滤（如 SAAS 模式 OrgNo = @WebUser.OrgNo）。

五、生态承载：基于 ORM 构建的产品模块

该平台 ORM 不是孤立的数据层，而是 该引擎 / 该引擎 / 该 BPM 平台 低代码平台 的统一元数据底座。

结论：更换 ORM 意味着重写元数据模型、表单设计器、流程引擎数据层、组织结构集成接口——成本极高，因此该 ORM 是平台级基础设施而非可插拔组件。

六、与市面 ORM 的对比评估

6.1 对比总表

6.2 该平台 ORM 的优势

1. 元数据一体：同一 Attr 描述列类型、控件、外键、枚举、默认值，设计器与运行引擎零阻抗。
2. 企业功能内建：主从表、多对多维护、列表查询、权限位、关联方法，减少重复劳动。
3. 低代码原生：运行期可 GenerMap()，字段可来自数据库配置，适合用户自定义表单。
4. 久经生产验证：2002 年至今，与 该引擎 流程场景深度耦合（附件、签名、公文、轨迹等控件类型）。
5. 多数据库与国产库：EntityDBAccess 内可见 Oracle、MySQL、PostgreSQL、达梦、人大金仓等分支。

6.3 该平台 ORM 的局限

1. 非标准 ORM：无法直接用于普通 .NET 项目的「引包即用」，与 EF Core 生态（LINQ、迁移、工具链）不兼容。
2. 弱类型 Row：大型团队纯代码开发时，缺少编译期字段检查，重构依赖全局搜索。
3. 无现代查询抽象：没有 LINQ / IQueryable，复杂查询依赖 SqlBuilder 字符串，可读性与组合性弱于 EF。
4. 无变更跟踪：更新需显式调用 Update() 并指定字段，易遗漏或误更新。
5. XML 遗产：GenerMap(xml) 与代码 EnMap 双路径并存，增加维护心智负担。
6. 测试与 Mock：Entity 与 DBAccess 静态耦合紧密，单元测试需依赖数据库或大量封装。

6.4 适用场景判断

七、典型开发模式示例

7.1 声明式实体（代码优先）

// 1. 字段常量类
public class XxxAttr { public const string Title = "Title"; }

// 2. 实体类
public class Xxx : EntityNoName
{
    public override Map EnMap
    {
        get
        {
            if (_enMap != null) return _enMap;
            Map map = new Map("My_Xxx", "示例");
            map.AddTBStringPK(XxxAttr.No, null, "编号", true, false, 1, 50, 20);
            map.AddTBString(XxxAttr.Title, null, "标题", true, false, 0, 200, 30);
            map.AddDDLSysEnum("Status", 0, "状态", true, false, "XxxStatus");
            _enMap = map;
            return _enMap;
        }
    }
}

// 3. 集合类
public class Xxxs : EntitiesNoName
{
    public override Entity GetNewEntity => new Xxx();
}

7.2 运行时使用

Xxx en = new Xxx();
en.No = "001";
en.SetValByKey(XxxAttr.Title, "测试");
en.Insert();

Xxxs ens = new Xxxs();
ens.RetrieveByAttr("Status", 1);

Xxx en2 = new Xxx("001");
en2.RetrieveFromDBSources();
string title = en2.GetValStringByKey(XxxAttr.Title);

7.3 低代码动态表单（元数据优先）

1. 设计器保存字段 → Sys_MapAttr；
2. MapDtl.GenerMap() / MapData.GenerMap() 合成 Map；
3. GEDtl / GEEntity 作为通用实体承载数据；
4. 前端根据 MapAttr JSON 渲染控件。

八、总结

该平台 ORM 是一段从 2002 年 XML 映射演进到 2003 年 Map/Attr/Attrs 代码化元数据、并在二十余年中持续扩展为低代码应用框架底座的技术路线。

它的本质不是「对象—关系映射库」，而是：

用统一的 Map 元数据，同时描述数据库结构、实体行为、UI 控件、主从与多对多关系、外部数据源与查询条件，并驱动 该引擎、该引擎、组织结构与低代码表单的全生命周期。

与 Entity Framework、Hibernate 等市面 ORM 相比，该平台 ORM 在标准性、强类型、现代查询上不占优，但在低代码、流程、表单、组织一体化场景具有不可替代的语义内聚优势。理解这一边界，是正确使用和扩展该 BPM 平台 平台的前提。