# 函数表达式指南

本文档提供了常用函数的详细说明，包括函数定义、参数类型、功能描述及使用示例。

提示

1、函数执行失败，不会中断任务执行，函数处理的字段会被清空。任务开发阶段请留意日志确认函数处理正确。 2、配置函数表达式后，映射连线就不再生效，输出以函数的处理结果为准。

# 函数表达式

函数使用了一个高性能的表达式引擎（Aviator），支持灵活的语法和类型系统。

# 数据类型

支持以下主要数据类型：

类型	说明	示例
String	字符串类型，使用单引号或双引号	`'hello'`, `"world"`
Number	数值类型，包括整数和浮点数	`123`, `3.14`, `-456`
Boolean	布尔类型	`true`, `false`
Date	日期类型	`now()`, `dateFormat(...)` 返回值
Array	数组类型	`split('a,b,c', ',')` 返回值
Null	空值	`null`

# 基本语法

# 基本运算

算术运算：+, -, *, /, %
比较运算：==, !=, <, >, <=, >=
逻辑运算：&&, ||, !
三元运算：条件 ? 真值 : 假值

# 示例

// 数值计算
10 + 5 * 2 // 返回 20
(10 + 5) * 2 // 返回 30

// 比较运算
age > 18 && gender == 'male' // 返回 true 或 false

// 三元运算
score >= 60 ? '及格' : '不及格' // 根据条件返回不同值

// 字符串操作
name.length() > 5 ? name.substring(0, 5) : name // 字符串长度判断

# 函数表达式上下文变量

在函数表达式中，上下文变量是指在执行环境中预先定义的变量，可以直接引用，本系统中将源表所有字段插入到上下文变量中，可以直接通过字段名引用。

提示

请注意：源表中的数据置入上下文时全部转换成了字符串，若需要进行数值运算，需要使用函数将值转换成数字。

# 上下文变量类型

字段变量：来自数据源的字段
- 在表达式中可直接引用字段名
- 可通过 val(fieldName) 获取字段值
系统变量：
- now()：当前时间
- 其他全局函数返回值也可作为临时变量使用

# 上下文变量使用示例

// 假设源有字段 name, age, score
val(name) // 获取name字段值
val(age) > 18 && val(gender) == 'male' // 条件判断

// 结合函数使用
filter("val(score) >= 60") // 过滤及格数据

// 字段值处理
toUpperCase(trim(name)) // 对name字段去空格后转大写（直接引用变量名取值）

// 字段值处理
toUpperCase(trim(val(name))) // 对name字段去空格后转大写（使用val函数引用变量名取值）

// 日期字段处理
dateFormat(val(birthDate), 'yyyy-MM-dd') // 格式化出生日期

# 上下文变量作用域

每个表达式执行时都有独立的上下文环境
字段变量的作用域限于当前记录/数据行
函数调用不会改变原始上下文变量的值（函数式特性）

# 字符串类函数

# 字符串截取函数

函数名: subString(String str, int begin, int end)
参数类型: 字符类
描述: 字符串截取函数，从begin位置开始到end位置结束（从零开始，结束不包含end位置），field为要执行截取的原始串，返回，例如：String：subString('Hello world!',0,3) ,执行结果：Hel
示例:

subString('Hello world!', 6, 10) // 执行结果：worl

# 字符串转小写

函数名: toLowerCase(String str)
参数类型: 字符类
描述: 将字符串转换为小写，例如传入'HELLO'，返回'hello'
示例:

toLowerCase('HELLO') // 返回 'hello'

# 字符串转大写

函数名: toUpperCase(String str)
参数类型: 字符类
描述: 将字符串转换为大写，例如传入'hello'，返回'HELLO'
示例:

toUpperCase('hello') // 返回 'HELLO'

# 去除前后空格

函数名: trim(String str)
参数类型: 字符串类
描述: 去除字符串的前后空格
示例:

trim('  hello  ') // 返回 'hello'

# 字符串正则替换

函数名: replace(String str, String subStr|regex, String replacement)
参数类型: 字符类
描述: 字符串正则替换函数replace
示例:

