YonBIP高级版开发入门：元数据驱动、主子孙表与插件扩展实战

1. 先搞清楚你在YonBIP高级版里到底动哪一层刚接手YonBIP高级版开发入门这件事的人十有八九会卡在同一个地方拿到账号、连上环境打开IDE却不知道第一行代码该写在哪。这跟学Linux驱动开发时对着内核源码树发呆是一回事——不是能力问题是没建立地图。YonBIP高级版脱胎于NC/NCC那一套企业级应用体系它的开发范式和互联网项目差别非常大不追求从零造轮子而是要求你在一个已经跑起来的、元数据驱动的平台上做接入和扩展。所以入门的第一课不是写代码是把平台的分层画清楚。1.1 平台分层和开发者的活动半径把整个YonBIP高级版拆开看从下往上是这么几层层级主要组成你需不需要动基础设施层容器编排、数据库、中间件、存储基本不动运维负责技术平台层微服务框架、元数据引擎、低代码建模、统一权限只读理解机制即可领域中台层主数据、基础档案、组织、账簿、用户体系读取和引用少量扩展应用层财务、供应链、人力等业务模块你的主战场集成层开放接口、消息、事件总线对接外部系统必用大部分初级开发者的活动范围就是应用层 一点集成层。这个定位很关键因为它直接决定了你的工作方式你要做的是在既有的业务对象模型上增加字段、增加单据、增加逻辑分支而不是设计一套全新的架构。理解这一点之后很多困惑会自然消失。比如有人问我要不要自己设计一套用户权限体系答案是不用——平台已经有完整的组织、角色、功能权限、数据权限模型你要做的是把自己新增的功能挂到现有权限树上。再比如数据表我要不要自己设计主键也不用平台的单据表结构规范是固定的主键id用什么类型、删除标记dr怎么用、时间戳ts干什么全都是约定好的。我见过不少从互联网转过来的同学上手第一周就想重构表结构、想换掉元数据引擎最后撞得满头包。这不是水平问题是路径问题。先当租客再当二房东别一上来就想当业主。1.2 四种开发方式分别适合什么场景平台给了四条路很多新人只知道最后一条结果把本来三天能干完的活干成了三周。第一种是配置化。标准产品自带的功能开关、参数、单据模板调整、审批流配置都属于这一类。比如客户要求某张单据增加一个备注字段并控制显示隐藏这在元数据配置界面拖拖拽拽就完事了不需要一行代码。新手最容易犯的错就是跳过这一步直接写代码结果版本升级时代码全废。第二种是低代码建模。当你需要一张平台没有的单据、一个平台没有的档案时用建模工具定义实体、属性、关系工具会自动生成表结构、基础增删改查页面和接口。这种方式适合数据结构清晰、业务逻辑以标准CRUD为主的场景比如设备台账、合同附件登记这类。第三种是代码扩展。低代码生成的骨架之上当出现复杂计算、跨模块事务、特殊校验时就需要写Java插件或者前端扩展组件。这是入门这个词真正指向的核心内容也是坑最多的地方。第四种是集成对接。跟外部系统交换数据、接收外部事件、推送业务单据走开放平台的标准接口或者消息通道。判断顺序应该是这样的能配置就不建模能建模就不写代码能写插件就不改源码能走标准接口就不动数据库。这条优先级链是我踩过几次大坑之后总结出来的后面会讲具体为什么。1.3 一个反面例子为什么不建议直接动数据库说个真实场景。有个需求是给采购订单加一个预计到货周字段有人觉得简单直接连数据库ALTER TABLE加了一列然后在页面上想办法显示出来。短期看确实跑通了但问题接踵而至第一元数据里没有这个字段定义平台的通用查询、打印模板、导入导出、审批流取值全都识别不了它等于这个字段是个黑户。第二测试环境改了生产环境忘了改上线直接报错。第三后续版本升级时平台的表结构脚本按元数据定义生成跟手工加的列冲突升级直接失败。正确的做法是走元数据先在建模工具里给对应的业务对象加属性工具生成DDL并执行再在单据模板里把字段摆上去最后按需加校验逻辑。整个过程看似绕了一圈但换来的是所有平台能力对这个字段自动生效。提示数据库是平台的结果不是你的输入。任何绕过元数据直接改表的行为都要做好后续维护成本翻倍的准备。2. 三个必须提前建立的心智模型环境搭好之前先把三个概念刻进脑子里否则后面每走一步都要停下来查文档。2.1 元数据驱动模型在前代码在后元数据是这套平台的灵魂。你可以把它理解成描述业务对象的数据——一张单据有哪些字段、每个字段什么类型、什么参照、什么校验规则、在界面上怎么布局、能出现在哪些查询条件里全部由元数据描述。平台拿到这份描述才能自动渲染页面、自动生成接口、自动做权限过滤。生活化的类比元数据就像餐厅的菜单。菜单上写清楚了有什么菜、什么价格、什么配料厨房后端按菜单做菜服务员前端按菜单点单。如果菜单上没有这道菜哪怕厨房真的能做服务员也没法给客人点。这就是为什么元数据里没定义的字段前端看不见。这个模型带来两个直接后果。第一改元数据必须发布。你在建模工具里改了属性不点发布运行时就还是旧的描述前端页面纹丝不动——这是新手最常见的我明明改了呀问题。第二元数据有缓存。集群部署时每个节点都缓存一份元数据描述发布之后可能只刷新了部分节点需要主动清缓存或者滚动重启。我个人的经验是把改元数据 → 发布 → 清缓存 → 验证当成一个不可拆分的四步动作缺一步都会浪费时间。2.2 主子孙表数据库设计是整个项目的地基企业级单据几乎都是一主多子结构。一张销售订单表头有客户、日期、金额合计表体有多行商品明细可能还有表尾的收款计划。平台的标准做法是三张表主表、子表、可能还有孙表。以NC体系延续下来的命名习惯为例表结构大概是这样的-- 主表一张单据一条记录 CREATE TABLE xx_order_h ( id CHAR(20) NOT NULL, -- 主键平台统一生成 pk_group CHAR(20) NOT NULL, -- 集团 pk_org CHAR(20) NOT NULL, -- 业务组织数据权限的依据 bill_no VARCHAR(40) NOT NULL, -- 单据号走编码规则生成 bill_date CHAR(19) NOT NULL, -- 单据日期 pk_customer CHAR(20), -- 客户主键 total_amount DECIMAL(28,8) DEFAULT 0, -- 金额注意精度 bill_status SMALLINT DEFAULT 0, -- 单据状态 dr SMALLINT DEFAULT 0, -- 删除标记0正常1删除 ts CHAR(19) NOT NULL, -- 时间戳乐观锁 creator CHAR(20), creationtime CHAR(19), modifier CHAR(20), modifiedtime CHAR(19), PRIMARY KEY (id) ); -- 子表一张单据多条记录 CREATE TABLE xx_order_b ( id CHAR(20) NOT NULL, pk_group CHAR(20) NOT NULL, pk_org CHAR(20) NOT NULL, pk_order_h CHAR(20) NOT NULL, -- 指向主表 rowno SMALLINT, -- 行号 pk_material CHAR(20), qty DECIMAL(28,8), price DECIMAL(28,8), amount DECIMAL(28,8), dr SMALLINT DEFAULT 0, ts CHAR(19) NOT NULL, PRIMARY KEY (id) ); CREATE INDEX idx_order_b_h ON xx_order_b(pk_order_h, dr); CREATE UNIQUE INDEX uk_order_h_no ON xx_order_h(pk_org, bill_no, dr);几个必须注意的点都是平台约定而不是我的偏好dr删除标记是逻辑删除所有查询都要带上dr 0不要用物理删除。平台的通用查询会自动加这个条件你自己写的SQL如果忘了加就会出现删了还在的灵异现象。ts时间戳是乐观锁。更新时必须带上原值的条件比如UPDATE ... WHERE id ? AND ts ?更新成功后再写入新的ts。多人同时编辑同一张单据时这个机制能防止后写覆盖先写。金额字段的精度统一用DECIMAL(28,8)这类高精度类型绝对不要用FLOAT或者DOUBLE。财务系统的金额误差一分钱都是事故。单据号bill_no必须走平台的编码规则生成不要自己写SELECT MAX(no)1。并发场景下那种写法必然重复。自定义表建议加独立前缀比如xx_避免和标准产品的表名撞车。升级时标准脚本可能会建同名表撞上了就是一场灾难。2.3 扩展点思维能挂钩子就别改源码这是我认为最重要的一条心法。平台的源码是别人的代码你改了它下次打补丁、升级版本改动就可能丢失或者冲突。所以平台设计了大量扩展点事件监听、插件接口、规则脚本、前端组件注册。你的代码应该挂在钩子上而不是织进布里。从执行位置分扩展点大致有三类前端扩展点页面加载前、按钮点击时、字段值变化时、保存提交前。适合做界面交互、动态显隐、前端校验、联动赋值。比如选择客户后自动带出默认结算方式就属于字段值变化事件。后端插件保存前校验、保存后处理、审核前后、删除前后、查询条件拼装。适合做业务规则、事务控制、跨表数据更新。比如审核通过后自动生成下游应收单。规则与脚本不需要重新打包部署的轻量逻辑比如审批流的条件表达式、简单的字段计算规则。适合业务人员自己维护的部分。判断标准很朴素这段逻辑属于界面表现就放前端属于数据正确性就放后端属于流程流转就放规则。数据校验一定放后端因为前端可以被绕过纯展示逻辑一定放前端因为放后端会拖慢性能。注意同一份校验逻辑前后端都写一份是常见做法但要注意两者的规则保持一致。我习惯把可配置的校验参数比如金额上限放到同一个配置源里两边都读它避免改了一边忘了另一边。3. 开发环境搭建与第一个能跑起来的单据理论讲完了动手。这一节的目标是从零搭好环境做出一个能增删改查、能跑通前后端的自定义单据。3.1 环境清单与版本对齐环境搭不起来八成是版本没对齐。企业级平台的依赖关系比互联网项目复杂得多中间件版本、JDK版本、平台补丁号、前端Node版本每一个都可能成为拦路虎。准备清单大致如下# 后端 JDK 8 或 11以平台文档为准别自己升级 Maven 3.6 平台开发SDK从官方渠道获取注意补丁号一致 # 前端 Node.js 14/16高版本经常编不过用nvm切换最省心 npm 或 yarn跟随平台前端工程的要求 # 运行环境 关系型数据库企业版通常用主流商业数据库或开源数据库 Redis缓存元数据和会话 对象存储或文件服务附件、打印模板 # 工具 IDE 装好对应插件 数据库客户端 接口调试工具版本对齐的几个实操心得第一JDK版本不要自己升级。平台的字节码增强、反射扫描、序列化框架都对JDK版本敏感用JDK 17去跑JDK 8编译的平台代码大概率在启动阶段就报模块访问错误。我见过有人为了用新语法把项目升到高版本JDK结果平台一堆依赖报错最后退回重来。第二前端Node版本用版本管理器切换。不同平台版本对Node的要求不一样全局装一个很容易踩坑。nvm装多个版本进项目目录nvm use一下这是最省事的办法。第三补丁号必须和生产一致。你在本地用A补丁开发生产是B补丁接口签名、元数据结构都可能不一样联调时会出现我本地好好的这类经典问题。开工第一件事就是问清楚生产环境的版本和补丁号。3.2 从空库到一个能联调的单据完整链路走一遍大概八个步骤。我按实际执行顺序列每一步都说明为什么。第一步建业务对象。在建模工具里定义实体填名称、编码、所属模块、主表信息。业务对象编码一旦确定就尽量别改因为它会贯穿表名、类名、接口路径、权限编码。第二步定义属性。把需要的字段一个个加上选类型、设长度、配参照。参照字段比如客户、物料、部门要选对应的参照档案这样界面自动带出选择框后端自动校验存在性。第三步生成数据库表。工具根据属性生成DDL并执行。生成后务必用数据库客户端核对一遍重点看字段类型、长度、索引、唯一约束是否符合预期。工具生成的索引不一定贴合你的查询场景。第四步生成代码骨架。一般会生成实体类、DAO、Service、Controller这一套。骨架代码是给你改的但注意保留平台要求的注解和继承关系那些是框架识别的依据。第五步配置单据模板。决定界面上哪些字段显示、摆在哪个区域、是否必填、是否只读。这一步直接对应前端渲染结果改完必须发布。第六步配置查询模板。决定列表页显示哪些列、能按哪些条件过滤、默认排序是什么。查询模板和单据模板是两套配置很多人只配了前者发现列表页没有新字段。第七步接入编码规则。把单据号字段绑定到编码规则上设定前缀、日期段、流水号位数。不要硬编码。第八步联调验证。启动后端、启动前端走一遍新增、保存、查询、修改、删除。这一步要特别关注新增时主子孙表是否一起写入、修改时子表是否正确更新、删除是逻辑删除还是物理删除。3.3 参数配置里的几个关键取舍组织字段怎么定。pk_org是数据权限的核心。如果这张单据是单组织业务就在创建时写入当前组织如果是跨组织业务可能还需要pk_org_v之类的版本组织字段。这一点想清楚再动手后期改起来要动数据权限、要动历史数据。单据类型要不要拆。平台支持按单据类型区分不同的业务规则和模板。如果两个场景的字段差异超过30%建议拆成两个单据类型差异小就用同一类型加条件控制。拆得太细会导致编码规则、审批流、打印模板全都翻倍。编码规则的位数。流水号位数定少了业务量上来就会溢出。我的习惯是年流水至少六位日流水至少四位留足余量。另外要注意编码规则的并发安全平台的标准实现已经处理了别自己另起炉灶。4. 核心实操单据从建表到上线的完整链路前面是骨架这一节把每一块的血肉补上。4.1 数据模型设计规范表结构设计有几个反复被验证的规范我逐条说清楚原因。组织字段一定要有索引。所有查询都会带组织过滤条件pk_org没索引就是全表扫描。复合索引的顺序也要讲究通常按过滤性强的在前、范围查询的在后排列。比如(pk_org, bill_date, dr)组织等值查询在前日期范围在后删除标记放最后。子表必须建pk_父表h的索引。打开一张单据时平台按主表ID查所有子表行这个索引不加单据行数一多打开就卡。业务唯一约束用组合唯一索引。比如同一组织下单据号唯一就用(pk_org, bill_no, dr)。加上dr是因为逻辑删除的记录还在表里不加的话删了再建同号会冲突。扩展字段单独建扩展表还是直接加列。少量字段直接加列简单直接如果扩展字段很多、且不同客户差异大考虑建扩展表用id关联。加列的方案查询简单但每次升级可能冲突扩展表方案隔离性好但查询要多一次关联。我一般控制在10个字段以内直接加列。字段类型的选择。金额用高精度小数枚举用SMALLINT而不是字符串日期时间统一用CHAR(19)存yyyy-MM-dd HH:mm:ss格式这是NC体系的历史约定虽然看着不优雅但跟平台一致才不会出问题主键外键统一CHAR(20)。别忘了审计字段。creator、creationtime、modifier、modifiedtime四个字段看似没用但排查问题时是救命的。谁在什么时候改了这张单据只能靠它们。4.2 元数据配置模板、参照、枚举单据模板的布局逻辑。模板按区域组织表头区、表体区、表尾区、隐藏区。隐藏区的字段在界面上不显示但数据照常传递常用于存放技术字段。我习惯把系统自动生成的字段比如来源单据号、外部系统标识放隐藏区避免界面杂乱。字段属性要区别对待。必填、只读、可编辑、默认值、可见性这些属性在新增、修改、查看三种状态下可以分别设置。比如单据号在新增时只读由规则生成、在修改时也只读那就在两个状态都设只读。这个细节不注意用户能手工改单据号编码规则就形同虚设。自定义参照怎么做。当标准参照满足不了需求时可以建自定义参照定义带过滤条件的查询、定义返回的字段映射。参照的关键是返回值和显示值要分开——返回值是主键用于存储显示值是编码或者名称用于展示。混在一起会导致数据表里塞了一堆中文。枚举档案的用法。状态类字段尽量用枚举不要用魔法数字。枚举的好处是界面自动渲染成下拉框、多语言自动切换、后端校验自动生效。定义枚举时注意保留值的兼容性已经用过的值不要删只能停用。发布与缓存。这里再说一次所有元数据改动都要发布发布之后清理缓存。集群环境下建议用平台提供的缓存刷新接口逐个节点刷比整体重启温和得多。4.3 业务逻辑落地前后端插件与规则后端插件是重头戏。典型结构大致长这样示意具体接口名以实际SDK为准public class XxOrderSavePlugin extends AbstractBillSavePlugin { Override public void beforeSave(BillContext context) { XxOrderHVO head (XxOrderHVO) context.getHeadVO(); ListXxOrderBVO bodys context.getBodyVOs(); // 1. 业务校验金额必须大于零 if (head.getTotalAmount() null || head.getTotalAmount().compareTo(BigDecimal.ZERO) 0) { throw new BusinessException(单据总金额必须大于零); } // 2. 明细行不能为空 if (bodys null || bodys.isEmpty()) { throw new BusinessException(至少录入一行明细); } // 3. 逐行校验数量 for (XxOrderBVO body : bodys) { if (body.getQty() null || body.getQty().compareTo(BigDecimal.ZERO) 0) { throw new BusinessException( 第 body.getRowno() 行数量必须大于零); } } } Override public void afterSave(BillContext context) { // 保存成功后的动作比如写日志、发消息 XxOrderHVO head (XxOrderHVO) context.getHeadVO(); logService.record(订单保存成功, head.getBillNo()); } }写插件有几个要点异常类型要选对。业务校验失败抛平台定义的业务异常前端会弹出友好提示抛运行时异常会被当成系统错误提示不友好还会打一堆堆栈。这两者别混。事务边界要清楚。保存前插件里做的事默认在同一个事务里一旦抛异常整个保存回滚。保存后插件如果涉及外部调用发消息、调接口要注意事务提交时机别把慢操作放在事务里。批量操作要压测。单据保存时子表可能是几十上百行插件里如果有循环查询数据库性能会断崖式下跌。能批量查的一次查完能在内存里比对的别去查库。前端扩展主要处理界面联动。典型场景客户变更后带出默认税率、数量变更后重算金额、某个条件下隐藏某些字段。前端扩展的代码同样要挂在注册的扩展点上不要直接改平台组件源码。4.4 审批流、权限与打印模板的接入审批流接入。单据要支持审批需要三步把单据注册为可审批对象、设计流程定义、发布流程。流程定义里的条件表达式可以取单据字段值比如金额大于10万走总经理审批。这里有个坑条件表达式里的字段必须是元数据里已定义的属性否则取不到值流程会卡在默认分支。权限接入。功能权限管能不能打开这个功能数据权限管能看到哪些数据。新增的功能要在权限树上注册节点然后配到角色上。数据权限通常是按组织维度过滤需要确认当前登录用户的组织范围是什么、单据的组织字段是哪个、跨组织查询要不要特殊处理。打印模板。打印模板基于单据模板生成字段拖进去就能用。要注意的是数据格式金额千分位、日期格式和多语言。另外打印模板的修改也要发布不发布打印出来还是旧的。5. 联调上线阶段的常见问题与排查实录真正的坑都在联调阶段。这一节我把遇到过的问题整理成速查表再挑几个展开讲。5.1 元数据不生效类问题速查现象大概率原因处理动作新增字段页面上看不到元数据没发布 / 单据模板没加字段重新发布检查模板列表页没有新字段查询模板没配单独配置查询模板字段能显示但保存后为空属性没勾选可编辑或没参与持久化检查属性配置修改模板后部分节点没变化集群缓存未刷新逐节点刷新缓存参照选不出来数据参照的过滤条件过严 / 权限受限放宽条件检查组织范围枚举显示成数字枚举值未定义 / 多语言未配补枚举值和翻译这张表里的每一条我几乎都亲自踩过。印象最深的是枚举显示成数字定义字段时顺手选了枚举类型但忘了把枚举值和对应翻译配全界面上直接显示0、1业务人员看了一头雾水。5.2 数据不一致与并发踩坑删了还能看见。典型原因是自己写的SQL没带dr 0。平台的通用查询会自动加自定义查询不会。排查方法很直接把执行的SQL打到日志里看一眼过滤条件。养成习惯所有自定义SQL都显式写dr 0。并发编辑互相覆盖。两个用户同时打开同一张单据A先保存B后保存B把A的修改覆盖了。这是乐观锁失效的表现。检查更新语句是否带了ts条件如果没带就会无条件覆盖。正确写法是WHERE id ? AND ts ?更新影响行数为0时提示用户数据已被他人修改请刷新。这个提示虽然用户体验一般但比丢数据强得多。子表更新出现孤儿行。修改单据时先删掉全部子表行再重新插入听起来简单粗暴但如果中间失败就会留下没有主表关联的行。正确做法是按行号做增量比对保留的行更新、删掉的行标记删除、新增的行插入。这套逻辑平台一般有封装好的方法优先用平台的。单据号重复。三种可能编码规则没走平台、并发时缓存不同步、历史数据里已经有同号。排查顺序是先看代码里有没有自己拼单据号的逻辑再看集群节点时间是否同步最后查历史数据。5.3 性能问题定位思路性能问题别凭感觉优化按层排查。第一步看数据库。把慢查询日志打开找执行时间最长的SQL。企业系统里慢SQL通常有三种缺索引的全表扫描、多表关联的笛卡尔积、子查询嵌套太深。第二步看索引命中。用执行计划看有没有走索引。特别注意组织字段和删除标记是否在索引里这两个条件几乎每个查询都有。第三步看接口耗时分布。如果SQL很快但接口慢问题可能在序列化、权限计算、元数据加载。权限计算是重灾区数据权限规则复杂时一次查询可能要先算出一堆组织ID再拼进SQL。第四步看前端渲染。列表页返回几千行数据前端渲染也会卡。企业系统的列表页应该分页默认每页几十行就够了不要图省事一次全查出来。一个实用的经验给列表查询定一个硬性规则——必须带组织条件、必须分页、必须走索引。这三条守住80%的性能问题不会出现。6. 几个文档里不太容易查到的心得写到这说几个零散但很有用的经验。关于开发环境的备份。元数据配置是存在数据库里的不是代码。这意味着你的配置成果可能会因为一次误操作丢失。我的做法是每完成一个阶段性配置就导出一次元数据包存到版本库里。这个习惯在最开始的时候觉得多余直到有一次误删了配置又没备份重新配了两天。关于自定义字段的命名。一定要加业务前缀比如xx_order_type。有一次我们定义了order_type跟后来平台升级新增的标准字段重名两边含义还不一样排查了好久才发现。关于日志。平台自带的日志级别可以在运行时调整遇到疑难问题时把对应模块调到DEBUG级别能看到元数据加载、SQL执行、插件调用的全过程。比在代码里到处打断点快得多。问题是DEBUG日志量很大用完记得调回来不然磁盘会被写爆。关于版本升级。升级前必须做的一件事是把所有自定义插件、自定义表结构、自定义元数据列一份清单。升级后逐项验证。我们有一套检查表大概二十来项跑一遍半天时间但能避免上线后才发现功能失效。关于和业务人员的沟通。这一条和技术无关但我觉得同样重要。企业系统的需求往往是业务语言描述的比如这个单子要走特殊审批。你得把它翻译成什么条件下触发什么分支。翻译错了代码写得再漂亮也没用。我现在养成的习惯是需求确认时把技术方案用业务语言复述一遍让对方点头再动手。最后分享一个小技巧。如果你不确定某个功能该用配置还是该写代码先花半小时在测试环境用配置的方式试一遍。配置能实现的永远优先配置。这不是偷懒是给未来的自己省事——配置可以随时调整代码一旦上线改动成本就高了。