數(shù)據(jù)加載全攻略：表單、列表、服務插件與性能優(yōu)化)
做了這么多年蒼穹二開插件里“加載數(shù)據(jù)”這件事幾乎每天都在寫。但奇怪的是我在社區(qū)和客戶現(xiàn)場經(jīng)?？吹揭环N現(xiàn)象很多人代碼能跑卻不知道自己到底在加載什么為什么這樣加載換一個場景就抓瞎。今天這篇我就專門把“插件開發(fā)里的數(shù)據(jù)加載”這件事拆開揉碎講清楚從最基礎的取數(shù)方式到列表、表單、服務三類插件各自的加載套路再到我踩過的坑一次說透。這篇內(nèi)容適合誰剛接觸蒼穹插件開發(fā)、被動態(tài)表單模型繞暈的初級二開也包括已經(jīng)寫了半年一年插件、想系統(tǒng)性梳理數(shù)據(jù)加載方案的開發(fā)。全文沒有廣告沒有理論堆砌都是可以直接拿過去用的代碼片段和排查思路。1. 加載數(shù)據(jù)之前先把蒼穹的數(shù)據(jù)模型搞清楚1.1 你取到的數(shù)據(jù)到底是“顯示值”還是“存儲值”剛開始寫插件的人最容易栽的跟頭是把頁面看到的值和數(shù)據(jù)庫存的值混為一談。蒼穹頁面渲染出來的數(shù)據(jù)是經(jīng)過格式化的比如日期顯示成“2025-06-18”金額顯示成“1,234.56”基礎資料顯示成編碼名稱的組合但這些都不是數(shù)據(jù)底層的本相。插件里通過this.View.Model.GetValue(billDate)取到的通常是經(jīng)過平臺處理的DynamicObject或者基礎類型而通過GetDataEntity()拿到的才是這張單據(jù)完整的實體數(shù)據(jù)。我見過一個同事想在表單插件里拿基礎資料字段的編碼直接用了this.View.Model.GetValue(supplier)取出來一個對象打印一看里面有Id、Number、Name他當時就懵了。實際上在蒼穹的模型里基礎資料字段的值是一個Long型的id要拿到編碼和名稱得走DynamicObject的屬性取法或者通過DataEntity再去解析。這里我的建議是先分清楚你是在哪個環(huán)節(jié)取數(shù)。如果只是取當前表單頁面上某個字段的值用this.View.Model.GetValue(字段標識)就夠了如果你要拿著這條數(shù)據(jù)去做服務端邏輯或者要把單據(jù)體數(shù)據(jù)批量拿出來處理直接用this.View.Model.GetDataEntity()把整個動態(tài)實體拿到手再逐字段取。另外一個高頻坑是字段標識蒼穹里字段標識大小寫敏感而且設計器里顯示的名稱和真正的標識是兩回事。比如頁面上叫“供應商”標識可能是“supplier”也可能是“kdec_supplier”帶上前綴的往往是二開擴展字段。你寫錯一個字母運行時不報錯取回來的就是null排查要花半天。所以每次取數(shù)之前先到BOS設計器里核對一下字段標識別憑記憶寫。1.2 三種插件類加載數(shù)據(jù)的姿勢完全不同蒼穹插件主要分表單插件、列表插件、服務插件三大類我接觸過的項目中幾乎80%的數(shù)據(jù)加載需求都落在這三塊里。同類插件內(nèi)部加載數(shù)據(jù)的方式也有差異不要拿表單插件里取數(shù)的方式硬套到列表插件上。表單插件包括動態(tài)表單和單據(jù)的插件核心操作對象是this.View.Model你可以直接讀寫當前實體數(shù)據(jù)配合BeforeDoOperation、AfterDoOperation、AfterLoadData這類生命周期事件去處理數(shù)據(jù)。列表插件不一樣它的核心是ListShowParameter和QueryServiceHelper你要主動構造查詢條件去查數(shù)據(jù)再綁定到列表視圖上。服務插件則更多的在操作服務、計劃任務、審批流里跑沒有頁面Model可用一切數(shù)據(jù)都得通過服務上下文去拿。簡單說表單插件是“人在頁面上操作數(shù)據(jù)已經(jīng)躺在那里你只需讀和改”列表插件是“按條件從數(shù)據(jù)庫里拉一批數(shù)據(jù)渲染成列表”服務插件是“后臺默默處理數(shù)據(jù)要通過操作參數(shù)或服務上下文顯式去取”。這三個場景的代碼寫法和注意事項差別巨大下面我分別帶著代碼講。2. 開發(fā)環(huán)境與插件工程的基本盤2.1 一套能跑起來的本地開發(fā)環(huán)境再好的思路環(huán)境配不好也是白搭。金蝶云蒼穹的插件開發(fā)本質(zhì)上是Java開發(fā)我在項目里最常用的組合是IntelliJ IDEA 蒼穹的Maven依賴 本地/測試環(huán)境的蒼穹服務。這里有個很重要的點蒼穹插件分“蒼穹設計器內(nèi)嵌編寫”和“獨立Java工程編寫”兩種模式。設計器里那種輕量級的規(guī)則插件、簡單字段聯(lián)動可以直接在界面上配但只要是稍微復雜一點的加載數(shù)據(jù)邏輯比如多表聯(lián)查、自定義過濾、批量取數(shù)我的經(jīng)驗是必須走獨立Java工程用Maven管理依賴調(diào)試也方便。你需要在pom.xml里引入蒼穹的開發(fā)SDK依賴具體坐標版本跟你使用的蒼穹版本強相關。這個問題我在幾個客戶的現(xiàn)場都遇到過引入了錯誤的依賴版本插件一部署就報NoClassDefFoundError。正確做法是讓實施或架構組提供與你環(huán)境匹配的依賴清單或者從平臺的lib目錄下把對應jar包導出來install到本地倉庫。別自己在網(wǎng)上隨便找依賴版本版本不匹配的問題非常隱蔽。工程建好之后寫插件類、編譯、打成jar包然后在蒼穹設計器的“插件”配置里填上你的插件類全限定名保存發(fā)布。這是一個標準的二開流程。需要提醒的是每次改完Java代碼都要重啟或熱部署對應的服務否則你改的代碼不生效這種“改了沒反應”的假象我遇到過太多次最后發(fā)現(xiàn)是沒重啟。2.2 插件類要繼承誰父類決定你能干什么選錯父類是插件運行時不執(zhí)行或者找不到方法的頭號原因。我理了一下最常用的繼承關系單據(jù)/動態(tài)表單插件繼承AbstractFormPlugIn或AbstractBillPlugIn。AbstractBillPlugIn是單據(jù)插件比AbstractFormPlugIn多了單據(jù)專屬的能力。列表插件繼承AbstractListPlugIn。服務插件根據(jù)場景不同繼承AbstractOperate操作服務插件、AbstractAuditPlugIn審核相關、AbstractBillPlugInService單據(jù)服務等。我見過一個特別典型的問題同事在列表插件里重寫了afterLoadData發(fā)現(xiàn)怎么都不觸發(fā)后來一看他繼承的是AbstractFormPlugIn列表視圖根本沒有表單模型。所以動手寫之前先確認你的插件掛載在哪個位置BOS里“表單插件”“列表插件”“服務插件”三個入口對應不同的父類體系別混淆。綁定插件時注意插件標識必須是類的全限定名包括包名寫成類名簡寫是找不到的。還有一個順序問題BOS里可以掛多個插件插件之間的執(zhí)行順序按配置順序來如果A插件要先加載數(shù)據(jù)、B插件要消費A的數(shù)據(jù)順序千萬不能反否則B拿到的永遠是null。3. 實操核心三類加載數(shù)據(jù)的標準寫法3.1 表單插件用Model取當前數(shù)據(jù)用Query取擴展數(shù)據(jù)表單插件加載數(shù)據(jù)分兩種一是加載當前單據(jù)自身的數(shù)據(jù)二是根據(jù)當前單據(jù)的信息去查別的數(shù)據(jù)。前者簡單后者是常規(guī)需求。先看第一類。在單據(jù)的AfterLoadData事件里我可以這么取public class MyBillPlugin extends AbstractBillPlugIn { Override public void afterLoadData(EventObject e) { // 取單個字段值 String billNo (String) this.getModel().getValue(billNo); // 取整單數(shù)據(jù)實體 DynamicObject billData this.getModel().getDataEntity(); // 取單據(jù)體數(shù)據(jù)集合 DynamicObjectCollection entryRows billData.getDynamicObjectCollection(entryEntity); } }這里有幾個細節(jié)。getValue返回的字段類型要看字段定義比如基礎資料字段返回的是Long型id而不是對象單據(jù)體取出來的是一個DynamicObjectCollection你可以遍歷它去讀每一行。再說第二類需要查外部數(shù)據(jù)。這里我推薦優(yōu)先用QueryServiceHelper它是蒼穹里通用的查詢?nèi)肟诳梢钥绫聿?、可以加過濾條件返回DynamicObjectCollectionimport kd.bos.servicehelper.QueryServiceHelper; DynamicObjectCollection result QueryServiceHelper.query( my_bill, // 查詢的實體標識 billNo,supplier.name,totalAmount, // 要查的字段支持基礎資料屬性的點路徑 billNo ? and totalAmount ?, // 過濾條件參數(shù)用?占位 new Object[] { billNo, 1000 } // 條件參數(shù) );我自己的習慣是能用query一次性查出來的絕不循環(huán)里單條load。比如我要按單據(jù)頭一批單據(jù)號查所有單據(jù)體行直接一次query把頭和體都拉出來再在內(nèi)存里分組比在循環(huán)里一個個load效率高一個數(shù)量級。這里需要多說一句字段路徑。蒼穹的查詢字段支持用點號取關聯(lián)基礎資料的屬性比如supplier.number、supplier.name這是平臺自動join的省了你手動多表關聯(lián)的麻煩。但你得知道這種點路徑的寫法在動態(tài)表單模型里同樣適用比如getValue(supplier.name)在部分場景下也能取到。不過我用下來最穩(wěn)的還是先拿對象再取屬性。3.2 列表插件構造查詢參數(shù)喂給列表視圖列表插件加載數(shù)據(jù)的思路和表單插件完全不同。列表頁的核心是ListShowParameter你構造好它再調(diào)用this.getView().showData()就能刷新列表。一個最基礎的列表加載長這樣public class MyListPlugin extends AbstractListPlugIn { // 刷新列表數(shù)據(jù)可指定過濾條件 public void refreshList() { ListShowParameter showParam new ListShowParameter(); showParam.setFormId(my_bill); // 設置列表的過濾條件只在當前列表視圖生效 showParam.getCustomParams().put(keyword, 張三); // 打開或刷新 this.getView().showData(showParam); } }但實際項目里列表插件更多的場景是重寫查詢條件。常見的是在afterQueryData里對查出來的數(shù)據(jù)做二次加工或者在beforeQueryData里改寫查詢參數(shù)。我項目中用得最多的是重寫列表的過濾Override public void setFilter(FilterParameter filter) { super.setFilter(filter); // 追加客戶權限過濾 filter.getFilterItems().add(new FilterItem(customer.id, , currentCustomerId)); }還有個使用要點列表插件的取數(shù)如果只是展示不需要把數(shù)據(jù)實體全部加載出來盡量只取列表需要的字段否則數(shù)據(jù)量大的時候列表首屏會很慢。我在一個客戶現(xiàn)場排查過他們列表每次打開要5秒后來發(fā)現(xiàn)是查詢條件里帶了單據(jù)體字段導致平臺把整個主從表都load了一次。去掉單據(jù)體字段后首屏降到1秒以內(nèi)。列表加載完數(shù)據(jù)后你還可以在afterQueryData里拿到查詢結果集Override public void afterQueryData(EventObject e) { super.afterQueryData(e); DynamicObjectCollection rows this.getModel().getDataEntities(); // 對返回結果做加工或統(tǒng)計 }這里注意afterQueryData里的數(shù)據(jù)是當前列表頁展示的那一頁數(shù)據(jù)不是全量數(shù)據(jù)。如果你要統(tǒng)計整個數(shù)據(jù)集的匯總別在這里寫聚合邏輯否則你統(tǒng)計的只是當前頁。3.3 服務插件從操作上下文里取數(shù)據(jù)服務插件沒有頁面Model最常見的是操作服務插件通過繼承AbstractOperate來實現(xiàn)。它的核心方法是execute通過OperateContext上下文取參數(shù)。public class MyOperatePlugin extends AbstractOperate { Override public void execute(OperateContext ctx) throws Exception { // 操作服務傳入的選中數(shù)據(jù)一般是Long[]形式的id數(shù)組 Long[] selectedIds ctx.getSelectedIds(); // 按具體操作類型可能需要從ctx.getDataEntities()取完整數(shù)據(jù) DynamicObject firstRow ctx.getDataEntity(); // 或者取操作參數(shù)里的自定義參數(shù) Object customValue ctx.getCustomParam(customKey); } }在服務插件里取數(shù)要區(qū)分兩個來源如果操作是從列表頁發(fā)起的ctx.getSelectedIds()會帶選中行的id如果是從單據(jù)詳情頁發(fā)起的ctx.getDataEntities()里會有當前單據(jù)的實體數(shù)據(jù)。我做過一個批量審核的服務插件就是先拿selectedIds再批量load單據(jù)數(shù)據(jù)逐條做校驗最后調(diào)用審核服務。服務插件里加載數(shù)據(jù)我強烈建議用批量接口不要一條條循環(huán)load。蒼穹的BusinessDataServiceHelper提供了load和loadMore兩個方法import kd.bos.servicehelper.BusinessDataServiceHelper; // 單條加載 DynamicObject single BusinessDataServiceHelper.load(id, my_bill); // 批量加載 DynamicObjectCollection batch BusinessDataServiceHelper.loadMore(ids, my_bill);如果數(shù)據(jù)量比較大比如一次幾百上千條還有分頁load的姿勢用loadMore配合OrmConfig做字段裁剪只取你要用到的字段避免把大字段比如文本、附件信息也一并load出來內(nèi)存和性能都會好很多。我寫過一次批量處理沒裁剪字段結果服務直接OOM了后來加了OrmConfig只取必要字段內(nèi)存瞬間降下來。3.4 通過OrmConfig控制加載字段性能差距就在這BusinessDataServiceHelper.load系列方法支持傳OrmConfig用來指定查詢哪些字段類似于SQL里的select指定列。這個參數(shù)很多初學者會忽略但它是性能優(yōu)化的第一道門。import kd.bos.orm.OrmConfig; OrmConfig config new OrmConfig(); config.addField(billNo); config.addField(supplier); config.addField(entryEntity.entryRow); config.addField(entryEntity.amount); DynamicObjectCollection dataRows BusinessDataServiceHelper.loadMore( ids, my_bill, config );OrmConfig還有一個好處你可以控制是否加載單據(jù)體行、是否加載基礎資料屬性。默認情況下load會連基礎資料的關聯(lián)屬性都帶出來數(shù)據(jù)量大時開銷很明顯。如果你只需要Id和Number就明確只查這兩個字段別讓平臺白做那么多join。我自己的一個經(jīng)驗閾值是超過50條的批量load一律用OrmConfig裁剪字段超過200條的必須做分頁超過1000條的建議直接走QueryServiceHelper用分頁查詢。這套標準我在多個項目里復用基本沒出過性能事故。4. 查詢引擎與服務選擇的細節(jié)決定代碼上限4.1 什么時候用QueryServiceHelper什么時候用BusinessDataServiceHelper這是我在面試候選人時經(jīng)常問的一個問題也是項目里爭論最多的點。我先把結論說出來查詢展示用QueryServiceHelper拿到實體做操作用BusinessDataServiceHelper。QueryServiceHelper適合做列表查詢、報表取數(shù)、條件統(tǒng)計這類只讀場景它支持復雜過濾、排序、分頁查出來的DynamicObject是輕量的行數(shù)據(jù)。BusinessDataServiceHelper.load系列適合按id讀取完整業(yè)務對象它會返回帶單據(jù)體的完整實體你可以直接對這個實體做修改再保存或者把它傳給操作服務去審核、提交。兩者之間有一個很容易踩的坑QueryServiceHelper查出來的數(shù)據(jù)是“查詢快照”它不是完整的業(yè)務對象有些字段沒查的話就是null而且不能直接拿去調(diào)保存操作。如果代碼里查完直接改數(shù)據(jù)再提交保存往往保存的只是部分字段甚至因為缺了關鍵字段導致保存報錯。正確做法是拿到查詢出的id后再用BusinessDataServiceHelper.load把完整實體load出來在完整實體上改數(shù)據(jù)、做操作。4.2 寫過濾條件時的表達式語法蒼穹查詢的過濾條件不是原生SQL它有一套自己的表達式規(guī)則?；緦懛ㄊ恰白侄螛俗R 比較符 參數(shù)占位符”。比較多的是等于、不等于、大于、小于、in集合、like模糊匹配。in集合的寫法我截個代碼DynamicObjectCollection result QueryServiceHelper.query( my_bill, billNo,customer.name,totalAmount,status, billNo in (?, ?, ?) or status ?, new Object[] { BILL001, BILL002, BILL003, A } );如果你只有一個集合參數(shù)也可以把集合當一個占位符傳進去蒼穹支持把List或數(shù)組整體作為一個in參數(shù)。但要注意空的集合千萬不要傳否則生成的SQL可能變成in ()有些數(shù)據(jù)庫直接報錯有些數(shù)據(jù)庫查不出數(shù)據(jù)這算一個低級但常見的坑。還有l(wèi)ike的寫法參數(shù)里拼%號比如new Object[]{% keyword %}而不是在條件里寫like %?%。這點和JDBC的PreparedStatement習慣一樣參數(shù)和SQL模板要分開平臺才能正確做防注入和類型轉(zhuǎn)換。4.3 數(shù)據(jù)權限與字段權限的隱藏坑服務插件里取數(shù)如果不做任何處理默認是帶操作者上下文的也就是說查詢結果會受到數(shù)據(jù)權限和字段權限控制。這個機制有好有壞。好的一面是安全壞的一面是你可能會莫名其妙地查不到數(shù)據(jù)。我第一次做項目時就遇到過管理員賬號跑計劃任務查數(shù)據(jù)全正常換普通賬號在前臺觸發(fā)同一個服務查出來少了幾條。排查了半天最后發(fā)現(xiàn)是數(shù)據(jù)權限規(guī)則在起作用。解決方案要看具體需求如果查詢就應該遵守權限那就保持默認如果后臺任務必須繞過權限則要用特定的查詢?nèi)肟诨蛘咛嵘舷挛?。我個人的習慣是后臺任務、計劃任務這類場景盡量顯式處理權限上下文前臺用戶操作的場景則明確依賴權限校驗。字段權限的坑更隱蔽。有時候數(shù)據(jù)能查出來但某些字段返回null不是因為數(shù)據(jù)沒有值而是當前操作者對該字段沒有查看權限平臺在查詢層就把字段值屏蔽了。遇到這種情況先別懷疑代碼用管理員賬號跑一次同樣的邏輯如果管理員能看到那就是字段權限問題去權限配置里檢查即可。5. 常見問題與排查技巧實錄5.1 為什么插件里取出來的數(shù)據(jù)總是null這個問題的出現(xiàn)頻率在我的答疑記錄里排第一。我總結了一下十個里有七個是以下三個原因一是字段標識寫錯。區(qū)分大小寫、帶不帶擴展前綴去BOS設計器里核對別靠記憶。二是取數(shù)時機不對。表單還沒加載完就去取數(shù)據(jù)比如在beforeBindData里用getValue取頁面值這時候數(shù)據(jù)都還沒進來取到null太正常了。要在afterBindData、afterLoadData這類生命周期事件里取。三是數(shù)據(jù)源本身就沒值。頁面可能顯示了值但那個值是計算列或動態(tài)字段不是真實存儲字段。你需要在數(shù)據(jù)庫里直接跑一條SQL確認數(shù)據(jù)是否存在排除業(yè)務數(shù)據(jù)本身為空的情況。排查這類問題我有一招特別好用在代碼里打印當前數(shù)據(jù)實體的JSON串。用JSONUtils.toJson(dataEntity)或者直接輸出實體類型一跑就能看到數(shù)據(jù)里到底有哪些字段、哪些值是null比一步步斷點快得多。5.2 加載數(shù)據(jù)慢先查查詢字段和循環(huán)性能問題我前面提了兩次這里集中說一個排查順序。首先看是不是循環(huán)里逐條load數(shù)據(jù)這是最常見的性能殺手。把循環(huán)內(nèi)load改成批量loadMore或者一次性query通常能帶來幾十倍的性能提升。其次看查詢條件有沒有走索引過濾條件里的字段如果沒建索引數(shù)據(jù)量大時查詢會很慢。再者看是不是把不必要的單據(jù)體行全部加載了用OrmConfig裁剪掉無意義的大字段。我處理過最夸張的一個案例一個列表頁打開要15秒最后發(fā)現(xiàn)列表查詢條件里帶了一個基礎資料屬性的模糊匹配而那個基礎資料表有幾十萬條數(shù)據(jù)平臺做關聯(lián)查詢直接炸了。后來改造成先按編碼前綴查基礎資料再按查到的id集合過濾列表整個查詢降到1秒內(nèi)。5.3 修改數(shù)據(jù)后不生效或者保存失敗這個坑通常發(fā)生在“查到數(shù)據(jù) → 改了字段 → 直接保存”這套流程里。前面講過QueryServiceHelper查出來的數(shù)據(jù)是輕量快照不是完整業(yè)務對象。你對快照修改再調(diào)用保存服務平臺會因為數(shù)據(jù)不完整報錯或者更新的字段不生效。正確流程是用BusinessDataServiceHelper.load拿出完整實體修改字段再調(diào)用保存服務。而且如果涉及單據(jù)體行的新增、刪除、修改要特別注意行的狀態(tài)新增加的行要setStatus(EntityBase.STATUS_ADDNEW)修改的行要setStatus(EntityBase.STATUS_UPDATE)。我見過不少新手在這塊踩坑改完數(shù)據(jù)保存數(shù)據(jù)庫里紋絲不動就是行狀態(tài)沒設置對。5.4 插件沒生效時的三板斧插件寫好掛上運行沒反應先別急著懷疑代碼邏輯。我的排查順序是第一檢查插件類有沒有編譯進jar包用反編譯工具看一眼確認類存在。第二檢查BOS的插件配置是否寫對了全限定名有沒有保存發(fā)布。第三確認服務是否重啟或熱部署成功。這三步走完百分之八十的“插件沒生效”問題都能解決。如果還沒生效就去看蒼穹的日志。服務端日志里會記錄插件加載異常有時候是類沖突、有時候是依賴缺失。我遇到過最無語的一次是插件類名和打包后的包名不一致BOS配置的是舊包名新包名從未被加載日志里壓根沒有插件相關輸出折騰了兩小時。寫在最后加載數(shù)據(jù)這件事看起來是每個插件開發(fā)的第一步但真要寫順手還是得靠場景積累。我個人的體會有三條第一時刻搞清楚自己站在哪類插件上表單、列表、服務三種姿勢別混著用第二能用批量絕不用循環(huán)寫代碼之前先算一下數(shù)據(jù)量級第三數(shù)據(jù)的查詢和修改變成兩件事查出來的快照別拿去保存要保存就先load完整實體。如果你們項目中也在做蒼穹插件開發(fā)遇到加載數(shù)據(jù)相關的疑難雜癥建議把本文提到的排查順序過一遍大部分問題都能在日志和代碼里找到答案。這類插件開發(fā)的系列內(nèi)容我后面還會繼續(xù)梳理比如數(shù)據(jù)保存、表單校驗、列表自定義按鈕、服務插件的高級用法都是實打?qū)嵉捻椖拷?jīng)驗到時候再跟你們慢慢聊。 蒼穹插件開發(fā)數(shù)據(jù)加載全攻略：表單、列表、服務插件與性能優(yōu)化
做了這么多年蒼穹二開插件里“加載數(shù)據(jù)”這件事幾乎每天都在寫。但奇怪的是我在社區(qū)和客戶現(xiàn)場經(jīng)?？吹揭环N現(xiàn)象很多人代碼能跑卻不知道自己到底在加載什么為什么這樣加載換一個場景就抓瞎。今天這篇我就專門把“插件開發(fā)里的數(shù)據(jù)加載”這件事拆開揉碎講清楚從最基礎的取數(shù)方式到列表、表單、服務三類插件各自的加載套路再到我踩過的坑一次說透。這篇內(nèi)容適合誰剛接觸蒼穹插件開發(fā)、被動態(tài)表單模型繞暈的初級二開也包括已經(jīng)寫了半年一年插件、想系統(tǒng)性梳理數(shù)據(jù)加載方案的開發(fā)。全文沒有廣告沒有理論堆砌都是可以直接拿過去用的代碼片段和排查思路。1. 加載數(shù)據(jù)之前先把蒼穹的數(shù)據(jù)模型搞清楚1.1 你取到的數(shù)據(jù)到底是“顯示值”還是“存儲值”剛開始寫插件的人最容易栽的跟頭是把頁面看到的值和數(shù)據(jù)庫存的值混為一談。蒼穹頁面渲染出來的數(shù)據(jù)是經(jīng)過格式化的比如日期顯示成“2025-06-18”金額顯示成“1,234.56”基礎資料顯示成編碼名稱的組合但這些都不是數(shù)據(jù)底層的本相。插件里通過this.View.Model.GetValue(billDate)取到的通常是經(jīng)過平臺處理的DynamicObject或者基礎類型而通過GetDataEntity()拿到的才是這張單據(jù)完整的實體數(shù)據(jù)。我見過一個同事想在表單插件里拿基礎資料字段的編碼直接用了this.View.Model.GetValue(supplier)取出來一個對象打印一看里面有Id、Number、Name他當時就懵了。實際上在蒼穹的模型里基礎資料字段的值是一個Long型的id要拿到編碼和名稱得走DynamicObject的屬性取法或者通過DataEntity再去解析。這里我的建議是先分清楚你是在哪個環(huán)節(jié)取數(shù)。如果只是取當前表單頁面上某個字段的值用this.View.Model.GetValue(字段標識)就夠了如果你要拿著這條數(shù)據(jù)去做服務端邏輯或者要把單據(jù)體數(shù)據(jù)批量拿出來處理直接用this.View.Model.GetDataEntity()把整個動態(tài)實體拿到手再逐字段取。另外一個高頻坑是字段標識蒼穹里字段標識大小寫敏感而且設計器里顯示的名稱和真正的標識是兩回事。比如頁面上叫“供應商”標識可能是“supplier”也可能是“kdec_supplier”帶上前綴的往往是二開擴展字段。你寫錯一個字母運行時不報錯取回來的就是null排查要花半天。所以每次取數(shù)之前先到BOS設計器里核對一下字段標識別憑記憶寫。1.2 三種插件類加載數(shù)據(jù)的姿勢完全不同蒼穹插件主要分表單插件、列表插件、服務插件三大類我接觸過的項目中幾乎80%的數(shù)據(jù)加載需求都落在這三塊里。同類插件內(nèi)部加載數(shù)據(jù)的方式也有差異不要拿表單插件里取數(shù)的方式硬套到列表插件上。表單插件包括動態(tài)表單和單據(jù)的插件核心操作對象是this.View.Model你可以直接讀寫當前實體數(shù)據(jù)配合BeforeDoOperation、AfterDoOperation、AfterLoadData這類生命周期事件去處理數(shù)據(jù)。列表插件不一樣它的核心是ListShowParameter和QueryServiceHelper你要主動構造查詢條件去查數(shù)據(jù)再綁定到列表視圖上。服務插件則更多的在操作服務、計劃任務、審批流里跑沒有頁面Model可用一切數(shù)據(jù)都得通過服務上下文去拿。簡單說表單插件是“人在頁面上操作數(shù)據(jù)已經(jīng)躺在那里你只需讀和改”列表插件是“按條件從數(shù)據(jù)庫里拉一批數(shù)據(jù)渲染成列表”服務插件是“后臺默默處理數(shù)據(jù)要通過操作參數(shù)或服務上下文顯式去取”。這三個場景的代碼寫法和注意事項差別巨大下面我分別帶著代碼講。2. 開發(fā)環(huán)境與插件工程的基本盤2.1 一套能跑起來的本地開發(fā)環(huán)境再好的思路環(huán)境配不好也是白搭。金蝶云蒼穹的插件開發(fā)本質(zhì)上是Java開發(fā)我在項目里最常用的組合是IntelliJ IDEA 蒼穹的Maven依賴 本地/測試環(huán)境的蒼穹服務。這里有個很重要的點蒼穹插件分“蒼穹設計器內(nèi)嵌編寫”和“獨立Java工程編寫”兩種模式。設計器里那種輕量級的規(guī)則插件、簡單字段聯(lián)動可以直接在界面上配但只要是稍微復雜一點的加載數(shù)據(jù)邏輯比如多表聯(lián)查、自定義過濾、批量取數(shù)我的經(jīng)驗是必須走獨立Java工程用Maven管理依賴調(diào)試也方便。你需要在pom.xml里引入蒼穹的開發(fā)SDK依賴具體坐標版本跟你使用的蒼穹版本強相關。這個問題我在幾個客戶的現(xiàn)場都遇到過引入了錯誤的依賴版本插件一部署就報NoClassDefFoundError。正確做法是讓實施或架構組提供與你環(huán)境匹配的依賴清單或者從平臺的lib目錄下把對應jar包導出來install到本地倉庫。別自己在網(wǎng)上隨便找依賴版本版本不匹配的問題非常隱蔽。工程建好之后寫插件類、編譯、打成jar包然后在蒼穹設計器的“插件”配置里填上你的插件類全限定名保存發(fā)布。這是一個標準的二開流程。需要提醒的是每次改完Java代碼都要重啟或熱部署對應的服務否則你改的代碼不生效這種“改了沒反應”的假象我遇到過太多次最后發(fā)現(xiàn)是沒重啟。2.2 插件類要繼承誰父類決定你能干什么選錯父類是插件運行時不執(zhí)行或者找不到方法的頭號原因。我理了一下最常用的繼承關系單據(jù)/動態(tài)表單插件繼承AbstractFormPlugIn或AbstractBillPlugIn。AbstractBillPlugIn是單據(jù)插件比AbstractFormPlugIn多了單據(jù)專屬的能力。列表插件繼承AbstractListPlugIn。服務插件根據(jù)場景不同繼承AbstractOperate操作服務插件、AbstractAuditPlugIn審核相關、AbstractBillPlugInService單據(jù)服務等。我見過一個特別典型的問題同事在列表插件里重寫了afterLoadData發(fā)現(xiàn)怎么都不觸發(fā)后來一看他繼承的是AbstractFormPlugIn列表視圖根本沒有表單模型。所以動手寫之前先確認你的插件掛載在哪個位置BOS里“表單插件”“列表插件”“服務插件”三個入口對應不同的父類體系別混淆。綁定插件時注意插件標識必須是類的全限定名包括包名寫成類名簡寫是找不到的。還有一個順序問題BOS里可以掛多個插件插件之間的執(zhí)行順序按配置順序來如果A插件要先加載數(shù)據(jù)、B插件要消費A的數(shù)據(jù)順序千萬不能反否則B拿到的永遠是null。3. 實操核心三類加載數(shù)據(jù)的標準寫法3.1 表單插件用Model取當前數(shù)據(jù)用Query取擴展數(shù)據(jù)表單插件加載數(shù)據(jù)分兩種一是加載當前單據(jù)自身的數(shù)據(jù)二是根據(jù)當前單據(jù)的信息去查別的數(shù)據(jù)。前者簡單后者是常規(guī)需求。先看第一類。在單據(jù)的AfterLoadData事件里我可以這么取public class MyBillPlugin extends AbstractBillPlugIn { Override public void afterLoadData(EventObject e) { // 取單個字段值 String billNo (String) this.getModel().getValue(billNo); // 取整單數(shù)據(jù)實體 DynamicObject billData this.getModel().getDataEntity(); // 取單據(jù)體數(shù)據(jù)集合 DynamicObjectCollection entryRows billData.getDynamicObjectCollection(entryEntity); } }這里有幾個細節(jié)。getValue返回的字段類型要看字段定義比如基礎資料字段返回的是Long型id而不是對象單據(jù)體取出來的是一個DynamicObjectCollection你可以遍歷它去讀每一行。再說第二類需要查外部數(shù)據(jù)。這里我推薦優(yōu)先用QueryServiceHelper它是蒼穹里通用的查詢?nèi)肟诳梢钥绫聿?、可以加過濾條件返回DynamicObjectCollectionimport kd.bos.servicehelper.QueryServiceHelper; DynamicObjectCollection result QueryServiceHelper.query( my_bill, // 查詢的實體標識 billNo,supplier.name,totalAmount, // 要查的字段支持基礎資料屬性的點路徑 billNo ? and totalAmount ?, // 過濾條件參數(shù)用?占位 new Object[] { billNo, 1000 } // 條件參數(shù) );我自己的習慣是能用query一次性查出來的絕不循環(huán)里單條load。比如我要按單據(jù)頭一批單據(jù)號查所有單據(jù)體行直接一次query把頭和體都拉出來再在內(nèi)存里分組比在循環(huán)里一個個load效率高一個數(shù)量級。這里需要多說一句字段路徑。蒼穹的查詢字段支持用點號取關聯(lián)基礎資料的屬性比如supplier.number、supplier.name這是平臺自動join的省了你手動多表關聯(lián)的麻煩。但你得知道這種點路徑的寫法在動態(tài)表單模型里同樣適用比如getValue(supplier.name)在部分場景下也能取到。不過我用下來最穩(wěn)的還是先拿對象再取屬性。3.2 列表插件構造查詢參數(shù)喂給列表視圖列表插件加載數(shù)據(jù)的思路和表單插件完全不同。列表頁的核心是ListShowParameter你構造好它再調(diào)用this.getView().showData()就能刷新列表。一個最基礎的列表加載長這樣public class MyListPlugin extends AbstractListPlugIn { // 刷新列表數(shù)據(jù)可指定過濾條件 public void refreshList() { ListShowParameter showParam new ListShowParameter(); showParam.setFormId(my_bill); // 設置列表的過濾條件只在當前列表視圖生效 showParam.getCustomParams().put(keyword, 張三); // 打開或刷新 this.getView().showData(showParam); } }但實際項目里列表插件更多的場景是重寫查詢條件。常見的是在afterQueryData里對查出來的數(shù)據(jù)做二次加工或者在beforeQueryData里改寫查詢參數(shù)。我項目中用得最多的是重寫列表的過濾Override public void setFilter(FilterParameter filter) { super.setFilter(filter); // 追加客戶權限過濾 filter.getFilterItems().add(new FilterItem(customer.id, , currentCustomerId)); }還有個使用要點列表插件的取數(shù)如果只是展示不需要把數(shù)據(jù)實體全部加載出來盡量只取列表需要的字段否則數(shù)據(jù)量大的時候列表首屏會很慢。我在一個客戶現(xiàn)場排查過他們列表每次打開要5秒后來發(fā)現(xiàn)是查詢條件里帶了單據(jù)體字段導致平臺把整個主從表都load了一次。去掉單據(jù)體字段后首屏降到1秒以內(nèi)。列表加載完數(shù)據(jù)后你還可以在afterQueryData里拿到查詢結果集Override public void afterQueryData(EventObject e) { super.afterQueryData(e); DynamicObjectCollection rows this.getModel().getDataEntities(); // 對返回結果做加工或統(tǒng)計 }這里注意afterQueryData里的數(shù)據(jù)是當前列表頁展示的那一頁數(shù)據(jù)不是全量數(shù)據(jù)。如果你要統(tǒng)計整個數(shù)據(jù)集的匯總別在這里寫聚合邏輯否則你統(tǒng)計的只是當前頁。3.3 服務插件從操作上下文里取數(shù)據(jù)服務插件沒有頁面Model最常見的是操作服務插件通過繼承AbstractOperate來實現(xiàn)。它的核心方法是execute通過OperateContext上下文取參數(shù)。public class MyOperatePlugin extends AbstractOperate { Override public void execute(OperateContext ctx) throws Exception { // 操作服務傳入的選中數(shù)據(jù)一般是Long[]形式的id數(shù)組 Long[] selectedIds ctx.getSelectedIds(); // 按具體操作類型可能需要從ctx.getDataEntities()取完整數(shù)據(jù) DynamicObject firstRow ctx.getDataEntity(); // 或者取操作參數(shù)里的自定義參數(shù) Object customValue ctx.getCustomParam(customKey); } }在服務插件里取數(shù)要區(qū)分兩個來源如果操作是從列表頁發(fā)起的ctx.getSelectedIds()會帶選中行的id如果是從單據(jù)詳情頁發(fā)起的ctx.getDataEntities()里會有當前單據(jù)的實體數(shù)據(jù)。我做過一個批量審核的服務插件就是先拿selectedIds再批量load單據(jù)數(shù)據(jù)逐條做校驗最后調(diào)用審核服務。服務插件里加載數(shù)據(jù)我強烈建議用批量接口不要一條條循環(huán)load。蒼穹的BusinessDataServiceHelper提供了load和loadMore兩個方法import kd.bos.servicehelper.BusinessDataServiceHelper; // 單條加載 DynamicObject single BusinessDataServiceHelper.load(id, my_bill); // 批量加載 DynamicObjectCollection batch BusinessDataServiceHelper.loadMore(ids, my_bill);如果數(shù)據(jù)量比較大比如一次幾百上千條還有分頁load的姿勢用loadMore配合OrmConfig做字段裁剪只取你要用到的字段避免把大字段比如文本、附件信息也一并load出來內(nèi)存和性能都會好很多。我寫過一次批量處理沒裁剪字段結果服務直接OOM了后來加了OrmConfig只取必要字段內(nèi)存瞬間降下來。3.4 通過OrmConfig控制加載字段性能差距就在這BusinessDataServiceHelper.load系列方法支持傳OrmConfig用來指定查詢哪些字段類似于SQL里的select指定列。這個參數(shù)很多初學者會忽略但它是性能優(yōu)化的第一道門。import kd.bos.orm.OrmConfig; OrmConfig config new OrmConfig(); config.addField(billNo); config.addField(supplier); config.addField(entryEntity.entryRow); config.addField(entryEntity.amount); DynamicObjectCollection dataRows BusinessDataServiceHelper.loadMore( ids, my_bill, config );OrmConfig還有一個好處你可以控制是否加載單據(jù)體行、是否加載基礎資料屬性。默認情況下load會連基礎資料的關聯(lián)屬性都帶出來數(shù)據(jù)量大時開銷很明顯。如果你只需要Id和Number就明確只查這兩個字段別讓平臺白做那么多join。我自己的一個經(jīng)驗閾值是超過50條的批量load一律用OrmConfig裁剪字段超過200條的必須做分頁超過1000條的建議直接走QueryServiceHelper用分頁查詢。這套標準我在多個項目里復用基本沒出過性能事故。4. 查詢引擎與服務選擇的細節(jié)決定代碼上限4.1 什么時候用QueryServiceHelper什么時候用BusinessDataServiceHelper這是我在面試候選人時經(jīng)常問的一個問題也是項目里爭論最多的點。我先把結論說出來查詢展示用QueryServiceHelper拿到實體做操作用BusinessDataServiceHelper。QueryServiceHelper適合做列表查詢、報表取數(shù)、條件統(tǒng)計這類只讀場景它支持復雜過濾、排序、分頁查出來的DynamicObject是輕量的行數(shù)據(jù)。BusinessDataServiceHelper.load系列適合按id讀取完整業(yè)務對象它會返回帶單據(jù)體的完整實體你可以直接對這個實體做修改再保存或者把它傳給操作服務去審核、提交。兩者之間有一個很容易踩的坑QueryServiceHelper查出來的數(shù)據(jù)是“查詢快照”它不是完整的業(yè)務對象有些字段沒查的話就是null而且不能直接拿去調(diào)保存操作。如果代碼里查完直接改數(shù)據(jù)再提交保存往往保存的只是部分字段甚至因為缺了關鍵字段導致保存報錯。正確做法是拿到查詢出的id后再用BusinessDataServiceHelper.load把完整實體load出來在完整實體上改數(shù)據(jù)、做操作。4.2 寫過濾條件時的表達式語法蒼穹查詢的過濾條件不是原生SQL它有一套自己的表達式規(guī)則?；緦懛ㄊ恰白侄螛俗R 比較符 參數(shù)占位符”。比較多的是等于、不等于、大于、小于、in集合、like模糊匹配。in集合的寫法我截個代碼DynamicObjectCollection result QueryServiceHelper.query( my_bill, billNo,customer.name,totalAmount,status, billNo in (?, ?, ?) or status ?, new Object[] { BILL001, BILL002, BILL003, A } );如果你只有一個集合參數(shù)也可以把集合當一個占位符傳進去蒼穹支持把List或數(shù)組整體作為一個in參數(shù)。但要注意空的集合千萬不要傳否則生成的SQL可能變成in ()有些數(shù)據(jù)庫直接報錯有些數(shù)據(jù)庫查不出數(shù)據(jù)這算一個低級但常見的坑。還有l(wèi)ike的寫法參數(shù)里拼%號比如new Object[]{% keyword %}而不是在條件里寫like %?%。這點和JDBC的PreparedStatement習慣一樣參數(shù)和SQL模板要分開平臺才能正確做防注入和類型轉(zhuǎn)換。4.3 數(shù)據(jù)權限與字段權限的隱藏坑服務插件里取數(shù)如果不做任何處理默認是帶操作者上下文的也就是說查詢結果會受到數(shù)據(jù)權限和字段權限控制。這個機制有好有壞。好的一面是安全壞的一面是你可能會莫名其妙地查不到數(shù)據(jù)。我第一次做項目時就遇到過管理員賬號跑計劃任務查數(shù)據(jù)全正常換普通賬號在前臺觸發(fā)同一個服務查出來少了幾條。排查了半天最后發(fā)現(xiàn)是數(shù)據(jù)權限規(guī)則在起作用。解決方案要看具體需求如果查詢就應該遵守權限那就保持默認如果后臺任務必須繞過權限則要用特定的查詢?nèi)肟诨蛘咛嵘舷挛?。我個人的習慣是后臺任務、計劃任務這類場景盡量顯式處理權限上下文前臺用戶操作的場景則明確依賴權限校驗。字段權限的坑更隱蔽。有時候數(shù)據(jù)能查出來但某些字段返回null不是因為數(shù)據(jù)沒有值而是當前操作者對該字段沒有查看權限平臺在查詢層就把字段值屏蔽了。遇到這種情況先別懷疑代碼用管理員賬號跑一次同樣的邏輯如果管理員能看到那就是字段權限問題去權限配置里檢查即可。5. 常見問題與排查技巧實錄5.1 為什么插件里取出來的數(shù)據(jù)總是null這個問題的出現(xiàn)頻率在我的答疑記錄里排第一。我總結了一下十個里有七個是以下三個原因一是字段標識寫錯。區(qū)分大小寫、帶不帶擴展前綴去BOS設計器里核對別靠記憶。二是取數(shù)時機不對。表單還沒加載完就去取數(shù)據(jù)比如在beforeBindData里用getValue取頁面值這時候數(shù)據(jù)都還沒進來取到null太正常了。要在afterBindData、afterLoadData這類生命周期事件里取。三是數(shù)據(jù)源本身就沒值。頁面可能顯示了值但那個值是計算列或動態(tài)字段不是真實存儲字段。你需要在數(shù)據(jù)庫里直接跑一條SQL確認數(shù)據(jù)是否存在排除業(yè)務數(shù)據(jù)本身為空的情況。排查這類問題我有一招特別好用在代碼里打印當前數(shù)據(jù)實體的JSON串。用JSONUtils.toJson(dataEntity)或者直接輸出實體類型一跑就能看到數(shù)據(jù)里到底有哪些字段、哪些值是null比一步步斷點快得多。5.2 加載數(shù)據(jù)慢先查查詢字段和循環(huán)性能問題我前面提了兩次這里集中說一個排查順序。首先看是不是循環(huán)里逐條load數(shù)據(jù)這是最常見的性能殺手。把循環(huán)內(nèi)load改成批量loadMore或者一次性query通常能帶來幾十倍的性能提升。其次看查詢條件有沒有走索引過濾條件里的字段如果沒建索引數(shù)據(jù)量大時查詢會很慢。再者看是不是把不必要的單據(jù)體行全部加載了用OrmConfig裁剪掉無意義的大字段。我處理過最夸張的一個案例一個列表頁打開要15秒最后發(fā)現(xiàn)列表查詢條件里帶了一個基礎資料屬性的模糊匹配而那個基礎資料表有幾十萬條數(shù)據(jù)平臺做關聯(lián)查詢直接炸了。后來改造成先按編碼前綴查基礎資料再按查到的id集合過濾列表整個查詢降到1秒內(nèi)。5.3 修改數(shù)據(jù)后不生效或者保存失敗這個坑通常發(fā)生在“查到數(shù)據(jù) → 改了字段 → 直接保存”這套流程里。前面講過QueryServiceHelper查出來的數(shù)據(jù)是輕量快照不是完整業(yè)務對象。你對快照修改再調(diào)用保存服務平臺會因為數(shù)據(jù)不完整報錯或者更新的字段不生效。正確流程是用BusinessDataServiceHelper.load拿出完整實體修改字段再調(diào)用保存服務。而且如果涉及單據(jù)體行的新增、刪除、修改要特別注意行的狀態(tài)新增加的行要setStatus(EntityBase.STATUS_ADDNEW)修改的行要setStatus(EntityBase.STATUS_UPDATE)。我見過不少新手在這塊踩坑改完數(shù)據(jù)保存數(shù)據(jù)庫里紋絲不動就是行狀態(tài)沒設置對。5.4 插件沒生效時的三板斧插件寫好掛上運行沒反應先別急著懷疑代碼邏輯。我的排查順序是第一檢查插件類有沒有編譯進jar包用反編譯工具看一眼確認類存在。第二檢查BOS的插件配置是否寫對了全限定名有沒有保存發(fā)布。第三確認服務是否重啟或熱部署成功。這三步走完百分之八十的“插件沒生效”問題都能解決。如果還沒生效就去看蒼穹的日志。服務端日志里會記錄插件加載異常有時候是類沖突、有時候是依賴缺失。我遇到過最無語的一次是插件類名和打包后的包名不一致BOS配置的是舊包名新包名從未被加載日志里壓根沒有插件相關輸出折騰了兩小時。寫在最后加載數(shù)據(jù)這件事看起來是每個插件開發(fā)的第一步但真要寫順手還是得靠場景積累。我個人的體會有三條第一時刻搞清楚自己站在哪類插件上表單、列表、服務三種姿勢別混著用第二能用批量絕不用循環(huán)寫代碼之前先算一下數(shù)據(jù)量級第三數(shù)據(jù)的查詢和修改變成兩件事查出來的快照別拿去保存要保存就先load完整實體。如果你們項目中也在做蒼穹插件開發(fā)遇到加載數(shù)據(jù)相關的疑難雜癥建議把本文提到的排查順序過一遍大部分問題都能在日志和代碼里找到答案。這類插件開發(fā)的系列內(nèi)容我后面還會繼續(xù)梳理比如數(shù)據(jù)保存、表單校驗、列表自定義按鈕、服務插件的高級用法都是實打?qū)嵉捻椖拷?jīng)驗到時候再跟你們慢慢聊。