replace('Hello world!', 'world', 'Lisa') // 返回 'Hello Lisa!'

# 字符串分隔

函数名: split(String str, String string|regex)
参数类型: 字符类
描述: 字符串分隔函数,regex为分割的正则规则,返回值是一个字符串数组，如果输出到数据库字符串字段，会调用toString()方法。
示例:

split('13922223333,13744445555', ',') // 返回 ['13922223333', '13744445555']

# 反转字符串

函数名: reverse(String str)
参数类型: 字符类
描述: 反转字符串，例如传入'hello'，返回'olleh'
示例:

reverse('hello') // 返回 'olleh'

# 压缩字符串

函数名: compressString(String str)
参数类型: 字符串类
描述: 压缩字符串,将字符串的前后空格,字符中的\t（制表符）,\r（回车符）,\n（换行符）字符去除。如果字符串是"NULL"或"null"返回null。
示例:

compressString(' d\tat\na ') // 返回 'data'

# 数值类函数

# 格式化数字

函数名: formatNum(Number number[, String format])
参数类型: 数值类
描述: 格式化数字,例如formatNum(1234.567, "#,###.00") → "1,234.57" formatNum(42, "000") → "042" formatNum(0.85, "0.00%") → "85.00%"
示例:

formatNum(1234.567, "#,###.00") // 返回 "1,234.57"
formatNum(42, "000") // 返回 "042"
formatNum(0.85, "0.00%") // 返回 "85.00%"

# 随机数生成

函数名: randomNum(int bound[, String format])
参数类型: 数值类
描述: 获取随机数字
示例:

randomNum(99) // 返回 0-98 之间的随机数

# 日期类函数

# 获取当前时间

函数名: now()
参数类型: 日期类
描述: 获取当前时间绝对秒。支持搭配dateFormat函数使用，例如dateFormat(now())；
示例:

now() // 返回当前时间绝对秒：1765892844766
dateFormat(now()) // 2025-12-16 21:51:09

# 日期格式化

函数名: dateFormat(String|Date|Long date [,String pattern])
参数类型: 日期类
描述: 将日期格式转化为指定日期格式的字符串,例如"yyyy-MM-dd HH:mm:ss",不传pattern，默认格式为："yyyy-MM-dd HH:mm:ss"。支持输入日期串,日期对象,绝对秒和绝对毫秒，返回值:字符串。
示例:

dateFormat(update_time, 'yyyy-MM-dd HH:mm:ss') // 返回格式化后的日期字符串

# 加解密函数

# AES加密

函数名: aes(Object content, [String seed])
参数类型: 加解密
描述: 对指定内容做aes加密，可选提供seed值
示例:

aes(name) // 使用默认seed加密
aes(name, "seed") // 使用指定seed加密

# AES解密

函数名: aesDecrypt(Object encryptedContent, [String seed])
参数类型: 加解密
描述: 对AES加密的内容进行解密，可选提供seed值
示例:

aesDecrypt(encryptedContent) // 使用默认seed解密
aesDecrypt(encryptedContent, "seed") // 使用指定seed解密

# MD5加密

函数名: md5(Object... content)
参数类型: 加解密
描述: 对指定内容拼接后生成md5值，入参支持传入多个。
示例:

md5(name, idcard) // 返回name和idcard拼接后的MD5值

# JSON处理函数

# 读取JSON值

函数名: readJSON(String json, String jsonPath)
参数类型: 字符类
描述: 通过jsonPath获取json串中的值
示例:

readJSON('{"resource":{"url":"http://127.0.0.1/img.png"}}', '$.resource.url') // 返回 'http://127.0.0.1/img.png'

# 设置JSON值

函数名: setJSON(String json, String jsonPath, Object value [, String jsonPath2, Object value2,...])
参数类型: 字符类
描述: 修改或新增json串指定jsonPath的value
示例:

setJSON('{"resource":{"name":"lisa"}}', '$.resource.name', 'james') // 返回 '{"resource":{"name":"james"}}'

# 映射函数

# 字典转换

