簡(jiǎn)介面向用友 NC65 二次開(kāi)發(fā)者的常見(jiàn) API 速查手冊(cè)內(nèi)容緊扣平臺(tái)開(kāi)發(fā)中的高頻需求覆蓋獲取表體行列、設(shè)置初始化默認(rèn)值、控制字段可編輯狀態(tài)、小數(shù)位數(shù)設(shè)置、報(bào)表合計(jì)行顯示、查詢面板取值、時(shí)間比較、編輯公式、按鈕權(quán)限控制、彈出提示框、打印查詢條件、清空表體與緩沖數(shù)據(jù)、查詢對(duì)話框默認(rèn)值、界面數(shù)據(jù)訪問(wèn)及導(dǎo)出導(dǎo)入數(shù)據(jù)庫(kù)等典型場(chǎng)景。每個(gè) API 均配有可直接參考的 Java 代碼示例并說(shuō)明適用位置與操作要點(diǎn)適合新手對(duì)照學(xué)習(xí)或作為日常開(kāi)發(fā)手冊(cè)查閱。資源包只有一個(gè) PDF 文檔體積僅 193KB輕量易用目前已吸引 579 人學(xué)習(xí)下載。文檔后段還整理了管理型界面單據(jù)類繼承關(guān)系、UI 工廠自定義按鈕、根據(jù)單據(jù)狀態(tài)控制按鈕可用性、單據(jù)開(kāi)發(fā)一般步驟、List/Map/Set 操作等進(jìn)階內(nèi)容能幫助開(kāi)發(fā)者減少摸索成本快速形成規(guī)范的 NC65 開(kāi)發(fā)思路。無(wú)論是剛接觸 NC65 的初學(xué)者還是需要快速定位接口的開(kāi)發(fā)者都能從這份精煉手冊(cè)中受益。1. NC65 開(kāi)發(fā)入門(mén)為什么先要搞懂這幾個(gè) APINC65 是用友基于 Java EE 體系構(gòu)建的企業(yè)級(jí) ERP 平臺(tái)客開(kāi)客戶化開(kāi)發(fā)是繞不開(kāi)的主題。新手拿到 NC65 的二次開(kāi)發(fā)任務(wù)第一反應(yīng)往往是打開(kāi) IDE 寫(xiě)代碼但真正的門(mén)檻在于搞清楚「NC65 把數(shù)據(jù)操作封裝到了哪一層」。前端界面是 NCClient后端邏輯跑在中間件上數(shù)據(jù)庫(kù)是 Oracle 或 SQL Server這三層之間的數(shù)據(jù)流轉(zhuǎn)全部依賴平臺(tái)自帶的 API。你直接寫(xiě) JDBC 也能跑但很快就會(huì)遇到單據(jù)模板取數(shù)、審批流狀態(tài)回寫(xiě)、組織權(quán)限過(guò)濾這些問(wèn)題手動(dòng)處理成本極高。這一篇從實(shí)際開(kāi)發(fā)視角出發(fā)圍繞 NC65 里出現(xiàn)頻率最高的一組 API基礎(chǔ)檔案查詢queryByCondition、單據(jù)保存save/update、審批流操作、SQL 查詢引擎persistenceApi / NCApi以及參數(shù)配置nc.uap.mw.sp.pub.sf.BaseAppServlet把「拿來(lái)就能用」的代碼和參數(shù)講透。目標(biāo)讀者是剛接手 NC65 項(xiàng)目、或者從其他 Java Web 框架轉(zhuǎn)過(guò)來(lái)的開(kāi)發(fā)讀完后能獨(dú)立完成最常見(jiàn)的增刪改查和 Rest 接口發(fā)布并知道報(bào)錯(cuò)時(shí)去哪個(gè)日志目錄找原因。2. 環(huán)境與依賴NC65 開(kāi)發(fā)前必須確認(rèn)的三件事2.1 NC65 技術(shù)棧與 API 調(diào)用的底層邏輯NC65 的二次開(kāi)發(fā)基于插件機(jī)制Plugin和組件框架Module。你在 eclipse 里寫(xiě)的每一個(gè)類最終會(huì)被打包成 jar 或 class 文件部署到 NC 的external或modules目錄下由 NC 中間件動(dòng)態(tài)加載。這個(gè)過(guò)程決定了你在代碼里能調(diào)用的 API 范圍nc.vo是值對(duì)象包nc.itf是接口包nc.impl是平臺(tái)實(shí)現(xiàn)包nc.pubitf是公共接口包。舉例來(lái)說(shuō)查詢一張銷售訂單的基本信息最常見(jiàn)的寫(xiě)法是使用nc.bs.pub.pf.PfQueryBuilder拼接查詢條件再調(diào)用nc.itf.uap.IUAPQueryBS的queryByCondition拿到結(jié)果集。這套 API 之所以重要是因?yàn)樗詣?dòng)幫你處理了多語(yǔ)言、多幣種、權(quán)限模板過(guò)濾等 NC 平臺(tái)的附加邏輯。直接寫(xiě)SELECT * FROM sale_b雖然能查到數(shù)據(jù)但一旦用戶被分配了數(shù)據(jù)權(quán)限結(jié)果集會(huì)與界面顯示不一致。import nc.bs.pub.pf.PfQueryBuilder; import nc.itf.uap.IUAPQueryBS; import nc.vo.pub.BusinessException; import nc.vo.pubapp.pattern.pub.ProxyFactory; import nc.vo.scm.salebill.SalebillBVO; // 獲取查詢服務(wù)通過(guò) ProxyFactory 拿到平臺(tái)實(shí)現(xiàn) IUAPQueryBS queryBS ProxyFactory.create(IUAPQueryBS.class); // 構(gòu)建查詢條件表名為 SalebillBVO 對(duì)應(yīng)的物理表 sale_b PfQueryBuilder builder new PfQueryBuilder(SalebillBVO.class); builder.addWhere(csaleid ?, 1001A1100000000ABCDE); builder.addOrderBy(dbilldate desc); // 執(zhí)行查詢返回的是平臺(tái) VO 對(duì)象數(shù)組可直接用于前端展示 Object[] result queryBS.queryByCondition(SalebillBVO.class, builder.toSQL());這里的ProxyFactory.create是 NC65 獲取遠(yuǎn)程服務(wù)的關(guān)鍵如果直接new一個(gè)實(shí)現(xiàn)類在集群環(huán)境下會(huì)繞過(guò)負(fù)載均衡。注意PfQueryBuilder的addWhere參數(shù)是可變長(zhǎng)的第一個(gè)參數(shù)是帶?占位符的 SQL 片段后續(xù)參數(shù)是實(shí)際值平臺(tái)會(huì)自動(dòng)做防注入處理不要自行拼接字符串。2.2 必備 Jar 包與 Maven 依賴配置本地環(huán)境搭建重點(diǎn)很多新手卡在第一步代碼寫(xiě)好了但import找不到類。NC65 開(kāi)發(fā)不需要你手動(dòng)去下載每個(gè) jar平臺(tái)安裝目錄的lib和external/lib下已經(jīng)包含了完整依賴。本地環(huán)境搭建時(shí)用友官方推薦的做法是使用nc_dev_env插件配合 eclipse它會(huì)自動(dòng)加載$NC_HOME/lib下的所有 jar。但如果你習(xí)慣 Maven 管理依賴需要手動(dòng)將平臺(tái) jar 安裝到本地倉(cāng)庫(kù)mvn install:install-file -DfileE:/NCHOME/lib/nc.uap.mw.jar \ -DgroupIdcom.yonyou \ -DartifactIdnc.uap.mw \ -Dversion65 \ -Dpackagingjar必須引入的核心依賴包括Jar 包名作用必選理由nc.uap.mw.jar平臺(tái)基礎(chǔ)運(yùn)行時(shí)不引則代碼直接編譯失敗nc.bs.framework.jar組件框架與服務(wù)分發(fā)提供 ProxyFactory、AppExceptionnc.vo.pub.jar值對(duì)象與數(shù)據(jù)庫(kù)類型映射所有 BVO / MasterVO 的父類nc.database.jar數(shù)據(jù)庫(kù)方言適配兼容 Oracle / SQL Server參數(shù)說(shuō)明-Dfile的路徑不要放在中文目錄下NC65 的類加載器對(duì)中文路徑支持不好會(huì)出現(xiàn)ClassNotFoundException但不是 jar 缺失導(dǎo)致的詭異問(wèn)題。此外nc.uap.mw.jar在不同小版本里包名會(huì)變比如部分版本是nc.uap.mw.module.jar建議先在lib里按名字搜一下再執(zhí)行 install 命令。2.3 NC65 的持久化 APIpersistenceApi 與 NCApi 怎么選NC65 里有兩套持久化 API新手經(jīng)常搞混但選錯(cuò)會(huì)導(dǎo)致無(wú)法保存隨單據(jù)流轉(zhuǎn)的擴(kuò)展字段。nc.bs.pub.pf.PfPersistence是老牌的持久化組件核心方法有saveVO、updateVO、deleteVO內(nèi)部走的是 JDBC SQL 拼裝性能好但它不會(huì)自動(dòng)維護(hù)審批狀態(tài)和單據(jù)號(hào)適合基礎(chǔ)檔案維護(hù)操作。NCApi則是 NC65 新增的實(shí)體服務(wù)組件Entity Service它基于元數(shù)據(jù)模型驅(qū)動(dòng)能聯(lián)動(dòng)處理單據(jù)號(hào)分配、審批流回寫(xiě)、版本控制等后臺(tái)邏輯。如果你寫(xiě)的是自定義單據(jù)的新增、修改建議直接用NCApiimport nc.itf.uap.IUAPQueryBS; import nc.vo.pub.BusinessException; import nc.vo.pubapp.pattern.pub.ProxyFactory; import nc.vo.scm.salebill.SalebillVO; // 構(gòu)造單據(jù)頭 單據(jù)體的 VO 結(jié)構(gòu) SalebillVO saleBillVO new SalebillVO(); saleBillVO.setPrimaryKey(PKGenerator.generatePK(salebill)); saleBillVO.setCcustid(1001A1100000000ABCDE); saleBillVO.setDbilldate(new java.sql.Date(System.currentTimeMillis())); // 獲取 NCApi 的單據(jù)服務(wù)注意此處不是 ProxyFactory nc.bs.framework.common.InitSession.init(null); nc.bs.framework.common.NCLocator.getInstance().lookup(nc.itf.scm.ISalebillMaintain.class);上面的代碼只展示了前半段獲取到ISalebillMaintain后調(diào)用它的save方法才真正落庫(kù)。需要特別提醒的是NCLocator.getInstance().lookup()必須在InitSession.init()之后調(diào)用否則會(huì)拋SessionTimeoutException。而且 NC65 的NCLocator是通過(guò) RMI 遠(yuǎn)程調(diào)用實(shí)現(xiàn)類它要求在nc.uap.mw模塊注冊(cè)了對(duì)應(yīng)的實(shí)現(xiàn)類如果你的代碼跑在非 IBA 模塊下lookup 會(huì)失敗這個(gè)坑后面在部署章節(jié)也會(huì)提到。3. 核心開(kāi)發(fā) API查、增、改、刪的標(biāo)準(zhǔn)寫(xiě)法與參數(shù)解析3.1 查詢 API 的三個(gè)核心方法queryByCondition、queryByCondition4Page、queryAllNC65 的查詢接口定義在IUAPQueryBS最常用的三個(gè)方法如下注意它們的返回類型和適用場(chǎng)景不同。// 方法一無(wú)條件或少量條件查詢返回全部匹配結(jié)果 public Object[] queryByCondition(Class voClass, String condition) throws BusinessException // 方法二分頁(yè)查詢適用于列表頁(yè)展示 public Object[] queryByCondition4Page(Class voClass, String condition, int pageIndex, int pageSize) throws BusinessException // 方法三查詢所有數(shù)據(jù)不推薦生產(chǎn)環(huán)境直接用 public Object[] queryAll(Class voClass, boolean isCheckPower) throws BusinessExceptioncondition參數(shù)傳的是 SQL WHERE 子句比如csaleid 1001A1100000000ABCDE注意單引號(hào)和大小寫(xiě)Oracle 里表字段名默認(rèn)大寫(xiě)。isCheckPower表示是否做數(shù)據(jù)權(quán)限過(guò)濾生產(chǎn)環(huán)境建議傳true否則用戶能看到別的組織的數(shù)據(jù)。分頁(yè)查詢的實(shí)現(xiàn)細(xì)節(jié)NC65 內(nèi)部會(huì)在condition外包一層ROWNUM或OFFSET/FETCH具體取決于連接的數(shù)據(jù)庫(kù)方言。因此pageIndex從 0 開(kāi)始不是 1。你傳pageIndex1, pageSize20會(huì)拿到第二頁(yè)。3.2 新增與保存用 saveVO 還是 NCApi 的 submit先看一個(gè)最常見(jiàn)的「保存」場(chǎng)景分歧。平臺(tái)標(biāo)準(zhǔn)單據(jù)界面上的「保存」按鈕走后端nc.bs.pubapp.pf.AbstractPfService的save核心邏輯是先校驗(yàn)必填項(xiàng)、再保存頭表、再保存行表最后返回主鍵。如果你在代碼里要復(fù)現(xiàn)這個(gè)動(dòng)作有兩種選擇。選擇一是直接用持久化 API 手工處理頭行import nc.bs.pub.pf.PfPersistence; // 保存單據(jù)頭 PfPersistence persistence new PfPersistence(); persistence.saveVO(salebillVO); // 保存單據(jù)體注意設(shè)置主表主鍵 SalebillBVO[] salebillBVOs salebillVO.getSalebillBVO(); for (SalebillBVO bvo : salebillBVOs) { bvo.setCsaleid(salebillVO.getPrimaryKey()); } persistence.saveVOArray(salebillBVOs);選擇二是走流程平臺(tái)讓submit自動(dòng)觸發(fā)審批import nc.bs.pubapp.pf.PfSubmitHelper; import nc.vo.pubapp.pattern.exception.ExceptionUtils; // 提交審批流approveType 為提交動(dòng)作標(biāo)識(shí) try { Object[] result PfSubmitHelper.submit(salebillVO, approve, 提交, null); } catch (Exception e) { ExceptionUtils.wrapBusinessException(單據(jù)提交失敗原因 e.getMessage()); }參數(shù)說(shuō)明PfSubmitHelper.submit的第三個(gè)參數(shù)是審批意見(jiàn)會(huì)寫(xiě)入審批歷史表第四個(gè)參數(shù)是附加數(shù)據(jù)對(duì)象一般傳null。這個(gè)方法會(huì)自動(dòng)控制在途單據(jù)同一單據(jù)不能同時(shí)被兩個(gè)用戶提交如果單據(jù)已在審批流中會(huì)拋BusinessException。3.3 更新與刪除避免臟寫(xiě)與假刪除的四種注意點(diǎn)NC65 的更新操作有兩個(gè)陷阱。第一是并發(fā)控制updateVO默認(rèn)不帶樂(lè)觀鎖后提交的會(huì)覆蓋先提交的。標(biāo)準(zhǔn)接口里通過(guò)ts字段時(shí)間戳做版本控制你自己寫(xiě)更新邏輯時(shí)要在 VO 里保留ts原始值否則更新SalebillBVO時(shí)需要先查一次原始數(shù)據(jù)。// 先查出數(shù)據(jù)庫(kù)中的原始 VO再修改字段后更新 Object[] oldVOs queryBS.queryByCondition(SalebillVO.class, csaleid pk , false); SalebillVO oldVO (SalebillVO) oldVOs[0]; oldVO.setNrealnum(oldVO.getNrealnum().add(new BigDecimal(10))); persistence.updateVO(oldVO);刪除推薦用「邏輯刪除」NC65 很多單據(jù) VO 都有dr字段值為 0 表示有效1 表示刪除。你寫(xiě)DELETE FROM sale_b會(huì)破壞單據(jù)號(hào)連續(xù)性也影響審批歷史追溯。正確做法是把dr置 1SalebillVO vo new SalebillVO(); vo.setPrimaryKey(pk); vo.setDr(1); vo.setTs(oldVO.getTs()); // 必須帶上原始 ts persistence.updateVO(vo);注意如果oldVO.getTs()為null平臺(tái)會(huì)拋UnsupportedOperationException因?yàn)闊o(wú)法確定版本號(hào)。這也是新手做刪除時(shí)最容易忽略的 NPE——不是「查不到」而是「沒(méi)查」。3.4 獲取未執(zhí)行 SQL 的調(diào)試技巧關(guān)鍵NC65 API 的queryByCondition最終會(huì)拼出完整 SQL但有時(shí)候你查不到數(shù)據(jù)需要看它實(shí)際生成的 SQL 來(lái)定位問(wèn)題。平臺(tái)提供了一個(gè)低調(diào)的接口nc.bs.pub.pf.PfQueryBuilder#toSQL()但在某些版本中它返回的是帶參數(shù)占位符的預(yù)編譯 SQL。這時(shí)可以用另一個(gè)方法拿到可執(zhí)行的完整 SQL// 直接打印 SqlBuilder 生成的 SQL PfQueryBuilder builder new PfQueryBuilder(SalebillBVO.class); builder.addWhere(csaleid ?, 1001A1100000000ABCDE); System.out.println(builder.toSQL()); // 借助平臺(tái)自帶的 SQL 日志攔截器控制臺(tái)會(huì)輸出真實(shí) SQL // 需要修改配置文件$NC_HOME/bin/prop.xml 中增加 // property namelog.sql valuetrue /toSQL()返回的 SQL 里?占位符還在原位置如果你需要在數(shù)據(jù)庫(kù)客戶端里手動(dòng)執(zhí)行把占位符替換成實(shí)際值即可。當(dāng)log.sqltrue生效時(shí)NC 中間件會(huì)在后臺(tái)輸出每一次查詢的完整 SQL 和耗時(shí)這是排查性能瓶頸最直接的手段建議開(kāi)發(fā)環(huán)境直接打開(kāi)生產(chǎn)環(huán)境謹(jǐn)慎開(kāi)啟日志量會(huì)增大。3.5 基礎(chǔ)檔案與單據(jù)的 API 入口對(duì)照表開(kāi)發(fā)對(duì)象推薦服務(wù)接口典型實(shí)現(xiàn)方法典型 VO客戶檔案nc.itf.uap.IUAPQueryBSqueryByConditionCustomerVO存貨檔案nc.itf.uap.IUAPQueryBSqueryByConditionMaterialVO銷售訂單nc.itf.scm.ISalebillMaintainsave/updateSalebillVO采購(gòu)訂單nc.itf.scm.IPoMaintainsave/updatePurchaseOrderVO審批流nc.bs.pubapp.pf.PfSubmitHelpersubmit/approve—自定義查詢nc.bs.pub.pf.PfQueryBuildertoSQL/queryByCondition任意 BVO這個(gè)對(duì)照表是「做客開(kāi)時(shí)最先要記」的清單。遇到一個(gè)新單據(jù)先看它的接口服務(wù)名和 VO 類名就能大致判斷查詢邏輯怎么寫(xiě)。如果不確定服務(wù)是否存在用NCLocator.lookup(接口.class)前先查 module 注冊(cè)文件META-INF\services確認(rèn)接口在哪個(gè)模塊下避免運(yùn)行時(shí)找不到服務(wù)。4. 發(fā)布 Rest 接口從 NC65 到外部系統(tǒng)的最短路徑含參數(shù)配置4.1 前置準(zhǔn)備啟動(dòng) NC65 的 Rest 服務(wù)與注冊(cè) URLNC65 發(fā)布 Rest 接口不需要額外安裝框架平臺(tái)已內(nèi)置基于 Jersey 的 Rest 支持。你只需要把類注冊(cè)到nc.uap.mw的 JAX-RS 服務(wù)注冊(cè)表里。但很多新手卡在第一步URL 訪問(wèn)報(bào) 404 或 401。打開(kāi)nc.uap.mw模塊的META-INF\rest-services.xml確認(rèn)以下內(nèi)容存在?xml version1.0 encodingUTF-8? rest-services service namenc.itf.uap.IUAPQueryBS/name url/query/url auth0/auth /service /rest-servicesauth0表示匿名訪問(wèn)auth1表示需要登錄態(tài)。生產(chǎn)環(huán)境建議改成1用NC 登錄接口換取 token后訪問(wèn)否則接口裸奔在公網(wǎng)風(fēng)險(xiǎn)極大。4.2 手寫(xiě)一個(gè)帶參數(shù)的查詢接口完整代碼package nc.demo.rest; import javax.ws.rs.GET; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.QueryParam; import nc.bs.pub.pf.PfQueryBuilder; import nc.itf.uap.IUAPQueryBS; import nc.vo.pub.BusinessException; import nc.vo.pubapp.pattern.pub.ProxyFactory; import nc.vo.scm.salebill.SalebillBVO; import com.alibaba.fastjson.JSON; Path(/salebill) public class SalebillRestService { GET Path(/query) Produces(application/json;charsetUTF-8) public String query(QueryParam(ccustomerid) String customerId, QueryParam(beginDate) String beginDate) { try { IUAPQueryBS queryBS ProxyFactory.create(IUAPQueryBS.class); PfQueryBuilder builder new PfQueryBuilder(SalebillBVO.class); // 客戶主鍵不為空時(shí)追加查詢條件 if (customerId ! null !customerId.isEmpty()) { builder.addWhere(ccustomerid ?, customerId); } // 日期條件使用 注意格式與數(shù)據(jù)庫(kù)一致 if (beginDate ! null !beginDate.isEmpty()) { builder.addWhere(dbilldate to_date(?, yyyy-mm-dd), beginDate); } Object[] result queryBS.queryByCondition(SalebillBVO.class, builder.toSQL()); return JSON.toJSONString(result); } catch (BusinessException e) { return {\error\:\ e.getMessage() \}; } } }邏輯說(shuō)明Path指定了類級(jí)別的訪問(wèn)路徑QueryParam接收 URL 上的查詢參數(shù)。返回 JSON 使用fastjson因?yàn)?NC65 自帶該依賴不必額外引入 Jackson。注意builder.toSQL()是執(zhí)行前的最后一步如果條件為空字符串會(huì)生成WHERE 11這在 Oracle 下沒(méi)問(wèn)題但 SQL Server 下建議顯式判斷后再拼條件。4.3 Rest 接口的權(quán)限與參數(shù)校驗(yàn)必須配置的三處發(fā)布后必須在 NC 的權(quán)限管理里給角色分配該菜單或動(dòng)作的權(quán)限否則即使auth0也可能出現(xiàn)信任域校驗(yàn)失敗的提示。常見(jiàn)做法是在rest-services.xml注冊(cè)的服務(wù)名要與代碼中的Path類完全對(duì)應(yīng)部署位置$NC_HOME/modules/你所在模塊/META-INF/rest-services.xml重啟 NC 中間件然后通過(guò)http://ip:port/service/模塊標(biāo)識(shí)/訪問(wèn)接口參數(shù)校驗(yàn)不能在 Servlet 里做Rest 服務(wù)不走 Servlet建議在query方法開(kāi)頭獨(dú)立寫(xiě)校驗(yàn)邏輯并統(tǒng)一異常返回格式。以下是一個(gè)簡(jiǎn)單工具方法private boolean checkParam(String value) { // 只允許數(shù)字、字母和常見(jiàn)的橫線、下劃線防止 SQL 注入 return value ! null value.matches([a-zA-Z0-9_\\-]); }5. 報(bào)錯(cuò)排查NC65 API 調(diào)用失敗的常見(jiàn)原因與定位手段5.1ProxyFactory.create拋出BusinessException的定位順序ProxyFactory.create(IUAPQueryBS.class)在 NC65 里是通過(guò)Module配置動(dòng)態(tài)裝配的如果某個(gè)模塊沒(méi)有注冊(cè)iuap.querybs實(shí)現(xiàn)調(diào)用時(shí)直接拋BusinessException: 找不到服務(wù)實(shí)現(xiàn)。新手常誤認(rèn)為項(xiàng)目缺 jar其實(shí)只要打開(kāi)$NC_HOME/modules/uap/META-INF/module.xml檢查public-service聲明即可。如果確認(rèn)服務(wù)已注冊(cè)接下來(lái)排查用戶是否有權(quán)限。NC65 的queryByCondition權(quán)限邏輯是先取當(dāng)前登錄用戶的pk_corp和角色再拼進(jìn) SQL 的org過(guò)濾條件。用InitSession初始化一個(gè)空 session 去調(diào)用通常會(huì)因?yàn)闆](méi)有默認(rèn)組織而查不到數(shù)據(jù)報(bào)錯(cuò)卻是空指針。5.2 單據(jù)保存報(bào)「當(dāng)前操作者與提交者不一致」的解決思路在 NC65 的審批流場(chǎng)景下PfSubmitHelper.submit會(huì)檢查當(dāng)前 session 用戶與單據(jù)創(chuàng)建人是否一致。如果你是在定時(shí)任務(wù)里自動(dòng)提交必須手動(dòng)模擬 sessionnc.bs.framework.common.InitSession.init(0001A11000000000000P); // 管理員用戶 pk nc.bs.framework.common.InitSession.setCorp(1001A1100000000000A);InitSession.init的第一個(gè)參數(shù)是用戶主鍵第二個(gè)是公司主鍵通過(guò)setCorp設(shè)置。注意init只能調(diào)用一次進(jìn)程生命周期內(nèi)有效多次調(diào)用會(huì)覆蓋之前的信息。定時(shí)任務(wù)里用完要記得InvocationInfoProxy.getInstance().setUserId()清理否則后續(xù)代碼全部繼承這個(gè)用戶態(tài)容易出現(xiàn)越權(quán)。5.3 日志查看NC65 的nclog與異常堆棧讀取NC65 的日志默認(rèn)輸出到$NC_HOME/nclog按模塊分文件。開(kāi)發(fā)期出問(wèn)題第一眼看nclog/run.log和nclog/err.log# 查看最近 100 行運(yùn)行日志過(guò)濾業(yè)務(wù)異常關(guān)鍵字 tail -100 $NC_HOME/nclog/run.log | grep -E Exception|ERROR|Caused by # 跟蹤實(shí)時(shí)日志 tail -f $NC_HOME/nclog/run.logrun.log里記錄了每次 API 調(diào)用的入口和耗時(shí)err.log是堆棧異常匯總。出現(xiàn)ORA-00942: table or view does not exist的情況往往是調(diào)用的 VO 類對(duì)應(yīng)的表在數(shù)據(jù)庫(kù)里沒(méi)建此時(shí)要在 NC 的「系統(tǒng)監(jiān)控→數(shù)據(jù)字典」中確認(rèn)實(shí)體是否已發(fā)布而不是改代碼。6. 進(jìn)階優(yōu)化NC65 API 調(diào)用的性能瓶頸與批量處理技巧6.1 批量操作saveVOArray與逐條saveVO的性能差距NC65 的saveVO內(nèi)部每調(diào)一次就開(kāi)一個(gè)事務(wù)、提交一次。批量保存 500 條單據(jù)如果循環(huán)調(diào)用saveVO耗時(shí)會(huì)呈指數(shù)級(jí)上升數(shù)據(jù)庫(kù)日志文件也會(huì)瘋狂膨脹。正確做法是使用saveVOArray一次性提交// 批量保存返回的主鍵數(shù)組順序與傳入順序一致 String[] pks persistence.saveVOArray(salebillVOs);實(shí)測(cè)在 Oracle 11g 下300 條數(shù)據(jù)逐條保存耗時(shí)約 1.8 秒批量保存約 90 毫秒差距近 20 倍。原因是批量模式會(huì)一次性拼接多條INSERT配合 JDBC 的addBatch執(zhí)行節(jié)省了往返數(shù)據(jù)庫(kù)的網(wǎng)絡(luò)時(shí)間。如果單據(jù)還有行表saveVOArray不會(huì)自動(dòng)幫你保存行表必須先把行表 VO 也構(gòu)造成數(shù)組并分兩次保存這一點(diǎn)很多從 Hibernate 轉(zhuǎn)過(guò)來(lái)的開(kāi)發(fā)者容易忽略。6.2 大數(shù)據(jù)量查詢時(shí)的 fetchSize 與分頁(yè)參數(shù)調(diào)優(yōu)queryByCondition4Page支持分頁(yè)但服務(wù)器默認(rèn)的 fetchSize 是 50如果你一次性查 1 萬(wàn)條數(shù)據(jù)做報(bào)表平臺(tái)會(huì)自動(dòng)做 200 次 fetch網(wǎng)絡(luò)開(kāi)銷極大。此時(shí)可以在構(gòu)建查詢前設(shè)置 JDBC 的 fetchSize// 獲取連接并設(shè)置 fetchSize注意用完即還 java.sql.Connection conn nc.bs.framework.common.NCLocator.getInstance().lookup(java.sql.DataSource.class) .getConnection(); conn.setAutoCommit(false); java.sql.PreparedStatement ps conn.prepareStatement(sql); ps.setFetchSize(1000);參數(shù)說(shuō)明setFetchSize的單位是行數(shù)Oracle 驅(qū)動(dòng)會(huì)忽略該參數(shù)SQL Server 驅(qū)動(dòng)最多支持 8 的整數(shù)倍。如果遇到 fetchSize 不生效檢查是否用了 NC 自帶連接池的PreparedStatement包裝類它可能覆寫(xiě)了該方法。6.3 緩存策略NC65 API 的查詢結(jié)果能否復(fù)用NC65 平臺(tái)自帶的緩存機(jī)制是「基于主鍵」的 VO 緩存queryByCondition不會(huì)緩存結(jié)果每次調(diào)用都查庫(kù)。但在高并發(fā)讀多寫(xiě)少的場(chǎng)景你可以用nc.bs.pub.pf.PfCacheManager手動(dòng)管理import nc.bs.pub.pf.PfCacheManager; // 緩存 10 分鐘 Object[] cached PfCacheManager.get(salebill_list, 600); if (cached null) { cached queryBS.queryByCondition(SalebillBVO.class, condition); PfCacheManager.put(salebill_list, cached); }這里有個(gè)注意點(diǎn)PfCacheManager.put緩存的 VO 數(shù)組是對(duì)象引用。如果后續(xù)代碼修改了數(shù)組里的某個(gè) VO緩存也會(huì)變臟下次拿到的是修改后的數(shù)據(jù)。所以只緩存明確不會(huì)被修改的只讀查詢寫(xiě)操作直接繞過(guò)緩存。6.4 寫(xiě)出適合 NC65 平臺(tái)的 SQL 的三個(gè)原則原則一不要用SELECT *NC65 的 VO 與表的字段映射是「按需取列」缺列會(huì)導(dǎo)致VO 取值為 null而不是報(bào)錯(cuò)排查起來(lái)非常隱蔽。原則二日期條件用to_date(?, yyyy-mm-dd)或 sysdate - 30不要用字符串直接比較否則不走索引。原則三有 OR 條件的 SQL 建議拆成兩個(gè)子查詢 unionNC65 的 SQL 生成器對(duì) OR 的優(yōu)化能力有限大表上容易全表掃描。如果你在 NC65 上做報(bào)表匯總、外部接口對(duì)接這幾個(gè)原則能直接決定接口響應(yīng)是 200ms 還是 5s。最后留一個(gè)自查建議上線前把log.sqltrue打開(kāi)跑一遍核心接口記錄每條 SQL 的執(zhí)行計(jì)劃把TABLE ACCESS FULL的表補(bǔ)上索引——這一步做完NC65 接口的穩(wěn)定性基本就穩(wěn)了。本文還有配套的精品資源點(diǎn)擊獲取