1. 先掂量值不值得写：UDF的三种典型场景和两条红线
我最早产生写UDF的念头，是在处理一批埋点查询的时候。业务方要看“用户从哪个按钮点进了详情页”，这个按钮路径散落在URL参数里，不同版本App的参数名还不一样。当时我硬生生用一串regexp_extract加split_part叠了五六层函数，勉强写出一条SQL，但看着那几十行嵌套逻辑，心里很清楚：下次埋点格式一变，这SQL就废了；换个人来维护，大概率也读不懂。这才是我认真考虑开发Presto UDF的真实出发点——不是炫技，是被复杂SQL逼到墙角了。
在动手之前，得先分清什么场景值得写UDF，什么场景纯粹是自我感动。我自己的判断标准很简单：要么SQL写不出来，要么写出来没法维护，而且要复用的频率足够高。满足这两条，花半天时间开发一个函数是划算的。
1.1 什么时候该自己写UDF
从实际业务看，最能发挥UDF价值的主要是下面三类场景。
第一类是复杂字符串处理。这是我见过最多的需求，包括URL解析、日志字段特征提取、JSON里嵌套结构的二次加工、特殊编码的还原等。Presto的字符串函数虽然强，但针对某个业务埋点格式做定向提取时，往往需要组合五六个函数，出错率高，调试又麻烦。把这段逻辑封装成一个有业务含义的函数，比如myshop_url_param(url, 'channel')，语义一下就清晰了。
第二类是算法或数学计算。比如地理位置的距离计算、经纬度与行政区划的匹配、业务自定义的评分公式。这类逻辑要么SQL表达太笨拙，要么涉及第三方库（像空间计算或者相似度算法），在SQL层面硬写基本不可行，而UDF里可以自由引入Java生态的成熟类库。
第三类是敏感数据脱敏。很多团队有统一的脱敏规则：手机号中间四位打码、身份证保留前六后四、个人信息做哈希加盐。这个逻辑如果散布在每一条业务SQL里，很难保证口径一致，也容易漏改。做成一个公共脱敏函数，所有查询统一调用，口径自然收敛。
1.2 两条红线：场景不合适就别硬写
踩过不少坑之后，我给自己定了两条红线。
第一条：能用内置函数组合解决的问题，不要轻易写UDF。有些同事一遇到复杂需求就想着写Java代码，但Presto自身的函数体系更新很快，经常一个需求翻一翻文档，发现新版引擎已经内置了同样能力的函数，或者一个WITH子句加窗口函数就能优雅解决。为了一个小需求引入一个需要维护的Java模块，后续还得走打包、部署、重启的流程，代价远超收益。
第二条：不要在UDF里试图做“业务全局状态管理”。Presto的UDF是无状态的，每个worker上多个线程并发执行，函数体不能依赖跨调用共享的可变状态。有人试图用UDF做计数器、做批内缓存、甚至直接查外部接口，这些用法我后文会重点讲，基本都会在线上炸出问题。
用一句话总结我现在的习惯：先试着用纯SQL把需求边界摸清楚，再决定要不要投入UDF开发。纯SQL写出来虽然丑，但能帮你确认业务规则和边界条件，后面写函数时思路会清晰很多。
2. 从零搭工程：注解驱动的开发流程与部署到集群的完整链路
确认了需求值得做UDF之后，开发环节反而比较顺手。Presto的UDF本质上就是一个Java工程，核心是用SPI提供的一套注解把普通Java方法暴露成SQL函数。整体开发流程拆开看，其实就四步：建工程、写函数、注册插件、部署验证。
但这里有个很容易被网上教程带偏的点：很多人以为只要在一个类上写了@ScalarFunction注解，编译打包丢进插件目录就能用。这是错的。Presto加载UDF走的是Java标准的ServiceLoader机制，你必须在META-INF/services里声明插件入口，否则函数永远不会被注册。这个坑我亲眼见过好几个同事踩过，函数类写了，jar也放进去了，SHOW FUNCTIONS里就是查不到，最后排查半天发现是少了Plugin接口的实现类。
2.1 Maven工程里的关键依赖
先看工程基础配置。我一般用一个干净的Maven项目，只保留核心依赖：
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.source>8</maven.compiler.source> <maven.compiler.target>8</maven.compiler.target> </properties> <dependencies> <dependency> <groupId>io.prestosql</groupId> <artifactId>presto-spi</artifactId> <version>313</version> <scope>provided</scope> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>29.0-jre</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.30</version> <scope>provided</scope> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>4.13.1</version> <scope>test</scope> </dependency> </dependencies>这里提醒一个关键点：presto-spi的scope必须是provided。我见过有人图省事把scope写成默认的compile，最后打出来的jar接近几十MB，什么Guava、Jackson、Netty全打进去了，不仅部署时体积大，还容易跟Presto运行时自带的类冲突，典型的NoSuchMethodError就是这么来的。
版本号方面，我上面的313对应的是老的PrestoSQL分支；如果你的集群用的是Trino，那么依赖要换成：
<dependency> <groupId>io.trino</groupId> <artifactId>trino-spi</artifactId> <version>400</version> <scope>provided</scope> </dependency>这个差异直接决定后面接口类要引哪个包名，别混着用，很容易出现ClassNotFoundException。
2.2 会被很多人漏掉的Plugin入口
现在写函数本体。拿最简单的加法函数举例，主要是为了看清注解结构：
package com.example.udf; import io.prestosql.spi.function.Description; import io.prestosql.spi.function.ScalarFunction; import io.prestosql.spi.function.SqlType; import io.prestosql.spi.type.StandardTypes; public class MyMathFunctions { private MyMathFunctions() { } @ScalarFunction("myshop_add") @Description("Adds two BIGINT values") @SqlType(StandardTypes.BIGINT) public static long add( @SqlType(StandardTypes.BIGINT) long left, @SqlType(StandardTypes.BIGINT) long right) { return left + right; } }然后必须配一个Plugin实现类：
package com.example.udf; import com.google.common.collect.ImmutableSet; import io.prestosql.spi.Plugin; import java.util.Set; public class ExampleUdfPlugin implements Plugin { @Override public Set<Class<?>> getFunctions() { return ImmutableSet.of(MyMathFunctions.class); } }接着在src/main/resources/META-INF/services/目录下创建一个文件名是io.prestosql.spi.Plugin的文本文件，内容写插件类的全限定名：
com.example.udf.ExampleUdfPlugin如果是Trino引擎，文件名要改成io.trino.spi.Plugin。
这一步做完，函数才算真正被“接”到了引擎里。@ScalarFunction负责把Java方法标记为SQL函数，Plugin.getFunctions()负责告诉Presto要加载哪些函数类，ServiceLoader文件则是Java层面动态发现的入口，三件事缺一不可。
2.3 打包、部署与验证的完整链路
依次跑普通的Maven命令：
mvn clean package -DskipTests打包产物是一个依赖精简过的jar。如果函数逻辑里引用了第三方库（例如要算地理位置距离，引了空间计算库），就需要在pom.xml里配maven-shade-plugin，把依赖合并进最终jar，但要注意排除掉provided的那些引擎自带类库。
部署路径不复杂，但有几个细节容易被忽视：
- 在Presto安装目录的
plugin下建一个独立子目录，比如plugin/example-udf/。每个插件独占一个子目录，尽量不要把多个jar直接平铺在plugin根目录，Presto扫描插件时是按子目录加载classpath的。 - 把打好的jar复制进去，重启coordinator和所有worker。UDF是无状态的，所以集群里每台节点的
plugin目录下都得放同一份jar。 - 重启后通过
SHOW FUNCTIONS LIKE 'myshop_%'确认函数是否注册成功。如果查不到，去var/log/server.log看有没有插件加载阶段的错误堆栈。
我至今记得第一次部署时的教训：函数在测试集群跑得好好的，上生产集群却查不到。排查半天发现生产的Presto版本旧了半年，SPI接口的包名和返回值签名对不上，插件加载被静默跳过。所以做这类东西之前，最好先在生产环境确认一下SELECT version()的版本，再用对应版本的spi依赖重新编译，不要想当然地认为“能跑就行”。
3. 实战：一个按埋点格式解析URL参数的UDF是怎么长出来的
光讲理论没有感觉，我把之前做过的一个真实需求完整复盘一遍。需求是这样的：业务方想知道用户在落地页点了哪个活动模块，这个信息挂在页面URL的module_id参数上。埋点系统输出的URL长这样：
https://m.example.com/path/detail?module_id=home_banner_01&from=feed&trace_id=abc123当时最折磨人的是，URL里各个参数的顺序和编码格式在不同版本App里还不一样，有的客户端会把参数值做URL编码，中文变成%E4%B8%AD%E6%96%87，直接截取肯定不行。
3.1 需求边界：先看纯SQL能不能扛住
动手前我照例先把纯SQL方案写出来试了试，大概长这样：
SELECT CASE WHEN strpos(url, 'module_id=') = 0 THEN NULL ELSE url_decode( split_part( split_part(url, '?', 2), '&', 1 ) ) END AS module_id FROM page_views写完之后发现几个硬伤：module_id不一定排在第一个参数，用split_part(..., '&', 1)截取的策略非常脆弱；考虑参数顺序要再嵌一层正则；URL编码、空参数、重复key都得处理。SQL组合已经不太行了。于是开始写函数。
3.2 编写函数体：解析逻辑和边界处理
核心逻辑其实不复杂，关键是边界要做到位。先做一个严格的解析器，而不是简单字符串截取：
package com.example.udf; import io.prestosql.spi.function.Description; import io.prestosql.spi.function.ScalarFunction; import io.prestosql.spi.function.SqlType; import io.prestosql.spi.type.StandardTypes; import java.io.UnsupportedEncodingException; import java.net.URLDecoder; public class UrlFunctions { private UrlFunctions() { } @ScalarFunction("myshop_url_param") @Description("Extracts the value of the first query parameter with the given key from a URL") @SqlType(StandardTypes.VARCHAR) public static String extractUrlParam( @SqlType(StandardTypes.VARCHAR) String url, @SqlType(StandardTypes.VARCHAR) String key) { if (url == null || key == null || key.isEmpty()) { return null; } int queryStart = url.indexOf('?'); if (queryStart < 0 || queryStart == url.length() - 1) { return null; } String query = url.substring(queryStart + 1); for (String pair : query.split("&")) { int eqIndex = pair.indexOf('='); if (eqIndex <= 0) { continue; } String name = pair.substring(0, eqIndex); String value = pair.substring(eqIndex + 1); if (name.equals(key)) { return decode(value); } } return null; } private static String decode(String value) { try { return URLDecoder.decode(value, "UTF-8"); } catch (UnsupportedEncodingException | IllegalArgumentException e) { return value; } } }有几个边界条件我特意做了防御：
- URL里没有
?，或者?后是空的，直接返回NULL。 - 单个参数对里没有
=，说明是个无值的标志位参数，跳过。 - 参数名用精确匹配，不要用
contains，否则module_id_2会被错误命中。 - 解码失败时保留原始值，不要抛异常把整个查询搞挂。
- 重复key只取第一个，如果业务上需要取全部，就要改成返回数组类型，复杂度会上升一个级别。
3.3 验证方法：从单测到集群里的SQL查询
开发阶段的验证分两层。第一层是纯JUnit单测，直接把静态方法当普通Java方法测：
package com.example.udf; import org.junit.Test; import static org.junit.Assert.assertEquals; import static org.junit.Assert.assertNull; public class UrlFunctionsTest { @Test public void testExtractUrlParam() { String url = "https://m.example.com/path/detail?module_id=home_banner_01&from=feed"; assertEquals("home_banner_01", UrlFunctions.extractUrlParam(url, "module_id")); assertEquals("feed", UrlFunctions.extractUrlParam(url, "from")); assertNull(UrlFunctions.extractUrlParam(url, "not_exists")); assertNull(UrlFunctions.extractUrlParam(null, "module_id")); } @Test public void testExtractUrlParamWithEncoding() { String url = "https://m.example.com/path/detail?module_id=%E4%B8%AD%E6%96%87"; assertEquals("中文", UrlFunctions.extractUrlParam(url, "module_id")); } }单测能保证逻辑正确性，但UDF在Presto里的实际行为（类型映射、NULL处理、并发调用）还是要靠引擎验证。最朴素的办法是部署完以后，直接在客户端执行：
SELECT myshop_url_param( 'https://m.example.com/path/detail?module_id=home_banner_01&from=feed', 'module_id' );如果出来预期值，再用真实的埋点表跑几个抽样查询，跟手工统计的结果对一下，确认无异常才放开给业务用。这套“单测+部署验证+抽样核对”的流程，是我每次上线UDF都走的固定步骤，能挡住绝大多数低级问题。
4. 最容易翻车的地方：空值语义、类型匹配和版本裂谷
老实说，函数逻辑本身写起来不难，真正让人头大的是Presto框架层面的各种隐晦规则。这一章我把这几年踩过、也帮别人排查过的几类问题集中梳理一下，每一个都是线上真实闻过味的。
4.1 空值与NULL语义：Presto框架帮你做的两件事
这是最容易踩的坑，也是最多人一开始没意识到的。Presto对UDF的NULL处理有一套默认规则：如果某个参数被声明为“非Nullable”，而查询过程中传入的值是NULL，那么Presto根本不会调用你的函数体，而是直接返回NULL。
这意味着，像我在第三章写的extractUrlParam，如果入参url恰好是NULL，函数体里那段if (url == null)的防御代码其实永远走不到，因为框架在入口处就拦住了。
那什么时候函数体会收到NULL？只有你在参数上显式标注@SqlNullable注解。看下面这个对比：
| 参数声明方式 | 传入NULL时函数是否被调用 |
|---|---|
@SqlType(StandardTypes.VARCHAR) String url | 否，直接返回NULL |
@SqlNullable @SqlType(StandardTypes.VARCHAR) String url | 是，函数体自行处理 |
我见过不少函数因为漏了@SqlNullable，导致业务上明明期望“参数为空时返回默认值”，实际却返回了NULL，查了半天还以为函数写错了。这里我的建议是：除非确实需要在函数体内区分“NULL”和“空字符串”，否则不要给参数加@SqlNullable，让框架帮你处理NULL，函数体反而更简单、更安全。
4.2 类型映射：Java类型和SQL类型的对应关系
Presto的类型系统比Java复杂，注册函数时用@SqlType注解声明类型，框架会做一层映射。常见的对应关系大概是这样的：
| SQL类型 | Java参数类型 | 返回类型写法 |
|---|---|---|
BIGINT | long | StandardTypes.BIGINT |
DOUBLE | double | StandardTypes.DOUBLE |
BOOLEAN | boolean | StandardTypes.BOOLEAN |
VARCHAR | String | StandardTypes.VARCHAR |
DATE | long（Epoch Day） | StandardTypes.DATE |
TIMESTAMP | long（毫秒） | StandardTypes.TIMESTAMP |
这里有两个特别容易出问题的细节。一个是DATE和TIMESTAMP：Java里不会收到java.time.LocalDate，而是收到long，含义分别是“相对于Epoch的日期偏移量”和“自Epoch的毫秒数”。不了解这个规则的人，写出来的函数日期永远不对。
另一个是函数重载。同一个函数名可以注册多个不同参数签名的方法，比如myshop_add(BIGINT, BIGINT)和myshop_add(DOUBLE, DOUBLE)两个方法可以并存。但注意，Presto在SQL执行时做类型推断，1 + 2.5这种混合类型的调用可能会因为找不到适合的重载而报错，需要在函数里多做几个重载版本兜底。我在做数值类函数时，一般会把BIGINT和DOUBLE两个版本都写上，避免调用方被类型匹配卡住。
4.3 包名冲突与日志定位
UDF运行在Presto的classpath里，如果插件jar里带着引擎自带的类，轻则加载到旧版本，重则直接抛LinkageError。最常见的冲突来源是Guava、Jackson和Netty。我的经验是：凡是presto-spi已经提供的依赖，一律在pom里标成provided或使用shade插件时显式排除。判断冲突的方法也简单，部署后如果日志里出现NoSuchMethodError、ClassCastException且堆栈指向某个通用类，优先怀疑插件jar里嵌入了重复依赖。
至于日志，UDF代码里直接写System.out.println大概率是看不到输出的，它在Presto的stdout里而不在server.log。别问我怎么知道的。想正经打日志，就用slf4j的Logger，注意在pom中也是provided依赖。实际排查时，用日志关键字在var/log/server.log里过滤就能看到。这一步看着不起眼，但真的能省下大把排查时间。
4.4 版本裂谷：Presto与Trino的SPI差异
很多线上集群还在用PrestoSQL旧版本，而社区新版本已经迁移到Trino组织下了。这两个分支的SPI包名不一样：io.prestosql.spivsio.trino.spi，不只是包名，部分注解的元数据属性也有调整。最稳妥的做法是：在写代码之前，先确认目标集群的具体版本，照着那个版本的spi写，不要想当然沿用网上最新教程。
如果有多套集群要同时支持，就得维护两个分支或者用Maven profile按环境切换依赖。不用我多说，这是维护成本的大头，所以团队里最好尽早把引擎版本统一。
5. 性能与稳定性：让UDF在生产环境里跑得又快又稳
UDF能不能在线上扛住，比的不是单次执行的速度，而是在数百万行数据上并发执行时的总体表现。这一章的经验，都是我在压测和故障复盘里一点一点攒出来的。
5.1 昂贵对象只初始化一次
一个最常见的性能陷阱：在函数体内部创建昂贵对象，例如每次调用都编译一次正则表达式。像Pattern.compile("...")这种操作在小数据量上无感，但在几亿行的表上跑，JIT都救不了你，编译开销会被放大到分钟级。
正确的做法是把不可变对象放到static final字段里，类加载时只初始化一次，所有线程复用。正则、DateTimeFormatter、HashMap模板都适合这样干。比如：
private static final Pattern MODULE_PATTERN = Pattern.compile("module_id=([^&]+)");这一点在第三章的URL解析函数里也适用，如果某个函数内部频繁用正则找参数，单独把它抽成static final，收益非常可观。
5.2 函数体内不要做远程IO和状态存储
这是我最想强调的一条。写UDF的时候，默认禁止在函数体里做任何远程调用，包括查Redis、调HTTP接口、读写外部存储。听起来离谱，但我确实见过有团队真想这么干——结果就是Presto扫描百万行时，每个worker线程都在等网络响应，整个集群被一个UDF拖垮，查询超时、内存暴涨、节点一堆报错。
UDF应该是一个“给定输入，立即算出结果”的纯函数。如果确实需要关联外部数据，正确的姿势是先把外部数据做成Presto表，或者和维表做JOIN，让引擎的分布式能力去处理数据搬运，而不是在每个函数调用里做一次网络往返。
5.3 用基准测试观察调用开销
我习惯在函数开发完成后，构造一张足够大的数据表做一次基准测试。比如生成1000万行的临时表：
SELECT myshop_url_param(url, 'module_id') FROM ( SELECT 'https://m.example.com/path/detail?module_id=home_banner_01&from=feed&trace_id=abc' AS url FROM UNNEST(SEQUENCE(1, 10000000)) AS t(id) ) tmp观察查询耗时和集群资源占用。如果执行时间明显异常，先怀疑是不是函数内部有重量级操作，再用EXPLAIN ANALYZE看每个算子的耗时分布。
还有一个容易被忽视的点：UDF的入参如果是一个很长的VARCHAR，每次传入都会产生新的Java字符串，函数体里再频繁做substring、split，对象创建十分频繁。对这种热函数，可以考虑直接使用Block接口按需取数据，能减少很多不必要的字符串转换，但这部分API用起来更底层，一般业务函数不建议一上来就这么干，存在性能瓶颈再去优化。
6. 从单函数到函数库：团队里沉淀UDF工程化的经验
开发几个函数不是终点，真正让我觉得靠谱的，是把UDF当成一个独立工程项目来维护。走到这一步，很多方法和习惯就不一样了。
6.1 命名规范与函数文档
自研函数越来越多以后，第一件事就是定命名规则。我强烈建议所有自研UDF统一加业务前缀，比如myshop_、dw_、app_，不要裸起一个url_param之类的函数名。因为Presto内置函数和后续升级可能引入新函数，无前缀的函数名非常容易撞车；撞上之后要么报“函数已存在”，要么被解析到完全不同的实现，排查成本极其高昂。
同时，每个函数都要有配套文档，至少覆盖：函数名称、参数类型、返回值类型、NULL语义、示例SQL。我见过太多内部函数库最后变成了谁也看不懂的黑盒，想用不敢用，想改不敢改。用Markdown表格维护一份函数清单，放在工程仓库的README里，比什么都管用。
6.2 质量保障与发布流程
Java工程该有的质量保障，UDF项目一样都不能少。单测覆盖是底线，至少要把主要分支和边界条件测到。我见过一些团队把函数写完就上线，结果某个分支逻辑在特定数据下炸出NullPointerException，直接把整个查询搞失败，这种事故完全可以通过单测避免。
发布流程上，我个人的习惯是走一条严格的命令链：本地单测 → 打包 → 部署到测试集群 → 用真实SQL验证 → 灰度部署到部分节点 → 全量部署。整个过程用脚本固化，尽量别靠人工手工登录服务器放jar。因为Presto的插件加载是启动时扫描的，部署后必须重启节点，所以最好把jar的发布和节点重启编排到同一个自动化流程里，避免有人忘了重启导致“两个集群版本不一致”的隐患。
6.3 遇到复杂聚合逻辑：先算清楚要不要UDAF
经常会有人问：我要按用户分组后再做自定义聚合，单行UDF搞不定怎么办？这就需要UDAF（自定义聚合函数）。UDAF比UDF复杂一个量级，要自己管理聚合状态（AccumulatorState），还要实现状态序列化和合并逻辑，开发、调试成本都明显更高。
我的建议是：先用Presto现有的聚合函数和窗口函数能不能组合出需求，比如array_agg加Lambda函数能覆盖很多场景。确认实在搞不定再上UDAF，而且UDAF最好由对Presto SPI比较熟悉的人来写，不建议新手一上来就挑战这个。我见过不少团队在UDAF上投入巨大，最后发现需求变了，整个State设计全废，那感觉实在不好受。
经历过完整的开发、上线和运维周期之后，我最大的体会是：UDF不是越多越好，而是正好补在痛点上。每次新需求来时，我仍然会先老老实实写一遍纯SQL版本，试图理解业务规则和边界条件，再决定要不要动Java代码。把函数库控制在一个可维护的规模内，每一个新函数都有清晰的文档、单测和使用场景，这比盲目堆几十个“看起来高级”的函数有价值得多。下一次如果你的查询也开始嵌套五六层正则了，不妨停下来想想：这个逻辑，是不是该沉淀成一个有名字、有文档、有测试的函数了？
