内置SPI函数库详解：JQuick-Java Builtin工具类实战用法

前言

规则脚本里最烦人的事，是调用公共能力还要先 import、再等解析器支持。JQuick-Java 提供内置 SPI 函数库，脚本中直接以 Builtin::methodName(args) 调用，无需任何 import、无需注册------类型判断、位运算、信息脱敏、身份证识别、金融校验开箱即用。本文详解 JQuick-Java 内置 SPI 函数库的调用机制与实战用法。

核心技术原理

内置 SPI 函数库由独立仓库 jquick-transform-function 提供（依赖版本 1.4.0），JQuick-Java 的语法层内置了 BUILTIN : 'Builtin' 词法标记，文法中 primaryAtom 明确支持：

antlr 复制代码

primaryAtom
    : ...
    | BUILTIN COLON COLON methodName LPAREN argumentList? RPAREN  // Builtin::方法(参数)
    | ...
    ;

即 Builtin::xxx(...) 是语言一级语法，解析后由 JQuickJavaBuiltInFunctionContext 承载调用上下文（JContext、作用域栈、参数列表），路由到函数库执行。因此脚本内调用内置函数与调用 Java 静态方法语法一致，但省去全限定名与 import。

实战代码演示

1. 基础调用（求和）

jquick 复制代码

// 摘自 JStaticMethodInvocationTest#builtin
Builtin::sum(int:1, int:2, int:3, int:4, int:5, int:6); // 21

2. 类型判断

jquick 复制代码

boolean b1 = Builtin::isArray(listVar);    // 是否数组/集合
boolean b2 = Builtin::isBoolean(flag);     // 是否布尔

3. 位运算

jquick 复制代码

int and = Builtin::bitAnd(int:12, int:10); // 8
int or  = Builtin::bitOr(int:12, int:10);  // 14
int xor = Builtin::bitXor(int:12, int:10); // 6

4. 信息脱敏

jquick 复制代码

str card = Builtin::bankCardMask(str:"6222020202020202020");   // 银行卡脱敏
str mail = Builtin::emailMask(str:"user@example.com");         // 邮箱脱敏

5. 身份证识别

jquick 复制代码

int  age      = Builtin::idCardAge(str:"110101199001011234");       // 计算年龄
str  birthday = Builtin::idCardBirthday(str:"110101199001011234");  // 出生日期
str  gender   = Builtin::idCardGender(str:"110101199001011234");    // 性别

6. 金融校验

jquick 复制代码

boolean valid = Builtin::bankCardValidate(str:"6222020202020202020"); // Luhn 算法校验

7. 在规则函数中组合使用

jquick 复制代码

int def checkAndMask(str:cardNo) {
    boolean ok = Builtin::bankCardValidate(str:cardNo);
    if (!ok) {
        return -1;
    }
    console.log(Builtin::bankCardMask(str:cardNo));
    return 0;
}

核心技术细节解析

调用分类 ：内置函数覆盖类型判断（isArray/isBoolean）、位运算（bitAnd/bitOr/bitXor）、信息脱敏（bankCardMask/emailMask）、身份证识别（idCardAge/idCardBirthday/idCardGender）、金融校验（bankCardValidate，Luhn 算法）等。
可选参数 ：部分函数支持可选尾参，如 bankCardMask(cardNo, keepStart?, keepEnd?)、idCardAge(idCard, referenceDate?)，缺省时按内置默认规则处理。
与 Java 调用并存 ：Builtin:: 与 类名:: 在文法中并列，规则脚本内可自由混用内置函数与自定义 Java 静态方法。

常见踩坑与解决方案

拼写或大小写错误 ：Builtin 首字母大写且为语法关键字，写成 builtin:: 会解析失败。
参数类型不匹配 ：bankCardMask(str:...) 需要字符串参数，传入数字会类型转换失败，请显式 str:xxx 声明。
版本缺失 ：内置函数依赖 jquick-transform-function 依赖，Maven 引入 jquick-java 时默认传递引入，但排除该依赖后 Builtin:: 调用会找不到实现。

最佳实践

脱敏类函数优先用于日志脱敏与接口脱敏，配合黑白名单保障生产安全。
身份证、银行卡相关校验函数自带算法（如 Luhn），无需在规则内手写校验逻辑。
自定义的通用能力可参照 SPI 函数库封装为 Java 静态方法，脚本内用 类名:: 调用，保持规则脚本轻量。

总结

JQuick-Java 内置 SPI 函数库以 Builtin:: 语法提供开箱即用的公共能力，覆盖类型判断、位运算、脱敏、身份证识别与金融校验等高频场景，让规则脚本保持简洁的同时能力不减。对需要在规则内快速完成数据治理与校验的团队，这套函数库值得优先掌握。