用友NC业务插件注册开发：从原理到实操避开常见坑

简介面向用友 NC/NCC 系统的客开人员这份 docx 文档系统讲解业务插件的注册与开发方法用于解决单据在新增、修改、删除、刷新、查询、审批、取消审批、签字等操作前后需要执行自定义业务逻辑的常见客开需求。相比直接修改动作脚本或单据接口类在标准功能基础上挂接插件更安全能有效降低对系统原有逻辑的影响同一个业务插件还可同时处理多种操作灵活高效。资源为单个 docx 文件压缩包仅 92KB便于随时查阅。文档从业务插件注册节点入手给出实现 IBusinessListener 接口的完整 Java 代码示例如 CubeDefUpdateListener并演示如何通过 BDCommonEvent、BusinessEvent 获取对象数据以及如何按 insert、delete、update 等事件类型进行分支判断与处理对于插件注册位置、事件数据获取、多操作复用等关键点都有涉及可快速套用到实际客开任务中。已有 310 人学习下载适合正在从事 NC 客开或计划系统学习插件机制的开发者参考。 做用友NC系统二次开发这几年我最大的感触是一说起业务插件注册开发很多人的理解其实停留在“写个类丢进去”这个层面。有人以为写好代码就万事大吉有人以为插件不过是个菜单配置更有不少人卡在同一个环节——代码写完了注册信息也写了重启之后界面完全没反应于是开始怀疑人生。这篇文章不绕弯子直接把NC系统里业务插件注册开发这件事从原理到实操一条线讲透。内容里不会堆理论更多的是我踩过坑之后沉淀下来的判断方法和操作细节希望能帮你少走一段弯路。适合刚接手NC二次开发、被插件注册问题反复折磨、或者正在NC平台上规划扩展功能的人看。1. 先搞明白注册到底在注册什么1.1 NC里的插件是平台留好的挂点要理解注册首先得明白NC的插件到底是什么。NC内部有大量标准功能模块比如采购订单、销售订单、库存管理、财务凭证、审批流、报表这些功能都跑在底层UAP平台上。平台在运行时有非常固定的流程节点打开单据、编辑字段、保存数据、审批通过、打印输出、列表加载等等。平台不会在每个环节都对外开放但确实在一批关键节点上预留了“挂点”也就是开发文档里常说的扩展点。所谓业务插件就是针对某个挂点补齐一个处理类然后通过描述文件告诉平台“在这个节点请调用我这个类”。这个“告诉平台”的动作就是注册的真正含义。很多新手把插件和改标准源代码搞混。改源代码意味着你把平台自带的行为改掉了后续平台升级打补丁你的修改极大可能被覆盖而且出了问题很难界定是平台问题还是扩展问题。插件注册则是把自定义代码隔离在标准代码之外平台只在约定的时机自动调度。这种方式不只是维护方便更重要的是它遵循了平台的扩展机制后续升级时风险小得多。NC的插件机制还有一个好处同一个挂点上可以挂多个插件通过顺序配置控制执行先后互不干扰这是标准源码改造做不到的。1.2 注册必须说清的三件事模块、插件点、顺序一张注册信息其实要表达三个关键点。第一是目标模块告诉平台这组插件归属哪个业务模块避免全局扫描。比如某个校验逻辑只对销售订单生效那它就挂在销售模块下而不是整个NC系统每个模块都去加载。模块归属错了最典型的表现就是注册信息能读到但目标节点上就是不触发。第二是插件点告诉平台在哪个生命周期调用比如“打开单据后”“保存前”“按钮点击后”。插件点选择错误是插件不生效的最常见原因没有之一。第三是执行顺序同一延伸点上挂了多个插件时顺序号小的先执行后执行的依赖前面结果的必须把顺序排对否则数据状态和预期完全对不上。为了让你快速建立选型概念我把三类常见的插件挂在哪个插件点、适用于什么场景做了一个对比。插件类型典型插件点常见用途生效范围客户端按钮插件单据按钮点击事件自定义校验、调用后台服务、扩展动作单据卡片界面单据生命周期插件保存前、保存后、审批后数据加工、日志记录、关联生成其他单据单据保存与审批流程列表插件列表加载、行选中列表字段联动、按钮显隐查询列表界面2. 环境准备与工程结构少走弯路的配置2.1 开发环境的搭建思路开发NC业务插件核心不是代码本身而是环境是否贴近真实运行环境。常见组合是JDK1.8、官方提供的Eclipse开发环境、NCHome中间件再加一个可访问的数据库。很多人环境搭不起来是因为图省事只在自己的IDE里写代码本地没有一个可启动的NC中间件代码写完只能靠肉眼检查无法跑通真实的类加载和插件扫描。这里我必须强调插件注册最终看的是运行时的扫描结果而运行时环境的类加载、jar依赖、组件版本全都影响注册能否成功。所以不要节省这个步骤准备一个独立的NCHome配置成开发模式既能实时看日志又能随时重启验证后面能省下大把排查时间。2.2 工程目录和依赖组织NC插件工程的目录结构并不复杂但很讲究。通常src目录下放Java源码resources目录下放META-INF/plugin.xml描述文件编译后的class文件会对应部署到NCHome的模块目录里。依赖管理是很多人踩坑的地方——别把NCHome下的大量jar复制到自己的工程lib里而是直接在开发工具的classpath里引用NCHome路径下的jar。我接手过一个项目前同事把上百个jar复制到工程的lib目录导致每次平台升级都要比对版本后来统一改成只引用NCHome路径版本冲突问题少了很多。这看起来是小事但实际上决定了你后面注册能否顺利也是插件更新维护时能不能快速定位差异的关键。我常用的工程结构大概是这样的stock-plugin/ ├── src/ │ ├── nc/demo/plugin/ │ │ ├── CheckStockButtonPlugin.java │ │ └── StockSaveListener.java │ └── resources/ │ └── META-INF/ │ └── plugin.xml └── classes/ # 编译输出部署时合并到NCHome对应模块2.3 plugin.xml插件注册的“身份证”plugin.xml是插件注册信息的载体决定了平台在启动时能不能发现、加载并调用你的插件。一个最小化的描述文件大概长这样。需要说明的是不同NC版本的插件点名称有差异如果你用的版本对不上以当前版本的扩展点清单为准但整体结构和注册思路是一致的。?xml version1.0 encodingUTF-8? plugin idnc.demo.stockplugin/id version1.0/version categoryclient/category moduledemo/module description库存校验按钮插件/description extension pointnc.uif2.bill.button button idbtn_check_stock name库存校验 classnc.demo.plugin.CheckStockButtonPlugin/ /extension extension pointnc.uif2.bill.listener listener idlst_stock_save classnc.demo.plugin.StockSaveListener/ /extension /plugin注意这个文件不是随便放的。它要被平台模块扫描到编译后要放在对应模块的META-INF目录下和模块原有的plugin描述文件放在一起。我曾经遇到一个项目组把plugin.xml塞进自己写的工具jar里结果平台根本没扫那个jar注册始终不生效。所以遇到“注册不生效”的问题时先别怀疑代码先确认一个基本事实这个XML到底有没有落到平台会扫描的目录里。3. 一个能跑通的最小注册实战3.1 写一个最朴素的按钮插件我习惯于用最小案例验证机制第一步先在单据卡片上增加一个自定义按钮点击后弹个提示能跑通了再往里塞真实业务逻辑。这个按钮插件继承平台提供的按钮插件基类在点击动作里取当前卡片数据的主键调用后台能力再返回操作结果。核心是验证一件事注册信息与运行时代码是否能正确对接。下面的示例代码是一个骨架如果你用的平台版本接口不一样替换成对应的基类方法即可。package nc.demo.plugin; import nc.ui.pubapp.uif2app.actions.pub.AbstractButtonPlugin; import nc.ui.pubapp.uif2app.view.BillCardPanel; public class CheckStockButtonPlugin extends AbstractButtonPlugin { Override public void doAction(nc.ui.pubapp.uif2app.actions.ActionContext ctx) { BillCardPanel card getBillCardPanel(); if (card null) { return; } String[] pks card.getSelectedPrimaryKeyValues(); // 调用后台服务校验库存返回提示 int stock getStockService().queryStock(pks[0]); ctx.showMsg(当前库存 stock); } }这段代码不复杂但里面埋了几个容易出错的地方。getBillCardPanel()返回空时要判空很多插件运行时报空指针就是没做这个判断取主键的方式依赖当前界面状态如果界面上没有选中记录pks可能是空数组不处理就会数组越界调后台服务尽量走平台的事务和上下文别在新线程里直接创建连接否则可能出现连接管理混乱和事务不可控的问题。新手写按钮插件最常见的翻车点就是忽略了这些界面状态的边界情况。3.2 把插件注册到目标节点代码写完后要确认按钮注册到哪个节点上。NC的单据界面通常有节点编码比如采购订单、销售订单、库存单据各有各的编码。插件描述文件通过扩展点挂按钮但这个按钮要出现在哪个单据的工具栏上通常由按钮的target属性和平台资源共同决定。不同版本写法不一样有些在plugin.xml的button节点上直接配置target有些需要维护菜单资源和按钮资源再绑定到单据模板上。这也是很多人一开始就搞混的地方光写了plugin.xml没有把按钮资源和目标单据节点关联起来按钮自然出不来。我建议的做法是先在系统里找到目标单据的节点编码确认该节点属于哪个模块然后把插件XML放在对应模块目录下部署后重启中间件再打开单据页面看工具栏是否多了按钮。完整的验证流程是部署 - 重启服务 - 清客户端缓存 - 打开目标节点 - 观察按钮。少了“清缓存”这一步经常会发生代码更新了但界面还是老样子。清缓存不只清浏览器缓存还包括NC客户端本地缓存和中间件临时文件目录这一点在开发阶段极易被忽略。3.3 从按钮到完整的业务扩展按钮插件跑通之后再扩展其他插件点就顺理成章了。比如保存前校验库存写一个单据生命周期插件重写保存前方法在数据尚未提交时做校验发现问题直接抛异常中断保存这个“中断”能有效防止脏数据落库。再比如审批后动作审批通过之后自动把数据推送到下游系统或者生成关联单据这种场景更适合用服务端插件实现。注册方式跟按钮插件类似在描述文件里多配一段extension即可但有一点要特别提醒一个插件类最好只负责一类事情不要在一个类里堆几十个方法然后挂到多个插件点上。我见过一个项目把所有扩展逻辑都写在同一个插件类里最后类超过两千行代码本身能跑但维护非常痛苦。任何一个环节抛异常都要从头翻到尾定位问题的时间可能比写代码的时间还长。插件类的职责边界清晰名字和ID保持语义化注释写明挂载点和业务用途这些习惯在项目后期会带来巨大的回报。4. 注册之后不生效九成问题在这些地方4.1 五个快速定位动作插件注册开发里最让人头疼的就是“代码没问题但就是不生效”。我总结过五个定位动作按顺序排查能解决绝大多数问题。第一是检查plugin.xml是否落到了平台扫描的模块META-INF目录里第二是检查插件类是否已经编译进对应的classes或jar包中而不是只存在于IDE的编译输出里第三是检查扩展点名称和插件基类与当前平台版本是否匹配第四是清掉NC客户端缓存和中间件缓存后再看效果第五是打开系统日志看启动过程有没有加载你注册的插件。这五步看着简单但每一条背后都有真实案例。尤其是第四条。很多开发在本地改了代码重新登录客户端发现界面没变就误以为注册失败实际上缓存里的旧类还在运行。遇到这种情况把NCHome下的临时目录和客户端缓存目录清理掉再重启一次往往问题就消失了。这不算技术难点但确实是最耗人耐心的环节。4.2 系统监视器里的pk锁到底在说什么排查过程中可能会用到NC系统监视器。不少人在监视器里看到“pk锁”和“加锁次数1”就开始紧张其实不用慌。之前就有同事盯着屏幕问我这个pk锁加锁次数1是不是系统死锁了我说你把概念搞混了。pk锁是数据库层面对某一主键行的锁加锁次数表示这一行记录被当前事务获取锁的次数。在并发环境下多个用户同时打开编辑同一个单据时系统会对同一条主键记录加锁加锁次数为1是最常见的正常状态代表当前会话加过一次锁。真正需要警惕的不是加锁次数本身而是锁的持有时间和等待关系。如果某个会话长时间持有锁不释放其他会话在等这个锁同时加锁次数不停上涨那就需要回头查业务代码了。常见的情况是插件里开启了事务但忘记提交或者是长事务中嵌套了远程调用把整个事务的持续时间拖得很长。排查思路是在系统监视器里看会话对应的SQL和事务开始时间再回到插件代码里找可疑的事务控制位置。这里单独提醒一句不要为了排查问题去手工杀数据库会话杀了会话只是解决表面症状根因往往在代码逻辑里。先看事务边界再看是否有循环调用最后才看锁等待链。4.3 常见问题速查表现象可能原因解决办法注册后界面没有新增按钮插件XML没被扫描或扩展点不匹配当前版本确认XML部署路径逐个比对插件点名称按钮显示但点击无反应插件类没编译到运行环境或方法签名覆盖错误重新编译部署核对父类方法签名保存后插件执行了两次同一插件被重复注册或同时挂到了多个扩展点检查模块中是否有重复的plugin.xml只保留一个挂载点插件抛异常但界面无提示异常被平台捕获后未正确处理在插件方法内捕获并包装为业务异常打开详细日志锁等待严重插件中开启事务后未及时提交或长事务中调用远程API缩小事务边界远程调用放到事务外必要时用异步任务4.4 日志是定位插件问题的第一工具说实话很多插件问题不用看什么高大上的工具看日志就够了。NC运行日志在NCHome目录下的日志文件夹里操作日志、系统日志、错误日志是分开记录的。开发阶段我习惯把日志级别调到DEBUG专门盯着自己插件类名前缀的输出。这样做的好处是能立刻确认平台有没有加载这个类、插件代码走到了哪一步、执行顺序是否符合预期。如果日志里根本搜不到你注册的类名那说明问题出在注册阶段而不是业务逻辑阶段排查方向立刻就不一样了。还有一个我自己长期在用的技巧在插件代码的关键位置加上带明确标记的日志。入口、取数、调用后台、异常出口每个地方一行统一用类名做前缀。这样代码上线之后出问题能靠日志把问题快速圈定在某一段而不是到处翻代码。这个方法虽然朴素但实测比反复远程调试高效得多。尤其是在客户现场没有IDE调试条件的时候日志就是唯一的眼睛有没有埋好点直接决定排查效率。5. 插件注册开发的一点个人体会如果让我给刚开始做NC插件注册开发的人一句建议那就是先从最小的按钮插件开始跑通一个“注册-部署-生效”的完整闭环再考虑复杂业务。这个最小闭环会逼着你把环境、目录、依赖、缓存这些基础问题全部趟一遍之后再做任何插件无非就是复制套路。很多项目组一上来就做一堆复杂插件结果连最基础的注册环节都没弄明白后面越做越乱返工成本极高。还有一点是插件规范问题。NC平台允许在同一个扩展点上挂多个插件但不代表可以乱挂。我见过一个节点挂了十几个插件执行顺序混乱排查问题时谁都不敢动。建议的做法是同类扩展尽量合并到同一个插件模块里顺序号之间预留空隙方便后续插入新逻辑插件类名和ID保持语义化注释写明挂载点和业务用途代码上线前在测试环境完整跑一遍保存、审批、弃审三个核心动作确认没有影响到标准流程。最后分享一个我自己的开发习惯NC的插件机制虽然灵活但不要把所有扩展都塞进插件里。如果平台本身提供了标准配置项优先用标准配置只有标准功能确实满足不了需求时才考虑插件扩展。插件是锦上添花不是万能药。保持克制后续的升级维护会轻松非常多。本文还有配套的精品资源点击获取