函数名: dict(String key, String dictJson [,String defaultValue])
参数类型: 映射
描述: 字典转换,将参数key的值通过dictJson字典集,转换成对应的value。如果key不在字典中,将返回默认值 defaultValue,如果默认值没填,则原样返回原值。
示例:

dict('1', '{"1":"男","2":"女"}', '未知') // 返回 '男'

# 其他工具类函数

# 获取字段值

函数名: val(String fieldName)
参数类型: 其他
描述: 获取上下文中字段值,如果字段不存在,返回空串
示例:

val(name) // 返回 name 字段的值

# 生成UUID

函数名: uuid()
参数类型: 其他
描述: 生成一个uuid串
示例:

uuid() // 返回UUID字符串

# 下载资源

函数名: download(String url)
参数类型: 其他
描述: 下载url指向的资源,将资源进行base64编码后返回字符串
示例:

download('http://xxx.com/name.png') // 返回资源的base64编码字符串

# 数据过滤

函数名: filter(String exp)
参数类型: 其他
描述: 满足条件的数据被保留，支持逻辑运算。例如，做数据分发type等于'1'的数据才输出到目的端，filter("type == '1'")
示例:

filter("a == 1") // 返回满足条件的数据

# 函数高级用法示例

结合表示语法、数据类型和上下文变量的使用示例：

// 复杂条件判断（布尔类型）
filter("(val(age) > 18 && val(gender) == 'male') || (val(score) > 90)")

// 数值计算与格式化
formatNum(val(price) * 1.2, "#,###.00")

// 字符串操作组合
toUpperCase(trim(val(name)))

// 日期比较（日期类型）
dateFormat(now(), 'yyyy-MM-dd') == dateFormat(val(birthDate), 'yyyy-MM-dd') ? '生日' : '普通日'

// 三元运算配合函数
val(score) >= 60 ? '及格' : toUpperCase('不及格')

// JSON处理与字段结合
readJSON(val(userJson), '$.profile.name')

// 字典转换实际应用
dict(val(status), '{"1":"启用","0":"禁用"}', '未知状态')

# Aviator 内置函数（原生支持）

以下函数由 Aviator 引擎自带。

# 数学运算类

函数名	参数类型	描述	示例
`math.abs(x)`	数值	绝对值	`math.abs(-5)` → `5`
`math.sqrt(x)`	数值	平方根	`math.sqrt(16)` → `4.0`
`math.pow(base, exp)`	数值	幂运算	`math.pow(2, 3)` → `8.0`
`math.log(x)` / `log10(x)`	数值	自然对数 / 常用对数	`math.log10(100)` → `2.0`
`math.sin(x)` / `cos` / `tan`	数值	三角函数（弧度）	`math.sin(math.PI / 2)` → `1.0`
`math.asin(x)` / `acos` / `atan`	数值	反三角函数	`math.asin(1)` → `1.5708`
`math.ceil(x)` / `floor(x)` / `round(x)`	数值	取整操作	`math.round(3.6)` → `4.0`
`math.min(a, b)` / `max(a, b)`	数值	最小/最大值	`math.max(5, 10)` → `10`

常量：math.PI, math.E

# 类型转换类

函数名	参数类型	描述	示例
`string(obj)`	任意	转字符串	`string(123)` → `"123"`
`int(obj)` / `long(obj)` / `double(obj)`/	任意	转数值类型	`int("42")` → `42`
`bool(obj)`	任意	转布尔（`"0"`, `"false"`, `null` → `false`）	`bool("true")` → `true`

# 集合与序列操作

函数名	参数类型	描述	示例
`size(coll)`	Array/List/Map/String	返回长度或元素数	`size("abc")` → `3`
`contains(coll, value)`	集合、任意	是否包含某值	`contains(["a","b"], "a")` → `true`
`join(array, sep)`	数组、字符串	连接数组为字符串	`join(["x","y"], "-")` → `"x-y"`

# 通用判断

函数名	参数类型	描述	示例
`nil(obj)`	任意	判断是否为 null、空串或空集合	`nil("")` → `true` `nil(null)` → `true`

← 任务管理节点管理 →