2026/9/13 21:09:03
FEATURED · 精选文章 
1. 这不是“加个弹窗”那么简单NC65客开里自定义弹窗参照的真实战场你搜“NC65客开增加自定义弹窗参照”页面上全是零散的报错截图、断句的配置代码、还有人问“为什么点不开”“为什么查不到数据”。我干了十年用友系开发从UAP3.0到NC65亲手搭过上百个弹窗参照最常听到的一句话是“不就是拖个控件、写个查询逻辑吗半天搞定。”——结果呢项目上线前一周用户反馈“弹窗点开空白”“选中后主表字段不回填”“翻页卡死”“一查大数据量就超时”开发连夜改测试反复验业务方天天催。根本原因不是技术不会而是没吃透NC65这套体系里“参照”二字的分量。在NC65里“参照”从来不是UI组件而是一整套数据契约。它背后连着元数据模型、服务注册中心、缓存策略、权限校验链、甚至事务传播机制。你点的那个小弹窗本质是触发了一次跨层调用前端界面层 → UAP框架层 → 业务服务层 → 数据访问层 → 数据库。中间任何一环掉链子表现都是“弹窗打不开”或“数据对不上”。比如那个高频报错“nc65 cannot instiate plugin”十次有八次不是插件写错了而是你在服务注册时漏配了一个service标签里的scopesingleton属性导致UAP容器找不到实例再比如“查询接口实现分页”搜得最多但很多人只盯着SQL里加LIMIT却忘了NC65的分页必须走PageQuery对象直接拼offset会绕过UAP的缓存拦截器造成性能雪崩。这个需求真正要解决的是三个层面的问题第一界面层如何让弹窗长得像原生参照带搜索框、树形结构、多选支持、快捷键响应第二服务层如何把自定义查询逻辑无缝注入NC65的服务总线让它能被UAP框架识别、调度、缓存第三数据层如何确保回填字段与主表字段严格映射避免“客户档案”参照选中后主表的“客户编码”字段填的是ID而不是编码值。所以别再只抄网上那几行showDialog()代码了——那只是冰山露出水面的尖角。下面我就按真实项目交付的顺序把从设计、编码、调试到上线的全链路掰开揉碎讲清楚包括那些UAP官方文档里绝不会写的坑。2. 设计阶段先画清三张图再动一行代码2.1 业务场景图搞清“谁在什么时候用这个弹窗干什么”很多开发一上来就写代码结果做出来的东西业务方根本不用。我习惯先和业务顾问一起画一张极简的场景图。比如这次需求客户要的是“在采购订单新增界面点击‘供应商’字段旁的放大镜弹出一个自定义弹窗里面能按‘所属行业’‘信用等级’筛选并支持多选选中后自动回填‘供应商编码’和‘供应商名称’到主表”。注意这里藏着四个关键约束触发时机是单击放大镜图标触发还是双击字段触发NC65默认是单击图标如果你改成双击就得重写FieldEvent监听器成本翻倍筛选维度“所属行业”“信用等级”是基础档案字段还是需要关联查询的扩展属性前者直接查t_bd_supplier表就行后者就得写关联SQL还要考虑UAP的JoinTable注解是否生效多选支持NC65原生参照默认单选要多选必须启用multiSelecttrue但这会改变回填逻辑——单选回填一个值多选回填JSON数组主表字段类型必须是String且长度足够存[SUP001,SUP002]回填字段明确要求回填“供应商编码”和“供应商名称”意味着弹窗返回的数据结构必须包含pk_supplier和name两个key且主表的suppliercode和suppliername字段的refCode属性必须指向这两个key。提示如果业务方说“跟客户档案参照一样就行”千万别信。客户档案参照是NC65内置的重量级参照用了BDRefModel基类、BDRefService服务、还集成了组织架构权限过滤。你抄它的XML配置90%概率报cannot instiate plugin——因为你的自定义类没继承正确的基类。2.2 技术架构图看清UAP框架里数据怎么流NC65的弹窗参照不是独立模块它嵌在UAP的MVCSOA混合架构里。我画了这张简化的数据流向图帮你避开80%的集成错误[前端界面] ↓ (HTTP POST, /nccloud/xxx/refdialog) [Web层 - RefDialogController] ↓ (Spring MVC DispatcherServlet) [服务层 - RefDialogService] ← 注册在UAP服务总线 ↓ (UAP Service Bus 调用) [业务服务层 - 自定义RefServiceImpl] ← 你写的类必须实现IRefService接口 ↓ (MyBatis Mapper 或 JDBC Template) [数据访问层 - SupplierMapper.xml] ← SQL写在这里必须用PageQuery分页 ↓ [数据库]关键点在于中间的RefDialogService。它不是你写的是UAP框架提供的。你唯一要做的是把自己的RefServiceImpl注册成它可调用的服务。注册方式有两种XML配置老项目常用和注解配置新项目推荐。XML方式要写bean idsupplierRefService classcom.xxx.SupplierRefServiceImpl scopesingleton/并确保service标签里interfacecom.ufida.nc.api.ref.IRefService注解方式则要在类上加Service(supplierRefService)和Override实现IRefService的queryData方法。漏掉scopesingleton或Service里的id不匹配就是那个经典的cannot instiate plugin报错根源。2.3 数据契约图定义弹窗和主表之间的“语言”参照的本质是数据契约。你弹窗返回的数据格式必须和主表字段的refCode属性严格对应。比如主表有个字段定义property namesuppliercode typestring length30 refCodepk_supplier/ property namesuppliername typestring length100 refCodename/那么你的弹窗查询结果每一行数据必须是Map结构且必须包含pk_supplier和name两个keyMapString, Object row new HashMap(); row.put(pk_supplier, SUP001); // 注意key名必须完全一致区分大小写 row.put(name, 北京某某科技有限公司);如果业务方临时说“还要回填联系人电话”你就不能简单地在Map里加phone而必须去主表XML里给对应字段加refCodephone否则框架压根不认这个字段。我见过太多人在这里栽跟头SQL里查出了tel字段Map里put了tel但主表没配refCode结果弹窗选中后电话号就是不显示——不是代码bug是契约没签。3. 核心实现从XML配置到Java代码的完整闭环3.1 前端配置让弹窗长得像NC65原生的三步法NC65的弹窗参照前端由RefField控件驱动它的行为完全由XML配置决定。别指望用JS硬改UAP框架会拦截所有非标准操作。正确做法是三步第一步在主表的Form XML里声明参照字段找到采购订单的Form定义文件如PurchaseOrderForm.xml定位到供应商字段property namesuppliercode typestring length30 refCodepk_supplier/在它后面加一行refType属性property namesuppliercode typestring length30 refCodepk_supplier refTypesupplierRef/这里的supplierRef就是你给这个参照起的代号必须全局唯一后续所有配置都靠它串联。第二步定义参照的元数据XML新建文件supplierRef.xml放在/src/main/resources/ref/目录下路径必须准确UAP按约定路径扫描?xml version1.0 encodingUTF-8? refdef idsupplierRef name供应商参照 serviceIdsupplierRefService search field nameindustry label所属行业 typestring / field namecreditLevel label信用等级 typestring / /search columns column namepk_supplier label供应商编码 width120 / column namename label供应商名称 width200 / column nametel label联系电话 width120 / /columns returnFields returnField refCodepk_supplier / returnField refCodename / /returnFields /refdef重点看serviceIdsupplierRefService——这行代码告诉UAP“当用户点这个弹窗时请调用ID为supplierRefService的服务”。而returnFields里列出的refCode必须和主表字段的refCode完全一致一个字母都不能错。第三步配置弹窗样式与行为在同一个supplierRef.xml里追加dialog节点dialog width800 height500 multiSelecttrue showSearchtrue toolbar button namerefresh label刷新 / button nameexport label导出 / /toolbar /dialogmultiSelecttrue开启多选showSearchtrue显示顶部搜索栏。注意width和height单位是像素别写成800pxUAP会解析失败。toolbar里的按钮是UAP内置的你不用写JS框架自动绑定事件。实操心得XML文件名supplierRef.xml必须和refdef idsupplierRef里的id一致且整个文件必须UTF-8无BOM编码。我曾因编辑器保存时加了BOM导致UAP加载XML失败日志里只报“refdef not found”排查了三天才发现是编码问题。3.2 后端服务实现IRefService接口的五个必填项UAP要求所有参照服务必须实现com.ufida.nc.api.ref.IRefService接口。这个接口只有两个方法但每个方法都有魔鬼细节public RefResult queryData(RefParam param)—— 查询的核心RefParam对象里封装了所有前端传来的参数getSearchCondition()返回筛选条件Map如{industry:IT,creditLevel:AAA}getPageQuery()返回分页对象。你必须用PageQuery不能自己算offsetOverride public RefResult queryData(RefParam param) { // 1. 获取筛选条件 MapString, Object condition param.getSearchCondition(); // 2. 构建分页对象UAP强制要求 PageQuery pageQuery param.getPageQuery(); // 3. 调用Mapper传入condition和pageQuery ListMapString, Object dataList supplierMapper.queryByCondition(condition, pageQuery); // 4. 封装结果 RefResult result new RefResult(); result.setDataList(dataList); result.setTotalCount(pageQuery.getTotalCount()); // 注意totalCount必须手动设置 return result; }关键点pageQuery.getTotalCount()不是自动计算的你必须在Mapper里单独执行一次count查询然后赋值给pageQuery.setTotalCount(count)。UAP框架不会帮你查总数这是性能优化设计——大数据量时count比select快得多。public RefResult getRefData(String[] pks)—— 回填的兜底逻辑当用户从其他地方如历史记录直接输入编码UAP会调用这个方法查详情。你必须根据主键数组查出完整数据Override public RefResult getRefData(String[] pks) { ListMapString, Object dataList supplierMapper.queryByIds(pks); RefResult result new RefResult(); result.setDataList(dataList); return result; }如果这里没实现用户手动输入编码后点“确定”弹窗会报错“无法获取参照数据”。注意queryData和getRefData返回的dataList里每个Map的key必须是小写字母开头的驼峰命名如pk_supplier不能是下划线PK_SUPPLIER或大写PK_SUPPLIER否则UAP反射赋值失败回填为空。3.3 数据访问层Mapper里的分页陷阱与SQL优化NC65的MyBatis Mapper必须严格遵循UAP规范。SupplierMapper.xml里不能写普通SQL必须用select idqueryByCondition parameterTypemap resultTypemap且SQL里必须包含limit #{pageQuery.pageSize} offset #{pageQuery.startRow}select idqueryByCondition parameterTypemap resultTypemap SELECT t.pk_supplier AS pk_supplier, t.name AS name, t.tel AS tel FROM t_bd_supplier t WHERE 11 if testindustry ! null and industry ! AND t.industry #{industry} /if if testcreditLevel ! null and creditLevel ! AND t.credit_level #{creditLevel} /if ORDER BY t.name LIMIT #{pageQuery.pageSize} OFFSET #{pageQuery.startRow} /selectstartRow是UAP计算好的偏移量pageSize * (currentPage - 1)你不能自己算。更关键的是必须单独写一个count查询select idcountByCondition parameterTypemap resultTypejava.lang.Long SELECT COUNT(*) FROM t_bd_supplier t WHERE 11 if testindustry ! null and industry ! AND t.industry #{industry} /if if testcreditLevel ! null and creditLevel ! AND t.credit_level #{creditLevel} /if /select然后在Service里调用Long count supplierMapper.countByCondition(condition); pageQuery.setTotalCount(count); // 这行必须有如果省略count查询分页会失效永远只显示第一页。4. 调试与上线从报错日志到生产环境的实战 checklist4.1 本地调试五步快速定位90%的问题UAP的日志是调试的黄金线索。别盲目重启服务器按顺序查第一步查UAP服务注册日志启动时搜索Registering service确认你的supplierRefService是否注册成功INFO [main] o.s.b.f.s.DefaultListableBeanFactory - Registering bean supplierRefService with name supplierRefService如果没有这行检查Service(supplierRefService)的id是否和XML里的serviceId一致或者XML配置是否放在了/ref/目录下。第二步查弹窗打开日志点击放大镜在ncserver.log里搜RefDialogControllerDEBUG [http-nio-8080-exec-1] c.u.n.c.w.r.RefDialogController - Ref dialog request for refId: supplierRef如果没这行说明前端XML的refType没配对或者supplierRef.xml文件名/路径错了。第三步查服务调用日志搜calling serviceDEBUG [http-nio-8080-exec-1] c.u.n.c.s.r.RefDialogService - Calling service supplierRefService to query data如果没这行serviceId配置错误如果有这行但没后续说明你的queryData方法抛异常了。第四步查SQL执行日志开启MyBatis日志log4j.logger.com.xxx.mapperDEBUG看SQL是否执行DEBUG [http-nio-8080-exec-1] c.x.m.S.queryByCondition - Preparing: SELECT ... LIMIT ? OFFSET ? DEBUG [http-nio-8080-exec-1] c.x.m.S.queryByCondition - Parameters: 20(Integer), 0(Integer)如果SQL没执行检查Mapper的namespace是否和Service类包名一致如果执行了但没结果检查conditionMap里的key是否和SQL里的#{industry}一致注意大小写。第五步查回填日志选中数据点确定后搜ref result returnedDEBUG [http-nio-8080-exec-1] c.u.n.c.s.r.RefDialogService - Ref result returned: {pk_supplierSUP001, name北京某某科技有限公司}如果没这行queryData返回的Map key错了如果有这行但主表没填上检查主表XML的refCode是否匹配。4.2 生产环境 checklist上线前必须验证的七件事我把每次上线前的检查清单打印贴在显示器边少一项都敢不发布XML文件校验用Notepad的XML Tools插件验证supplierRef.xml语法确保没有未闭合标签服务ID一致性supplierRef.xml里的serviceId、Service注解里的id、applicationContext.xml里的bean id如果用XML配置三者必须完全相同字段映射验证主表XML的refCode和弹窗返回Map的key逐字比对用Excel列对比功能避免肉眼误差分页逻辑验证在测试环境用1000条数据手动翻到第50页确认startRow计算正确应为20*49980空值处理验证筛选条件全为空时SQL是否返回全部数据WHERE 11必须存在多选回填验证选中3个供应商确认主表字段存的是[SUP001,SUP002,SUP003]格式的字符串而非对象权限校验验证用不同角色账号登录确认无权限的用户点弹窗时提示“无此操作权限”而非空白页。实操心得有一次上线后用户反馈“弹窗点开慢”查日志发现countByCondition查询耗时2秒。原来SQL里AND t.industry #{industry}没加索引。我们给t_bd_supplier.industry字段加了B-tree索引查询降到50ms。记住NC65的参照查询90%的性能问题都在数据库索引上不是代码问题。4.3 常见报错速查表从现象到根因的精准打击现象日志关键词根本原因解决方案弹窗点开空白控制台无报错RefDialogController - Ref dialog request for refId: xxx有但无后续supplierRef.xml里refdef的id和refType不一致检查refTypexxx和refdef idxxx是否完全相同点确定后主表字段为空Ref result returned: {pk_supplierSUP001}有但主表没填主表XML的refCode和返回Map的key不匹配如返回pk_supplier主表写suppliercode用CtrlF全文搜索确保refCode值和Map key完全一致分页只显示第一页翻页无效PageQuery - startRow0, pageSize20每次都是0pageQuery.setTotalCount(count)没调用或count查询没执行在queryData方法里必须先执行count查询再调用setTotalCount多选后主表字段存的是[object Object]Ref result returned: [{pk_supplierSUP001}, {pk_supplierSUP002}]RefResult.setDataList()传入的是对象列表不是Map列表确保dataList是ListMapString, Object不是ListSupplierEntity点弹窗报cannot instiate pluginFailed to instantiate [xxx.RefServiceImpl]类没加Service注解或scopesingleton缺失XML配置时检查Spring配置确保Bean作用域是singleton且实现了IRefService5. 进阶技巧让自定义参照真正融入NC65生态5.1 权限控制复用NC65的组织架构权限模型NC65的参照默认无权限控制所有用户都能查全部数据。要接入组织架构权限不能自己写SQL过滤必须用UAP的OrgPermissionUtilOverride public RefResult queryData(RefParam param) { MapString, Object condition param.getSearchCondition(); // 获取当前用户可见的组织范围 String orgWhere OrgPermissionUtil.getOrgWhere(t.pk_org); // 拼接到SQL里 condition.put(orgWhere, orgWhere); ListMapString, Object dataList supplierMapper.queryByCondition(condition, pageQuery); // ... }getOrgWhere(t.pk_org)会根据当前用户的角色、岗位、组织隶属关系动态生成AND t.pk_org IN (ORG001,ORG002)这样的SQL片段。这样销售部员工只能看到自己部门的供应商财务部能看到全公司——权限逻辑完全复用NC65原生模型不用额外开发。5.2 缓存优化避免重复查询的两级缓存策略大数据量参照频繁查询直接查库压力大。UAP提供了Cacheable注解但要注意两点一是缓存key必须包含筛选条件二是要配置缓存过期时间Cacheable(value supplierRefCache, key #param.searchCondition.toString() _ #param.pageQuery.pageSize) Override public RefResult queryData(RefParam param) { // ... }key里拼了searchCondition.toString()确保不同筛选条件走不同缓存valuesupplierRefCache对应ehcache.xml里的缓存配置cache namesupplierRefCache maxElementsInMemory1000 timeToLiveSeconds300 !-- 5分钟过期 -- overflowToDiskfalse/这样同一条件的查询5分钟内只查一次库后续直接走内存缓存。5.3 REST接口暴露对接外部系统的标准姿势客户要求“用友NC65 rest接口”供其他系统调用。UAP的REST服务必须走RestController但参照查询要复用已有逻辑不能重写RestController RequestMapping(/api/ref/supplier) public class SupplierRefRestController { Autowired private SupplierRefServiceImpl supplierRefService; // 直接注入你的Service GetMapping(/query) public ResponseEntityRefResult query(RequestParam MapString, String params) { // 将params转为RefParam RefParam param new RefParam(); param.setSearchCondition(params); param.setPageQuery(new PageQuery(20, 1)); // 默认查第一页20条 RefResult result supplierRefService.queryData(param); return ResponseEntity.ok(result); } }关键点Autowired注入的是你已注册的SupplierRefServiceImpl不是新new的对象确保缓存、事务等UAP特性依然生效。URL/api/ref/supplier/query符合REST规范外部系统用GET请求即可调用。最后分享个小技巧我在所有自定义参照的supplierRef.xml里都会加一行注释!-- Created by [你的名字] on [日期] --。不是为了留名而是当项目交接时运维同事一眼就能看出这个参照是谁写的、什么时候上线的避免扯皮。技术人的专业就藏在这些不起眼的细节里。
NC65自定义弹窗参照全链路实现与避坑指南
1. 这不是“加个弹窗”那么简单NC65客开里自定义弹窗参照的真实战场你搜“NC65客开增加自定义弹窗参照”页面上全是零散的报错截图、断句的配置代码、还有人问“为什么点不开”“为什么查不到数据”。我干了十年用友系开发从UAP3.0到NC65亲手搭过上百个弹窗参照最常听到的一句话是“不就是拖个控件、写个查询逻辑吗半天搞定。”——结果呢项目上线前一周用户反馈“弹窗点开空白”“选中后主表字段不回填”“翻页卡死”“一查大数据量就超时”开发连夜改测试反复验业务方天天催。根本原因不是技术不会而是没吃透NC65这套体系里“参照”二字的分量。在NC65里“参照”从来不是UI组件而是一整套数据契约。它背后连着元数据模型、服务注册中心、缓存策略、权限校验链、甚至事务传播机制。你点的那个小弹窗本质是触发了一次跨层调用前端界面层 → UAP框架层 → 业务服务层 → 数据访问层 → 数据库。中间任何一环掉链子表现都是“弹窗打不开”或“数据对不上”。比如那个高频报错“nc65 cannot instiate plugin”十次有八次不是插件写错了而是你在服务注册时漏配了一个service标签里的scopesingleton属性导致UAP容器找不到实例再比如“查询接口实现分页”搜得最多但很多人只盯着SQL里加LIMIT却忘了NC65的分页必须走PageQuery对象直接拼offset会绕过UAP的缓存拦截器造成性能雪崩。这个需求真正要解决的是三个层面的问题第一界面层如何让弹窗长得像原生参照带搜索框、树形结构、多选支持、快捷键响应第二服务层如何把自定义查询逻辑无缝注入NC65的服务总线让它能被UAP框架识别、调度、缓存第三数据层如何确保回填字段与主表字段严格映射避免“客户档案”参照选中后主表的“客户编码”字段填的是ID而不是编码值。所以别再只抄网上那几行showDialog()代码了——那只是冰山露出水面的尖角。下面我就按真实项目交付的顺序把从设计、编码、调试到上线的全链路掰开揉碎讲清楚包括那些UAP官方文档里绝不会写的坑。2. 设计阶段先画清三张图再动一行代码2.1 业务场景图搞清“谁在什么时候用这个弹窗干什么”很多开发一上来就写代码结果做出来的东西业务方根本不用。我习惯先和业务顾问一起画一张极简的场景图。比如这次需求客户要的是“在采购订单新增界面点击‘供应商’字段旁的放大镜弹出一个自定义弹窗里面能按‘所属行业’‘信用等级’筛选并支持多选选中后自动回填‘供应商编码’和‘供应商名称’到主表”。注意这里藏着四个关键约束触发时机是单击放大镜图标触发还是双击字段触发NC65默认是单击图标如果你改成双击就得重写FieldEvent监听器成本翻倍筛选维度“所属行业”“信用等级”是基础档案字段还是需要关联查询的扩展属性前者直接查t_bd_supplier表就行后者就得写关联SQL还要考虑UAP的JoinTable注解是否生效多选支持NC65原生参照默认单选要多选必须启用multiSelecttrue但这会改变回填逻辑——单选回填一个值多选回填JSON数组主表字段类型必须是String且长度足够存[SUP001,SUP002]回填字段明确要求回填“供应商编码”和“供应商名称”意味着弹窗返回的数据结构必须包含pk_supplier和name两个key且主表的suppliercode和suppliername字段的refCode属性必须指向这两个key。提示如果业务方说“跟客户档案参照一样就行”千万别信。客户档案参照是NC65内置的重量级参照用了BDRefModel基类、BDRefService服务、还集成了组织架构权限过滤。你抄它的XML配置90%概率报cannot instiate plugin——因为你的自定义类没继承正确的基类。2.2 技术架构图看清UAP框架里数据怎么流NC65的弹窗参照不是独立模块它嵌在UAP的MVCSOA混合架构里。我画了这张简化的数据流向图帮你避开80%的集成错误[前端界面] ↓ (HTTP POST, /nccloud/xxx/refdialog) [Web层 - RefDialogController] ↓ (Spring MVC DispatcherServlet) [服务层 - RefDialogService] ← 注册在UAP服务总线 ↓ (UAP Service Bus 调用) [业务服务层 - 自定义RefServiceImpl] ← 你写的类必须实现IRefService接口 ↓ (MyBatis Mapper 或 JDBC Template) [数据访问层 - SupplierMapper.xml] ← SQL写在这里必须用PageQuery分页 ↓ [数据库]关键点在于中间的RefDialogService。它不是你写的是UAP框架提供的。你唯一要做的是把自己的RefServiceImpl注册成它可调用的服务。注册方式有两种XML配置老项目常用和注解配置新项目推荐。XML方式要写bean idsupplierRefService classcom.xxx.SupplierRefServiceImpl scopesingleton/并确保service标签里interfacecom.ufida.nc.api.ref.IRefService注解方式则要在类上加Service(supplierRefService)和Override实现IRefService的queryData方法。漏掉scopesingleton或Service里的id不匹配就是那个经典的cannot instiate plugin报错根源。2.3 数据契约图定义弹窗和主表之间的“语言”参照的本质是数据契约。你弹窗返回的数据格式必须和主表字段的refCode属性严格对应。比如主表有个字段定义property namesuppliercode typestring length30 refCodepk_supplier/ property namesuppliername typestring length100 refCodename/那么你的弹窗查询结果每一行数据必须是Map结构且必须包含pk_supplier和name两个keyMapString, Object row new HashMap(); row.put(pk_supplier, SUP001); // 注意key名必须完全一致区分大小写 row.put(name, 北京某某科技有限公司);如果业务方临时说“还要回填联系人电话”你就不能简单地在Map里加phone而必须去主表XML里给对应字段加refCodephone否则框架压根不认这个字段。我见过太多人在这里栽跟头SQL里查出了tel字段Map里put了tel但主表没配refCode结果弹窗选中后电话号就是不显示——不是代码bug是契约没签。3. 核心实现从XML配置到Java代码的完整闭环3.1 前端配置让弹窗长得像NC65原生的三步法NC65的弹窗参照前端由RefField控件驱动它的行为完全由XML配置决定。别指望用JS硬改UAP框架会拦截所有非标准操作。正确做法是三步第一步在主表的Form XML里声明参照字段找到采购订单的Form定义文件如PurchaseOrderForm.xml定位到供应商字段property namesuppliercode typestring length30 refCodepk_supplier/在它后面加一行refType属性property namesuppliercode typestring length30 refCodepk_supplier refTypesupplierRef/这里的supplierRef就是你给这个参照起的代号必须全局唯一后续所有配置都靠它串联。第二步定义参照的元数据XML新建文件supplierRef.xml放在/src/main/resources/ref/目录下路径必须准确UAP按约定路径扫描?xml version1.0 encodingUTF-8? refdef idsupplierRef name供应商参照 serviceIdsupplierRefService search field nameindustry label所属行业 typestring / field namecreditLevel label信用等级 typestring / /search columns column namepk_supplier label供应商编码 width120 / column namename label供应商名称 width200 / column nametel label联系电话 width120 / /columns returnFields returnField refCodepk_supplier / returnField refCodename / /returnFields /refdef重点看serviceIdsupplierRefService——这行代码告诉UAP“当用户点这个弹窗时请调用ID为supplierRefService的服务”。而returnFields里列出的refCode必须和主表字段的refCode完全一致一个字母都不能错。第三步配置弹窗样式与行为在同一个supplierRef.xml里追加dialog节点dialog width800 height500 multiSelecttrue showSearchtrue toolbar button namerefresh label刷新 / button nameexport label导出 / /toolbar /dialogmultiSelecttrue开启多选showSearchtrue显示顶部搜索栏。注意width和height单位是像素别写成800pxUAP会解析失败。toolbar里的按钮是UAP内置的你不用写JS框架自动绑定事件。实操心得XML文件名supplierRef.xml必须和refdef idsupplierRef里的id一致且整个文件必须UTF-8无BOM编码。我曾因编辑器保存时加了BOM导致UAP加载XML失败日志里只报“refdef not found”排查了三天才发现是编码问题。3.2 后端服务实现IRefService接口的五个必填项UAP要求所有参照服务必须实现com.ufida.nc.api.ref.IRefService接口。这个接口只有两个方法但每个方法都有魔鬼细节public RefResult queryData(RefParam param)—— 查询的核心RefParam对象里封装了所有前端传来的参数getSearchCondition()返回筛选条件Map如{industry:IT,creditLevel:AAA}getPageQuery()返回分页对象。你必须用PageQuery不能自己算offsetOverride public RefResult queryData(RefParam param) { // 1. 获取筛选条件 MapString, Object condition param.getSearchCondition(); // 2. 构建分页对象UAP强制要求 PageQuery pageQuery param.getPageQuery(); // 3. 调用Mapper传入condition和pageQuery ListMapString, Object dataList supplierMapper.queryByCondition(condition, pageQuery); // 4. 封装结果 RefResult result new RefResult(); result.setDataList(dataList); result.setTotalCount(pageQuery.getTotalCount()); // 注意totalCount必须手动设置 return result; }关键点pageQuery.getTotalCount()不是自动计算的你必须在Mapper里单独执行一次count查询然后赋值给pageQuery.setTotalCount(count)。UAP框架不会帮你查总数这是性能优化设计——大数据量时count比select快得多。public RefResult getRefData(String[] pks)—— 回填的兜底逻辑当用户从其他地方如历史记录直接输入编码UAP会调用这个方法查详情。你必须根据主键数组查出完整数据Override public RefResult getRefData(String[] pks) { ListMapString, Object dataList supplierMapper.queryByIds(pks); RefResult result new RefResult(); result.setDataList(dataList); return result; }如果这里没实现用户手动输入编码后点“确定”弹窗会报错“无法获取参照数据”。注意queryData和getRefData返回的dataList里每个Map的key必须是小写字母开头的驼峰命名如pk_supplier不能是下划线PK_SUPPLIER或大写PK_SUPPLIER否则UAP反射赋值失败回填为空。3.3 数据访问层Mapper里的分页陷阱与SQL优化NC65的MyBatis Mapper必须严格遵循UAP规范。SupplierMapper.xml里不能写普通SQL必须用select idqueryByCondition parameterTypemap resultTypemap且SQL里必须包含limit #{pageQuery.pageSize} offset #{pageQuery.startRow}select idqueryByCondition parameterTypemap resultTypemap SELECT t.pk_supplier AS pk_supplier, t.name AS name, t.tel AS tel FROM t_bd_supplier t WHERE 11 if testindustry ! null and industry ! AND t.industry #{industry} /if if testcreditLevel ! null and creditLevel ! AND t.credit_level #{creditLevel} /if ORDER BY t.name LIMIT #{pageQuery.pageSize} OFFSET #{pageQuery.startRow} /selectstartRow是UAP计算好的偏移量pageSize * (currentPage - 1)你不能自己算。更关键的是必须单独写一个count查询select idcountByCondition parameterTypemap resultTypejava.lang.Long SELECT COUNT(*) FROM t_bd_supplier t WHERE 11 if testindustry ! null and industry ! AND t.industry #{industry} /if if testcreditLevel ! null and creditLevel ! AND t.credit_level #{creditLevel} /if /select然后在Service里调用Long count supplierMapper.countByCondition(condition); pageQuery.setTotalCount(count); // 这行必须有如果省略count查询分页会失效永远只显示第一页。4. 调试与上线从报错日志到生产环境的实战 checklist4.1 本地调试五步快速定位90%的问题UAP的日志是调试的黄金线索。别盲目重启服务器按顺序查第一步查UAP服务注册日志启动时搜索Registering service确认你的supplierRefService是否注册成功INFO [main] o.s.b.f.s.DefaultListableBeanFactory - Registering bean supplierRefService with name supplierRefService如果没有这行检查Service(supplierRefService)的id是否和XML里的serviceId一致或者XML配置是否放在了/ref/目录下。第二步查弹窗打开日志点击放大镜在ncserver.log里搜RefDialogControllerDEBUG [http-nio-8080-exec-1] c.u.n.c.w.r.RefDialogController - Ref dialog request for refId: supplierRef如果没这行说明前端XML的refType没配对或者supplierRef.xml文件名/路径错了。第三步查服务调用日志搜calling serviceDEBUG [http-nio-8080-exec-1] c.u.n.c.s.r.RefDialogService - Calling service supplierRefService to query data如果没这行serviceId配置错误如果有这行但没后续说明你的queryData方法抛异常了。第四步查SQL执行日志开启MyBatis日志log4j.logger.com.xxx.mapperDEBUG看SQL是否执行DEBUG [http-nio-8080-exec-1] c.x.m.S.queryByCondition - Preparing: SELECT ... LIMIT ? OFFSET ? DEBUG [http-nio-8080-exec-1] c.x.m.S.queryByCondition - Parameters: 20(Integer), 0(Integer)如果SQL没执行检查Mapper的namespace是否和Service类包名一致如果执行了但没结果检查conditionMap里的key是否和SQL里的#{industry}一致注意大小写。第五步查回填日志选中数据点确定后搜ref result returnedDEBUG [http-nio-8080-exec-1] c.u.n.c.s.r.RefDialogService - Ref result returned: {pk_supplierSUP001, name北京某某科技有限公司}如果没这行queryData返回的Map key错了如果有这行但主表没填上检查主表XML的refCode是否匹配。4.2 生产环境 checklist上线前必须验证的七件事我把每次上线前的检查清单打印贴在显示器边少一项都敢不发布XML文件校验用Notepad的XML Tools插件验证supplierRef.xml语法确保没有未闭合标签服务ID一致性supplierRef.xml里的serviceId、Service注解里的id、applicationContext.xml里的bean id如果用XML配置三者必须完全相同字段映射验证主表XML的refCode和弹窗返回Map的key逐字比对用Excel列对比功能避免肉眼误差分页逻辑验证在测试环境用1000条数据手动翻到第50页确认startRow计算正确应为20*49980空值处理验证筛选条件全为空时SQL是否返回全部数据WHERE 11必须存在多选回填验证选中3个供应商确认主表字段存的是[SUP001,SUP002,SUP003]格式的字符串而非对象权限校验验证用不同角色账号登录确认无权限的用户点弹窗时提示“无此操作权限”而非空白页。实操心得有一次上线后用户反馈“弹窗点开慢”查日志发现countByCondition查询耗时2秒。原来SQL里AND t.industry #{industry}没加索引。我们给t_bd_supplier.industry字段加了B-tree索引查询降到50ms。记住NC65的参照查询90%的性能问题都在数据库索引上不是代码问题。4.3 常见报错速查表从现象到根因的精准打击现象日志关键词根本原因解决方案弹窗点开空白控制台无报错RefDialogController - Ref dialog request for refId: xxx有但无后续supplierRef.xml里refdef的id和refType不一致检查refTypexxx和refdef idxxx是否完全相同点确定后主表字段为空Ref result returned: {pk_supplierSUP001}有但主表没填主表XML的refCode和返回Map的key不匹配如返回pk_supplier主表写suppliercode用CtrlF全文搜索确保refCode值和Map key完全一致分页只显示第一页翻页无效PageQuery - startRow0, pageSize20每次都是0pageQuery.setTotalCount(count)没调用或count查询没执行在queryData方法里必须先执行count查询再调用setTotalCount多选后主表字段存的是[object Object]Ref result returned: [{pk_supplierSUP001}, {pk_supplierSUP002}]RefResult.setDataList()传入的是对象列表不是Map列表确保dataList是ListMapString, Object不是ListSupplierEntity点弹窗报cannot instiate pluginFailed to instantiate [xxx.RefServiceImpl]类没加Service注解或scopesingleton缺失XML配置时检查Spring配置确保Bean作用域是singleton且实现了IRefService5. 进阶技巧让自定义参照真正融入NC65生态5.1 权限控制复用NC65的组织架构权限模型NC65的参照默认无权限控制所有用户都能查全部数据。要接入组织架构权限不能自己写SQL过滤必须用UAP的OrgPermissionUtilOverride public RefResult queryData(RefParam param) { MapString, Object condition param.getSearchCondition(); // 获取当前用户可见的组织范围 String orgWhere OrgPermissionUtil.getOrgWhere(t.pk_org); // 拼接到SQL里 condition.put(orgWhere, orgWhere); ListMapString, Object dataList supplierMapper.queryByCondition(condition, pageQuery); // ... }getOrgWhere(t.pk_org)会根据当前用户的角色、岗位、组织隶属关系动态生成AND t.pk_org IN (ORG001,ORG002)这样的SQL片段。这样销售部员工只能看到自己部门的供应商财务部能看到全公司——权限逻辑完全复用NC65原生模型不用额外开发。5.2 缓存优化避免重复查询的两级缓存策略大数据量参照频繁查询直接查库压力大。UAP提供了Cacheable注解但要注意两点一是缓存key必须包含筛选条件二是要配置缓存过期时间Cacheable(value supplierRefCache, key #param.searchCondition.toString() _ #param.pageQuery.pageSize) Override public RefResult queryData(RefParam param) { // ... }key里拼了searchCondition.toString()确保不同筛选条件走不同缓存valuesupplierRefCache对应ehcache.xml里的缓存配置cache namesupplierRefCache maxElementsInMemory1000 timeToLiveSeconds300 !-- 5分钟过期 -- overflowToDiskfalse/这样同一条件的查询5分钟内只查一次库后续直接走内存缓存。5.3 REST接口暴露对接外部系统的标准姿势客户要求“用友NC65 rest接口”供其他系统调用。UAP的REST服务必须走RestController但参照查询要复用已有逻辑不能重写RestController RequestMapping(/api/ref/supplier) public class SupplierRefRestController { Autowired private SupplierRefServiceImpl supplierRefService; // 直接注入你的Service GetMapping(/query) public ResponseEntityRefResult query(RequestParam MapString, String params) { // 将params转为RefParam RefParam param new RefParam(); param.setSearchCondition(params); param.setPageQuery(new PageQuery(20, 1)); // 默认查第一页20条 RefResult result supplierRefService.queryData(param); return ResponseEntity.ok(result); } }关键点Autowired注入的是你已注册的SupplierRefServiceImpl不是新new的对象确保缓存、事务等UAP特性依然生效。URL/api/ref/supplier/query符合REST规范外部系统用GET请求即可调用。最后分享个小技巧我在所有自定义参照的supplierRef.xml里都会加一行注释!-- Created by [你的名字] on [日期] --。不是为了留名而是当项目交接时运维同事一眼就能看出这个参照是谁写的、什么时候上线的避免扯皮。技术人的专业就藏在这些不起眼的细节里。 
