NC65元数据表详解：核心表、关联关系与排障实践

1. 为什么要盯住NC65的元数据表做NC65二开的人迟早会撞上元数据这个词。刚到项目那会儿老开发跟我说元数据是NC65的命根子我没太当回事直到有一天前端单据报错整个页面起不来排查到最后发现是有个字段在元数据表里被改坏了才真正体会到这句话的分量。NC65是一个基于元数据驱动的平台你在界面看到的每一个单据模板、每一个字段、每一个按钮后台都不是写死在Java代码里的而是以元数据的形式存放在数据库表中。系统运行的时候框架会去读这些元数据把它们解析成运行时对象渲染成你看到的前端界面同时用它们来生成SQL语句完成数据表的增删改查。这意味着你改元数据表就相当于在改系统运行的图纸。图纸画错了后面盖出来的楼肯定歪。很多刚接触NC65的同事问我的第一个问题是那元数据到底存在哪些表里这个问题看似基础其实是整个NC65二开知识体系里最关键的一环。你只有知道了数据存在哪张表、哪个字段、以什么格式存才能在出了问题的时候快速定位也才能在写代码的时候不走弯路。这篇内容我把自己在项目中摸出来的元数据相关表清单、表与表之间的关系、以及实际排查问题时的经验完整整理一遍。以NC65的开发库Oracle为例SQL Server数据库逻辑相同只是个别字段类型有差异。2. 元数据核心表逐张拆解NC65的元数据表核心集中在MD开头的表里。MD是MetaData的缩写这是整个NC65元数据体系的基础。2.1 md_class万物起源的类定义表表全名md_class核心作用NC65里所有的基础信息、业务信息、单据类型、字段集合先有类后有实例。这张表就是用来存放类的定义的。可以这么理解我们要描述一个员工对象那员工就是一个类具体到某个叫张三的员工那就是实例。系统里所有的元数据都得先有一个类的定义挂在md_class上。关键字段pk_class类主键全局唯一class_name类的名称比如员工档案对应一个固定编码display_name显示名称界面展示用parentclass父类主键用于体现层级关系isclasstemplate是否类模板标记这个字段很关键1表示模板类0表示普通类extbeanname扩展Bean名称涉及扩展开发时会用到我记得第一次去查这张表用了一个最简单的查询SELECT pk_class, class_name, display_name FROM md_class WHERE display_name LIKE %员工%就这么一条SQL能把员工相关所有类定义捞出来。日常排查的时候这张表是你打开所有元数据问题的第一道门。2.2 md_entity实体定义表类的具体化表全名md_entity核心作用如果说md_class是类的定义那么md_entity就是实体的定义。一个类可以对应多个实体实体才是真正跟数据库字段挂钩的东西。这张表我一般不太直接关注因为它更多是框架底层在维护但有一类场景你必须去查它当你需要确认一个业务实体是否存在、或者需要拿到实体的主键去关联其他元数据表时就得用到它。关键字段pk_entity实体主键classid对应的类主键关联md_classentityname实体名称displayname显示名称tablename这个字段很关键它标识了这个实体映射的物理表名。比如员工档案实体可能映射的是bd_psndoc这张物理表这就能解释一个问题NC65界面上看到的员工档案后台是存在哪张物理表里的答案就在md_entity的tablename字段里。2.3 md_billtype单据类型表别被名字骗了表全名md_billtype核心作用NC65里所有的单据采购订单、销售订单、付款单、收款单、报销单都有一个自己的单据类型编码。这些单据类型的定义就存在md_billtype里。典型查询SELECT pk_billtype, billtypename, billtypecode FROM md_billtype WHERE billtypename LIKE %采购%这个查询基本能帮你快速定位所有采购相关单据的类型编码。别小看这个后续查单据模板、单据初始化、流程配置全都是围绕billtype编码来组织的。2.4 md_class_field字段定义的关键所在表全名md_class_field这张表是元数据表体系里最核心的一张没有之一。因为它用来维护类所拥有的字段。核心作用每一列字段的元数据定义都存放在这里。一个类下面有哪些字段、字段叫什么名字、什么类型、是否必输、是否只读、长度多少、默认值是什么全部记录在案。关键字段pk_class_field字段定义主键pk_class所属类主键关联md_classfield_name字段名比如empname、empcodedisplay_name显示名称界面上看到的中文标签比如姓名data_type数据类型标识比如字符串、整型、日期等is_required是否必输1是必输0非必输is_readonly是否只读field_length字段长度default_value默认值ref_info引用信息如果字段是引用型比如引用部门、引用人员引用关系就记录在这里我实际工作中最常用到这张表的一个场景是排查前端单据上的字段为什么没有显示出来。比如用户说采购订单的表头上我明明加了一个字段怎么界面上看不到。那我第一件事就是去查这张表SELECT field_name, display_name, is_visible, is_required FROM md_class_field WHERE pk_class (SELECT pk_class FROM md_class WHERE class_name 采购订单)注意我用了is_visible这个字段这个字段控制字段在前端是否可见。很多时候字段加上了代码也没问题纯粹是这个可见性标记没设对导致前端不渲染。这个问题在NC65二开里特别容易踩到后面我会专门展开讲。2.5 md_class_field_lang字段的多国语言翻译表表全名md_class_field_lang核心作用NC65支持多语言环境每个字段的显示名称在不同语言下可以有不同的翻译。这个语言表就是干这个活的。结构上它通过pk_class_field关联md_class_field然后按语言编码比如简体中文、繁体中文、英文分别存储显示名称。典型查询SELECT * FROM md_class_field_lang WHERE pk_class_field xxx这个表日常开发中用的频率不算高但要改字段显示名称的时候记得这个地方也要同步更新否则会出现简体中文环境改了名字英文环境还是旧名字的尴尬情况。2.6 md_relation关系的中间桥梁表全名md_relation核心作用记录元数据之间的关系比如主子表关系、关联关系、引用关系等。以采购订单为例采购订单表头主表和采购订单表体子表之间就存在一个主从关系这个关系定义就存在md_relation里。NC65的前端界面能正确展现主子表联动、保存的时候能正确维护主表和子表的数据靠的就是这个关系定义。关键字段pk_relation关系主键source源端标识target目标端标识relationtype关系类型比如主从关系、引用关系遇到主子表显示异常、保存数据时子表数据丢失这类问题查这张表往往能找到线索。2.7 md_enum枚举字典表表全名md_enum核心作用NC65里大量使用枚举字段比如性别字段的取值就是男/女审批状态字段的取值是已保存/审批中/已审批/已驳回。这些枚举值统一定义在md_enum里。日常排查的时候如果一个枚举字段的下拉选项突然少了几个或者多了几个第一反应就应该是去查这张表。关键字段pk_enum枚举主键enum_name枚举名称enumtype枚举类型标识与md_enum配套的还有一张md_enum_value表用来存枚举的具体值。结构上是经典的枚举类型 枚举值设计跟Java里的枚举类是一一对应的思路。2.8 其他需要了解的元数据相关表除了上面这些核心表还有几张表在特定场景下会用到我简单列一下md_comp组件定义表NC65的界面组件元数据比如按钮、面板等纯粹前端展示层面的定义md_panel面板定义表单据模板的界面布局表头区、表体区划分就是在这里定义的md_template模板定义表单据模板的元数据定义多个模板可以引用同一个类md_property属性定义表类的扩展属性md_custombutton自定义按钮表前端单据上自定义按钮的定义md_class_relation类关系表记录类与类之间的关系比如引用关系实际开发中你经常要建立这样的认知md_class_field管字段md_template管界面md_enum管下拉md_billtype管单据分类。这四个弄清楚NC65的元数据就算入了门。3. 元数据表之间的钩子关系刚才单独拆了表但你要真正会用这些表必须搞明白它们之间的关联关系。否则你只记住了表名遇到跨表问题时照样抓瞎。我画个比较直观的关联链路链路一类 → 字段 → 语言 → 枚举md_class类 → md_class_field字段通过pk_class关联 → md_class_field_lang字段语言通过pk_class_field关联 → md_enum枚举类型通过字段的枚举类型标识关联 → md_enum_value枚举值通过pk_enum关联这条链路用来回答这个类下面有哪些字段、这些字段叫什么名、取值有哪些。链路二单据 → 类 → 模板md_billtype单据类型通过billtype编码作为业务入口 → md_class类单据类型对应的业务类 → md_template模板通过pk_class关联 → md_comp / md_panel界面组件模板下的具体UI定义这条链路用来回答这个单据的界面模板是怎么组织的。链路三类 → 实体 → 物理表md_class类 → md_entity实体通过classid关联 → 物理表实体通过tablename映射到实际数据库表这条链路用来回答这个业务对象的数据到底存哪张物理表。这句话我听过的场景太多了新来的同事对着数据库几百张表懵了不知道哪张是存员工信息的其实查md_entity就能精准定位。实际拿一个问题的排查过程来举例客户反馈在NC65前端采购订单单据模板上增加了一个自定义字段采购原因但是填报保存后这个字段的值没有存到数据库里。常规排查思路摘录如下查md_billtype拿到采购订单的单据类型编码根据单据类型编码找到对应的类去md_class里确认主键去md_class_field里查采购原因字段是否存在如果存在接着去查这个字段对应的物理存储列名和实体映射如果不存在那就是模板配置阶段就没保存成功回到单据模板配置界面重新维护最终确认是字段权限问题导致该字段只读不保存。整个链条全程都在元数据表里绕。所以我说学会查元数据表至少解决NC65开发中一半的幽灵问题。4. 实操中发现的高频元数据问题与坑理论说了一堆说点实战中踩过的坑。以下这几类问题我认为是NC65二开中最常见的元数据翻车现场。4.1 字段可见性控制是is_visible还是权限这是第一个坑。因为NC65的字段在前端是否显示不完全由元数据表里的is_visible字段决定。还受角色字段权限控制。即使你在md_class_field里设置了is_visible为1可见如果当前登录用户没有这个字段的查看权限前端照样不显示。我遇到过这样的情况开发环境——管理员账号登录字段正常显示客户现场——业务员账号登录字段消失。排查老半天最后发现不是元数据配置问题而是字段权限没有分配给业务员的角色。所以查元数据表之前先分清楚当前问题是元数据配置的问题还是权限配置的问题。不要在错误的方向上浪费几个小时。经验判断技巧如果所有用户都看不到字段大概率是元数据或模板问题先查md_class_field的is_visible再查模板布局如果只有部分用户看不到字段优先查字段权限配置不要急着动元数据表。4.2 级别顺序share_flag和是否封存表md_class_field里有一个字段叫share_flag很多文档里叫共享级别或下发模式。这个字段实际控制着该字段在不同集团、不同组织之间的数据共享范围。我最初接手项目的时候这个字段被前面的人按错误级别设置了结果就是A组织录入的字段值B组织查询的时候看不到但界面是正常的代码也没任何报错。这种现象是最坑的因为它不会报错只是数据悄无声息地不见了。排查思路先确认字段在A组织录入成功并已保存B组织查询同一单据发现字段值为空检查md_class_field里share_flag的取值把它调整为目标组织能共享的级别重新登录刷新缓存验证数据是否正常显示。这个坑在集团化部署、多组织架构的项目里碰到概率非常高。遇到同一个单据换个组织数据就没了的现象优先查share_flag别绞尽脑汁去改代码。4.3 字段类型修改后物理表的同步问题NC65元数据设计器里修改字段类型是允许的但这里有一个巨大的坑修改元数据定义之后如果物理表没有同步更新运行时不报错数据却会出问题。举个实际发生的例子客户要求把备注字段的长度从300扩到1000开发人员在元数据设计器里改了metadata里的长度定义没有做数据库升级同步操作。结果就是界面输入不限制但数据库层面的列长度没变数据一旦超过原长度保存的时候直接报错或数据被截断。因为Oracle里nvarchar2(300)存不下1000个字符。正确做法修改元数据后必须走NC65的元数据发布或数据库升级流程让物理表结构和元数据保持一致。千万别绕过这个环节直接改元数据表或物理表。4.4 手工改元数据表导致系统无法启动这是我最想强调的一个坑。有些同事为了图省事直接用SQL改了md_class_field或其他元数据表里的数据。结果就是系统启动的时候框架加载元数据发现数据不合法直接抛异常整个模块起不来。NC65的元数据加载是有缓存和校验机制的手工改表很容易打破数据一致性。我见过最离谱的一次是有人直接DELETE了md_class_field里的几条记录想省事删除某个字段结果该类的所有单据全部打不开。经验之谈元数据表的设计原则是只读优先——代码可以读业务维护必须通过NC65平台自己的元数据设计器来做不要用SQL去动元数据表的业务数据。除非你在做数据修复并且已经备份。数据库里改一行容易改完以后引发的连锁问题可能要加班一整周来收拾。4.5 元数据缓存刷新问题还有一个日经问题为什么我改了元数据界面上没变化刷新也没用。因为NC65对元数据有缓存。改了元数据之后需要刷新元数据缓存常见的方式是重启中间件或者用系统自带的缓存刷新功能。我习惯的做法是用管理员账号登录系统执行元数据缓存清理动作确认缓存刷新成功再验证前端效果。这里有个提醒缓存刷新要等几秒到几十秒不要立即刷新页面就说没生效。因为元数据缓存不只是本机分布式部署环境下还有集群缓存要同步耐心等一会儿再验证比自己反复瞎操作高效得多。4.6 单据模板历史数据的兼容性最后一个经历修改单据模板上的字段配置后历史保存的数据单据打开时字段错位。根本原因模板元数据变更后旧单据保存的字段值位置信息与新的模板定义不匹配导致解析异常。NC65在读取一张历史单据时会按当前模板元数据去解析数据库存储的字段值如果模板中字段顺序、字段删除/新增导致位置变化历史数据可能就错位了。避开这个坑的关键思路删除字段优先用失效而不是物理删除新增字段时注意它不会影响既有字段的存储顺序大改动之前先导出模板备份。改元数据不是开发自嗨是要对系统里的存量数据负责的。5. 元数据表维护策略和避坑自查清单把前面零零散散的经验汇总一下给出几个我自己在项目里坚持的执行策略。5.1 核心执行策略按优先级排序优先使用平台功能维护元数据一切通过NC65元数据设计器来操作不直接改表读取元数据表是开发常态查询分析问题时尽管用SQL高效又直接修改前备份修改后验证为了保险改完元数据后确认物理表、缓存、历史数据三条线注意多组织环境的共享级别share_flag、数据权限、角色字段权限要一起看保持物理表与元数据一致任何元数据变更同步走数据库升级流程防止两侧不一致。5.2 字段挂历操作自查清单把上面的经验浓缩成一张自查清单方便你在每次动元数据之前瞄一眼检查项具体内容字段是否成功创建查md_class_field确认pk_class_field已生成字段是否绑定页面查模板中的面板和组件定义确认已拖到界面布局里字段是否对用户可见查is_visible标记同时检查角色字段权限字段是否有权限限制确认当前账号所属角色对这个字段的读写权限物理表是否已同步确认实体映射表结构已增加该字段列共享级别是否匹配查share_flag确认目标组织可以读取该字段缓存是否已刷新通过平台缓存刷新动作或重启中间件这七项是我在项目里总结的元数据字段七查。你按这个清单走一遍大部分字段相关的疑难杂症都能找到症结。5.3 权限设置不当引起的误删和误改有一件事我提过很多次但每次都要再说一遍非必须不要修改md_class_field的is_required、is_readonly等控制标记。因为这些标记一旦修改受影响的不只是当前界面而是全局所有引用了这个类的页面。我记得有一次只是为了应付某个客户的特殊需求把某个字段的is_required临时改成了0结果影响到了其他两个产品的界面导致必输项直接没了下游数据校验崩溃最后花了一晚上把所有相关页面排查了一遍才恢复完整。所以在动is_required这种全局性字段之前一定要考虑影响范围。实在有特殊需求优先考虑通过单据模板的字段属性和表单规则来实现而不是去动类的公共属性。5.4 关于扩展开发时的元数据策略最后补充一点和二开模式有关。NC65支持扩展开发模式也就是基于标准产品进行扩展开发而不是修改标准元数据。很多初学者图省事直接在标准元数据上修改字段、加字段。前期确实快到了升级的时候升级包一覆盖改的东西全丢了或者和新的标准元数据冲突。合理的做法是新增字段、新增类、新增模板都放在扩展包路径下与标准的元数据隔离。这样标准产品升级的时候扩展内容不会被冲掉。元数据表的隔离换来的是升级的平滑和整个项目的健康。这个道理就跟你写代码不应该去改第三方jar包一样——你在源码上打的补丁版本升级一次就没了。6. 元数据相关SQL速查手册最后贴一份我自己整理的速查SQL。这些语句我反复用Directly Copy能省很多事。查类定义SELECT * FROM md_class WHERE class_name xxx;查类下的字段SELECT * FROM md_class_field WHERE pk_class ( SELECT pk_class FROM md_class WHERE class_name xxx );查字段语言名称SELECT f.field_name, l.display_name FROM md_class_field f LEFT JOIN md_class_field_lang l ON f.pk_class_field l.pk_class_field WHERE f.pk_class xxx;查单据类型SELECT * FROM md_billtype WHERE billtypename LIKE %采购%;查枚举值SELECT ev.* FROM md_enum_value ev JOIN md_enum e ON ev.pk_enum e.pk_enum WHERE e.enum_name sex;查实体映射的物理表SELECT entityname, tablename FROM md_entity WHERE classid xxx;查模板定义SELECT * FROM md_template WHERE pk_class xxx;以上就是NC65元数据涉及到的表以及我在实际项目中用这些表排障的经验总结。元数据表虽然看起来多但核心就那几个理清关联关系、遵守维护规则基本就能玩转NC65的元数据体系。下次再遇到字段不见了单据起不来数据保存不了这类问题先拆元数据链路会比盲目看代码高效得多。