在标准函数无法满足业务场景时，UDF 是常见的扩展手段。本文基于客户版实践，整理了从开发到部署的关键步骤，并附常见问题与风险提示，方便团队快速落地。
## 一、先理解原理：为什么能在观远里用 UDF？
观远 Galaxy 基于 Spark 构建，而 Spark 支持集成 Hive UDF/UDAF/UDTF。
因此，客户可将自定义 Jar 注册为 Spark SQL 函数，再在 ETL/数据集/卡片计算字段中调用。
核心注册方式类似：
```sql
CREATE TEMPORARY FUNCTION <函数名> AS '<类全名>';
```
## 二、开发阶段（客户侧）
### 1）依赖引入
建议引入：
- `org.apache.hive:hive-exec:2.3.9`
- `scope=provided`
示例：
```xml
<dependency>
<groupId>org.apache.hive</groupId>
<artifactId>hive-exec</artifactId>
<version>2.3.9</version>
<scope>provided</scope>
</dependency>
```
### 2）编写 UDF 类
继承 Hive `UDF`，在 `evaluate` 中实现业务逻辑。例如手机号脱敏：
```java
package com.guandata.udf;
import org.apache.hadoop.hive.ql.exec.UDF;
public class HiveUDFExample extends UDF {
public String evaluate(String mobile) {
if (mobile != null && mobile.length() == 11) {
return mobile.replaceAll("(\\w{3})\\w*(\\w{4})", "$1*****$2");
}
return mobile;
}
}
```
### 3）打包与自检
- 推荐 Java 11 打包（至少 Java 8）。
- 执行 `mvn clean package`。
- 发布前建议检查：
- `target/classes` 是否含目标 class。
- `jar tf` / `jar xvf` 是否能看到目标 class。
## 三、部署阶段（运维侧）
### 1）准备配置文件
准备 `udfConfig.json`：
```json
[
{
"className": "com.guandata.udf.HiveUDFExample",
"functionName": "encrypt_mobile",
"udfType": "HIVE"
}
]
```
### 2）上传文件
将以下文件上传到 Job Engine：
- UDF Jar
- `udfConfig.json`
目录建议：`/guandata-store/udf/`
### 3）修改 Job Engine 配置
在 `spark-job-engine-configmap.yaml` 的 `spark-submit` 中加入 Jar：
```bash
/opt/spark/bin/spark-submit \
--jars "/app/*.jar,/guandata-store/udf/*.jar" \
...
```
CDH Cluster 模式下还需：
- `--file /guandata-store/udf/udfConfig.json`
- `--driver-java-options "...-Dguandata.udf.config=udfConfig.json..."`
配置完成后重启 Job Engine。
## 四、上线后可用位置
重启生效后，UDF 可用于：
- ETL SQL 算子
- ETL 计算字段
- Guan-Index 数据集计算字段
- 基于 Guan-Index 的卡片计算字段
## 五、常见问题
1. 是否支持 UDF/UDAF/UDTF？
支持，但 UDAF/UDTF 对代码能力要求更高，应额外评估性能与稳定性。
2. 加密和解密能否同类注册两个函数？
通常不建议。若需要两个函数名，建议拆成两个类分别注册。
3. 上传后函数报错怎么办？
优先排查：UDF 继承规范、Java 版本、Jar 内容、json 配置、提交参数、服务重启。
4. hive-exec 冲突怎么处理？
这是依赖治理问题，需在客户侧解决，并确保与运行环境版本匹配。
## 六、风险提示（请务必确认）
UDF 确实拓展了在产品上的自由度，但因为 UDF 会把客户自己代码引入到观远产品中，这部分逻辑完全依赖于客户自己的代码水平，所以它会给整个系统在性能与安全引入一些风险，这部分风险是需要客户自己去评估和把握。
一般情况，我们并不建议 Hive 开发经验较少客户使用这个 feature。请谨慎使用。
## 七、服务边界说明
Spark UDF 功能不属于观远 Galaxy 标准合同能力，默认不在常规运维服务支持范围内（特殊约定除外）。通常仅提供 Jar 安装部署支持。
|
