Hive 3.1.2 版本做 UDF 開發(fā)是個(gè)挺容易踩坑的活兒。網(wǎng)上很多教程還停留在 Hive 1.x/2.x 的老寫法照著做大概率會(huì)碰到類沖突、方法簽名不識別這類問題。我自己在 3.1.2 上踩了一輪坑之后把完整流程和避坑點(diǎn)整理出來希望能幫你少走彎路。1. 開發(fā)前的環(huán)境認(rèn)知與版本陷阱1.1 為什么要專門強(qiáng)調(diào) 3.1.2 版本Hive 3.1.2 是 Hive 3.x 系列里比較穩(wěn)定的一個(gè)版本很多公司的生產(chǎn)環(huán)境都在用。但這個(gè)版本和 2.x 相比有幾個(gè)直接影響 UDF 開發(fā)的底層變化依賴的 Hadoop 版本升級到了 3.x 系列導(dǎo)致一些老的 hive-exec 依賴寫法會(huì)出現(xiàn) NoSuchMethodError。引入了更嚴(yán)格的 SQL 標(biāo)準(zhǔn)合規(guī)檢查對函數(shù)注冊和調(diào)用的方式有影響。移除了部分 deprecated 的 API比如舊的UDF類雖然保留但GenericUDF的初始化流程有細(xì)微差別。Hive 3.x 默認(rèn)使用 LLAP 和新的執(zhí)行引擎UDF 在本地調(diào)試和集群運(yùn)行時(shí)的類加載機(jī)制不完全一樣。這些變化意味著如果你直接搜網(wǎng)上 Hive UDF 教程 然后復(fù)制代碼大概率會(huì)在打包或者運(yùn)行時(shí)碰到各種詭異報(bào)錯(cuò)。1.2 Maven 依賴的正確配置方法在 Hive 3.1.2 下開發(fā) UDF最穩(wěn)妥的 Maven 依賴配置是這樣dependency groupIdorg.apache.hive/groupId artifactIdhive-exec/artifactId version3.1.2/version scopeprovided/scope /dependency dependency groupIdorg.apache.hadoop/groupId artifactIdhadoop-common/artifactId version3.1.0/version scopeprovided/scope /dependency幾個(gè)關(guān)鍵點(diǎn)解釋一下scope必須設(shè)置為provided因?yàn)?Hive 集群環(huán)境本身已經(jīng)有這些 jar 了。如果打成 fat jar 把這些依賴打進(jìn)去極大概率會(huì)引發(fā)類沖突出現(xiàn)ClassNotFoundException或者奇怪的序列化錯(cuò)誤。Hadoop 版本不一定要跟 Hive 自帶的一模一樣3.1.0和3.1.1通常兼容。但如果業(yè)務(wù)方指定了 Hadoop 版本以實(shí)際環(huán)境為準(zhǔn)。如果你在代碼里用到org.apache.hadoop.hive.ql.exec.UDF還需要確認(rèn)hive-exec沒有被其他傳遞依賴干擾。建議在pom.xml里加exclusions把hive-common、log4j等排除掉避免和集群自帶的沖突。提示不要用hive-udf這種單獨(dú)的 artifactId 名稱那是老版本的方案3.x 下直接在hive-exec里就有完整的 UDF API。1.3 本地開發(fā)環(huán)境的 JDK 選擇Hive 3.1.2 官方推薦 JDK 是 Java 8本地開發(fā)也盡量用 JDK 8。如果你用 JDK 11 或 17 編譯雖然有些功能能跑但集群上如果還是 JDK 8 的環(huán)境運(yùn)行時(shí)容易出現(xiàn)UnsupportedClassVersionError。建議開發(fā)機(jī)裝一個(gè) JDK 8Maven 的pom.xml里加編譯參數(shù)properties maven.compiler.source1.8/maven.compiler.source maven.compiler.target1.8/maven.compiler.target /properties2. UDF 開發(fā)的兩種核心寫法與適用場景2.1 繼承 UDF 類的簡單寫法這是最簡單的一種方式適用于輸入輸出都是一對一的場景比如字符串處理、數(shù)值計(jì)算。package com.example.hive.udf; import org.apache.hadoop.hive.ql.exec.UDF; import org.apache.hadoop.io.Text; public class MaskPhone extends UDF { public Text evaluate(Text phone) { if (phone null) { return null; } String value phone.toString(); if (value.length() 7) { return new Text(value); } String masked value.substring(0, 3) **** value.substring(7); return new Text(masked); } }這個(gè)方法就干了件很典型的事把手機(jī)號中間四位脫敏。整個(gè)處理邏輯很直接方法就是evaluateHive 引擎會(huì)根據(jù)參數(shù)類型自動(dòng)找到對應(yīng)的方法。UDF基類的作用是幫你解決反射匹配那部分繁瑣的內(nèi)容自己只需要關(guān)心業(yè)務(wù)實(shí)現(xiàn)。這里有個(gè)小細(xì)節(jié)返回值最好用 Hadoop 的Text類型而不是 Java 的String。雖然Text也能轉(zhuǎn)成String但用Text在很多場景下性能更好。如果你返回 Java 基礎(chǔ)類型比如int、doubleHive 也能處理但會(huì)出現(xiàn)序列化層面的隱式轉(zhuǎn)換數(shù)據(jù)量大的時(shí)候差距能感覺到。2.2 繼承 GenericUDF 的高級寫法簡單UDF在處理復(fù)雜類型如struct、map、array或者需要做參數(shù)個(gè)數(shù)校驗(yàn)時(shí)就比較吃力。這時(shí)候需要GenericUDF。package com.example.hive.udf; import org.apache.hadoop.hive.ql.exec.UDFArgumentException; import org.apache.hadoop.hive.ql.exec.UDFArgumentLengthException; import org.apache.hadoop.hive.ql.exec.UDFArgumentTypeException; import org.apache.hadoop.hive.ql.metadata.HiveException; import org.apache.hadoop.hive.ql.udf.generic.GenericUDF; import org.apache.hadoop.hive.serde2.objectinspector.ObjectInspector; import org.apache.hadoop.hive.serde2.objectinspector.ObjectInspectorUtils; import org.apache.hadoop.hive.serde2.objectinspector.primitive.PrimitiveObjectInspectorFactory; import org.apache.hadoop.hive.serde2.objectinspector.primitive.StringObjectInspector; import org.apache.hadoop.io.Text; public class GenericMaskPhone extends GenericUDF { private StringObjectInspector stringOI; Override public ObjectInspector initialize(ObjectInspector[] arguments) throws UDFArgumentException { if (arguments.length ! 1) { throw new UDFArgumentLengthException(GenericMaskPhone 需要恰好 1 個(gè)參數(shù)你傳了 arguments.length 個(gè)); } if (arguments[0].getCategory() ! ObjectInspector.Category.PRIMITIVE || !(arguments[0] instanceof StringObjectInspector)) { throw new UDFArgumentTypeException(0, 參數(shù)類型錯(cuò)誤第一個(gè)參數(shù)需要是 STRING 類型); } stringOI (StringObjectInspector) arguments[0]; return PrimitiveObjectInspectorFactory.writableStringObjectInspector; } Override public Object evaluate(DeferredObject[] arguments) throws HiveException { if (arguments[0] null || arguments[0].get() null) { return null; } String value stringOI.getPrimitiveJavaObject(arguments[0].get()); if (value.length() 7) { return new Text(value); } return new Text(value.substring(0, 3) **** value.substring(7)); } Override public String getDisplayString(String[] children) { return GenericMaskPhone( children[0] ); } }GenericUDF的三個(gè)方法各有分工initialize在函數(shù)第一次執(zhí)行時(shí)被調(diào)用用來確定參數(shù)類型、校驗(yàn)參數(shù)個(gè)數(shù)并定義返回值的類型。這里的返回值從ObjectInspector來描述既是給引擎看的元數(shù)據(jù)信息也是后續(xù)處理數(shù)據(jù)的依據(jù)。evaluate是真正處理數(shù)據(jù)的核心每行數(shù)據(jù)都會(huì)調(diào)用一次。getDisplayString用于展示函數(shù)調(diào)用形式在 explain 語句和日志中會(huì)用到格式不嚴(yán)謹(jǐn)也沒關(guān)系但不能返回 null。很多新人在initialize里容易犯一個(gè)錯(cuò)以為可以在這里拿到數(shù)據(jù)。實(shí)際上這里只拿類型信息數(shù)據(jù)在evaluate里才能拿到。把ObjectInspector緩存下來就是為了在evaluate里高效地讀取數(shù)據(jù)。2.3 兩種寫法的選型建議做一個(gè)簡單的對比對比項(xiàng)繼承 UDF繼承 GenericUDF代碼量少只需寫 evaluate多要寫三個(gè)方法參數(shù)類型校驗(yàn)松散靠反射匹配嚴(yán)密可在 initialize 中精確控制復(fù)雜類型支持有限完全支持 struct/map/array性能略差更優(yōu)Debug 友好度簡單較復(fù)雜需要理解 ObjectInspector我的經(jīng)驗(yàn)是處理基本類型、邏輯簡單的場景直接用簡單UDF就好代碼可讀性好。但如果你需要處理嵌套結(jié)構(gòu)或者要檢查參數(shù)個(gè)數(shù)、按不同類型選擇不同的處理分支GenericUDF在復(fù)雜場景下更有優(yōu)勢排查問題也更直觀。3. 完整實(shí)操從代碼到集群運(yùn)行3.1 測試用例的編寫技巧很多開發(fā)者在本地寫完 UDF 之后直接扔到集群上測試結(jié)果一執(zhí)行就報(bào)錯(cuò)來回調(diào)試的成本特別高。其實(shí)在本地用 JUnit 寫一個(gè)測試用例幾分鐘就能驗(yàn)證大部分邏輯問題。package com.example.hive.udf; import org.apache.hadoop.io.Text; import org.junit.Assert; import org.junit.Test; public class MaskPhoneTest { Test public void testNormal() { MaskPhone udf new MaskPhone(); Text result udf.evaluate(new Text(13812345678)); Assert.assertEquals(138****5678, result.toString()); } Test public void testNull() { MaskPhone udf new MaskPhone(); Assert.assertNull(udf.evaluate(null)); } Test public void testShortLength() { MaskPhone udf new MaskPhone(); Text result udf.evaluate(new Text(123456)); Assert.assertEquals(123456, result.toString()); } }測試重點(diǎn)覆蓋三類情況正常輸入、空值、邊界值。特別是空值很多 UDF 在這上面崩潰過——用戶在 SQL 里寫where column is not null過濾掉了一部分但 UDF 內(nèi)部還是要做好防御。測試的依賴在 pom.xml 中加上dependency groupIdjunit/groupId artifactIdjunit/artifactId version4.13.2/version scopetest/scope /dependency3.2 打包與上傳 HDFS本地測試通過之后執(zhí)行mvn clean package -DskipTests打包。輸出 jar 一般不大幾百 KB 到幾 MB 都正常。把 jar 上傳到 HDFS 的常見做法hdfs dfs -mkdir -p /udf/lib hdfs dfs -put mask-udf-1.0.jar /udf/lib/為什么要放 HDFS 而不是直接放本機(jī)因?yàn)?Hive 集群可能是多節(jié)點(diǎn)如果只放在提交任務(wù)的節(jié)點(diǎn)上其他節(jié)點(diǎn)執(zhí)行時(shí)找不到 jar就會(huì)報(bào)ClassNotFoundException。放在 HDFS 上所有節(jié)點(diǎn)都能加載。這是個(gè)經(jīng)典坑務(wù)必注意。3.3 永久函數(shù)與臨時(shí)函數(shù)注冊在 Hive 3.1.2 中臨時(shí)函數(shù)的注冊方式ADD JAR hdfs:///udf/lib/mask-udf-1.0.jar; CREATE TEMPORARY FUNCTION mask_phone AS com.example.hive.udf.MaskPhone;臨時(shí)函數(shù)只在當(dāng)前會(huì)話有效斷開會(huì)話就失效適合開發(fā)測試階段使用。要在生產(chǎn)環(huán)境長期使用建議注冊為永久函數(shù)CREATE FUNCTION mask_phone AS com.example.hive.udf.MaskPhone USING JAR hdfs:///udf/lib/mask-udf-1.0.jar;注意永久函數(shù)的創(chuàng)建可能需要管理員權(quán)限如果當(dāng)前用戶沒有權(quán)限會(huì)報(bào)AuthorizationException。如果自己不是管理員可以讓 DBA 幫忙或者把 jar 的權(quán)限放開到 HDFS 上允許讀。Hive 3.1.2 里函數(shù)名最好不要帶橫線或點(diǎn)會(huì)跟一些內(nèi)部命名沖突。用下劃線連接是最穩(wěn)妥的寫法。3.4 實(shí)際調(diào)用驗(yàn)證注冊完成之后執(zhí)行一條 SQL 驗(yàn)證SELECT mask_phone(13812345678);正常結(jié)果應(yīng)該輸出138****5678。再試一下空值場景SELECT mask_phone(null);應(yīng)該返回NULL而不是報(bào)錯(cuò)。順便可以驗(yàn)證一下在WHERE條件中使用 UDF 的效果SELECT id, phone FROM user_phone WHERE mask_phone(phone) 138****5678;到這里簡單 UDF 的基本流程就算跑通了。4. 進(jìn)階GenericUDF 初始化與常量折疊問題4.1 initialize 方法里的參數(shù)校驗(yàn)細(xì)節(jié)很多復(fù)雜的 bug 都出在initialize方法上。有些場景下 UDF 的入?yún)⒖赡苁浅Ａ恳部赡苁亲侄?。ObjectInspector拿到的是類型描述而不是具體數(shù)值。在initialize里做校驗(yàn)時(shí)要格外注意不要嘗試讀取參數(shù)值只做類型和數(shù)量檢查。比如要處理兩個(gè)參數(shù)第一個(gè)是字符串第二個(gè)是整數(shù)可以這樣校驗(yàn)Override public ObjectInspector initialize(ObjectInspector[] arguments) throws UDFArgumentException { if (arguments.length ! 2) { throw new UDFArgumentLengthException(需要兩個(gè)參數(shù)); } if (arguments[0].getCategory() ! ObjectInspector.Category.PRIMITIVE) { throw new UDFArgumentTypeException(0, 第一個(gè)參數(shù)必須是基本類型); } PrimitiveObjectInspector poi0 (PrimitiveObjectInspector) arguments[0]; PrimitiveObjectInspector poi1 (PrimitiveObjectInspector) arguments[1]; if (poi0.getPrimitiveCategory() ! PrimitiveObjectInspector.PrimitiveCategory.STRING) { throw new UDFArgumentTypeException(0, 第一個(gè)參數(shù)必須是 STRING); } if (poi1.getPrimitiveCategory() ! PrimitiveObjectInspector.PrimitiveCategory.INT) { throw new UDFArgumentTypeException(1, 第二個(gè)參數(shù)必須是 INT); } return PrimitiveObjectInspectorFactory.writableStringObjectInspector; }注意這里用的getPrimitiveCategory()是更細(xì)粒度的類型判斷。STRING和CHAR、VARCHAR是不同的類別但某些場景下你可能希望同時(shí)接受它們。這種取舍要根據(jù)業(yè)務(wù)需求來定。4.2 常量折疊帶來的“詭異”現(xiàn)象Hive 3.1.2 的優(yōu)化器會(huì)在某些情況下做常量折疊。什么意思呢如果你執(zhí)行SELECT mask_phone(13812345678)引擎可能在你還沒進(jìn)入真正的 UDF 執(zhí)行前就把參數(shù)作為常量推導(dǎo)出結(jié)果了。這種情況下initialize可能根本不會(huì)被調(diào)用或者只調(diào)用一次。這種優(yōu)化通常不會(huì)影響最終結(jié)果但如果你在 UDF 里寫了static變量想保存狀態(tài)就需要注意不要依賴evaluate的調(diào)用次數(shù)。比如用static int count統(tǒng)計(jì)共處理了多少行在常量折疊下統(tǒng)計(jì)結(jié)果可能不準(zhǔn)確。4.3 UDF 中的狀態(tài)管理規(guī)范Hive 的 UDF 是被多線程并發(fā)調(diào)用的。同一個(gè) UDF 實(shí)例可能同時(shí)被多個(gè) mapper/reducer 線程使用因此不要在 UDF 里使用非線程安全的成員變量比如SimpleDateFormat。不要用成員變量保存行級狀態(tài)比如lastValue這種。如果確實(shí)需要線程安全的格式化工具在initialize里創(chuàng)建局部變量或者用ThreadLocal。踩過坑的開發(fā)者都知道這類并發(fā)問題在測試階段很難發(fā)現(xiàn)通常要到數(shù)據(jù)量大了之后突然報(bào)錯(cuò)排查起來相當(dāng)痛苦。5. 三個(gè)最容易踩的運(yùn)行時(shí)坑5.1 ClassNotFound 與依賴沖突這是出現(xiàn)頻率最高的問題。打包時(shí)如果用了maven-shade-plugin把 Hive 依賴打進(jìn)了 fat jar運(yùn)行時(shí)就會(huì)出現(xiàn)一個(gè)詭異的現(xiàn)象本地測試正常上傳集群就報(bào)錯(cuò)。典型報(bào)錯(cuò)信息java.lang.NoSuchMethodError: org.apache.hadoop.hive.ql.exec.UDF.evaluate解決思路把pom.xml中hive-exec的scope改成provided同時(shí)確保打的是瘦 jar。如果確實(shí)有特殊依賴需要打包用 shade 插件盡量排除org.apache.hive和org.apache.hadoop相關(guān)包名。另一個(gè)思路是直接用 Hive 的ADD JAR把額外的依賴 jar 加載進(jìn)來ADD JAR hdfs:///udf/lib/commons-lang3.jar; ADD JAR hdfs:///udf/lib/guava-27.0-jre.jar;注意優(yōu)先級問題后添加的 jar 可能覆蓋先添加的。同一份依賴集群自帶的版本和 jar 里的版本不一致時(shí)容易引發(fā)沖突。避免這種問題的最佳做法就是別在 UDF 里用和 Hive 核心依賴重疊的開源庫迫不得已時(shí)要精心管理類加載順序。5.2 返回 null 時(shí)引發(fā)的 NPEHive 里遇到null是家常便飯。UDF 里的evaluate方法如果收到null參數(shù)而代碼里沒做判空很容易 NPE。我見過的最隱蔽 NPE 是這么出現(xiàn)的public Text evaluate(Text a, Text b) { if (!a.toString().equals(b.toString())) { return new Text(not_equal); } return new Text(equal); }看著沒問題但如果a為 null調(diào)用a.toString()就 NPE 了。更麻煩的是Hive 引擎有時(shí)會(huì)把空字符串和 null 混在一起行為難以預(yù)測。建議在方法最開始統(tǒng)一判空if (a null || b null) { return null; }5.3 類型隱式轉(zhuǎn)換導(dǎo)致的結(jié)果異常Hive 3.1.2 對類型轉(zhuǎn)換有一套規(guī)則。比如你寫mask_phone(phone)而phone是varchar(20)而不是string簡單 UDF 的反射機(jī)制可能匹配不到對應(yīng)的evaluate方法要么報(bào)錯(cuò)要么是類型轉(zhuǎn)換消耗額外時(shí)間。更隱蔽的問題是精度丟失比如 UDF 參數(shù)用Double而傳入的是高精度的DecimalHive 會(huì)轉(zhuǎn)成 double 進(jìn)行處理可能丟掉精度。處理金額類數(shù)據(jù)時(shí)尤其小心盡量用BigDecimal或Text來確定性的字符串處理。6. 性能調(diào)優(yōu)與 UDF 編寫規(guī)范6.1 避免不必要的對象創(chuàng)建每行數(shù)據(jù)都調(diào)用evaluate如果每次都new一個(gè)StringBuilder或ArrayList在大數(shù)據(jù)量下就是海量對象創(chuàng)建GC 壓力飆升。更優(yōu)的寫法是在GenericUDF里把可重用的Object作為成員變量緩存起來前提是線程安全或者直接復(fù)用輸入的Text對象。在簡單 UDF 中如果必須返回字符串盡量少做無意義的拼接可以用StringBuilder的鏈?zhǔn)秸{(diào)用減少中間對象。6.2 分段處理與空值短路把復(fù)雜的 UDF 拆成多個(gè)簡單函數(shù)往往比一個(gè)超級函數(shù)更高效。因?yàn)?Hive 的謂詞下推和列剪枝能幫你過濾掉很多不需要計(jì)算的行。數(shù)據(jù)量大時(shí)空值短路很重要。如果 UDF 檢測到某個(gè)字段為 null直接返回 null后續(xù)的復(fù)雜邏輯就不用執(zhí)行了。這樣既避免 NPE又能減少不必要的計(jì)算。7. 常見問題速查表報(bào)錯(cuò)信息可能原因解決方案ClassNotFoundException: com.example.hive.udf.MaskPhonejar 未加載或路徑不對確認(rèn) ADD JAR 是否執(zhí)行jar 是否在 HDFS 上NoSuchMethodError: evaluatehive-exec 依賴沖突引入了錯(cuò)誤的版本檢查 pom.xml scope 是否為 provided清理 fat jarUDFArgumentException: 參數(shù)類型錯(cuò)誤initialize 中的類型校驗(yàn)過于嚴(yán)格檢查參數(shù)類別確認(rèn) STRING 與 VARCHAR 的區(qū)別AuthorizationException當(dāng)前用戶無創(chuàng)建永久函數(shù)權(quán)限聯(lián)系管理員授權(quán)或用臨時(shí)函數(shù)代替UnsupportedClassVersionError本地編譯 JDK 版本高于集群 JDK統(tǒng)一使用 JDK 8 編譯檢查 maven compiler 配置SemanticsException: Function is not registered創(chuàng)建函數(shù)的庫名不是當(dāng)前庫使用 db_name.function_name 顯式指定查詢結(jié)果為空但日志無報(bào)錯(cuò)常量折疊或 null 短路導(dǎo)致 UDF 未執(zhí)行檢查執(zhí)行計(jì)劃 EXPLAIN確認(rèn) UDF 是否被下推8. UDF 擴(kuò)展方向與調(diào)試建議8.1 從 UDF 到 UDTF 和 UDAFUDF 是一進(jìn)一出UDTF 是一進(jìn)多出比如把一行拆成多行UDAF 是多進(jìn)一出聚合函數(shù)比如自研 sum。如果業(yè)務(wù)上需要把 JSON 數(shù)組字段展開成多行就需要寫 UDTF這屬于GenericUDTF的范疇。UDAF 的情況更復(fù)雜一點(diǎn)Hive 3.1.2 推薦直接繼承AbstractGenericUDAFResolver和實(shí)現(xiàn)GenericUDAFEvaluator中間設(shè)計(jì)到Mode狀態(tài)機(jī)PARTIAL1、PARTIAL2、FINAL、COMPLETE不同階段對應(yīng)不同的iterate、merge、terminate方法回調(diào)。這塊建議單獨(dú)開項(xiàng)目不要在簡單 UDF 基礎(chǔ)上改動(dòng)。8.2 Debug 技巧日志輸出定位問題集群環(huán)境不好打斷點(diǎn)大部分 UDF 問題靠日志定位。Hive 的LogHelper可以輸出到 Hive 日志中import org.apache.hadoop.hive.ql.log.PerfLogger; // 或者使用 slf4j private static final Logger LOG LoggerFactory.getLogger(MaskPhone.class); Override public Object evaluate(DeferredObject[] arguments) throws HiveException { if (LOG.isDebugEnabled()) { LOG.debug(參數(shù)值: arguments[0].get()); } // 業(yè)務(wù)邏輯 }日志級別在log4j2.properties或hive-log4j2.properties里配置。調(diào)成 DEBUG 后跑一條小數(shù)據(jù)量的 SQL就能看到 UDF 的輸入輸出。查到問題后記得切回 WARN 級別避免日志量把集群磁盤打滿。我在實(shí)際開發(fā)過程中最后悔的一件事就是最開始沒養(yǎng)成良好的判空習(xí)慣導(dǎo)致上線后遇到空值 NPE還得緊急改版本重新打包。另外每次改完 UDF 記得清掉 Hive 的緩存有時(shí)候函數(shù)注冊信息在 session 里是帶緩存的重新注冊同名函數(shù)時(shí)可能調(diào)用的還是舊版本。這種情況可以DROP FUNCTION后重新CREATE或者重啟 beeline 再試。這個(gè) UDF 項(xiàng)目后續(xù)很好擴(kuò)展同一套框架下可以繼續(xù)封裝字符串脫敏系列身份證、郵箱、銀行卡號、JSON 解析系列、時(shí)間處理系列打包成同一個(gè) jar注冊一批函數(shù)形成團(tuán)隊(duì)內(nèi)部的自研函數(shù)庫開發(fā)和維護(hù)成本都會(huì)明顯降下來。