21-expression-parser

表达式解析器指南,包括变量解析、条件求值、函数扩展、表达式缓存和安全沙箱。适用于实现表达式解析、变量替换、扩展函数和配置引擎。

📖 中文导读:表达式解析器指南,包括变量解析、条件求值、函数扩展、表达式缓存和安全沙箱。适用于实现表达式解析、变量替换、扩展函数和配置引擎。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: 21-expression-parser description: 表达式解析器指南,涵盖变量表达式解析、条件表达式求值、自定义函数扩展、表达式缓存、安全沙箱。当用户实现表达式解析、处理流水线变量替换、扩展表达式函数或配置表达式引擎时使用。

表达式解析器

表达式解析器指南.

触发条件

当用户需要实现条件表达式解析、变量替换、动态计算时,使用此 Skill。

ExpressionParser

class ExpressionParser private constructor() {
    companion object {
        // 创建解析树
        fun createTree(
            expression: String,
            nameValues: Iterable<NamedValueInfo>?,
            functions: Iterable<IFunctionInfo>?
        ): IExpressionNode?
        
        // 验证表达式语法
        fun validateSyntax(
            expression: String,
            context: ExecutionContext?
        ): ValidateResult
    }
}

表达式语法

# 变量引用
${{ variables.buildNo }}
${{ parameters.env }}

# 条件表达式
${{ eq(variables.branch, 'master') }}
${{ and(eq(variables.env, 'prod'), ne(variables.skip, 'true')) }}

# 内置函数
${{ contains(variables.tags, 'release') }}
${{ startsWith(variables.branch, 'feature/') }}
${{ format('{0}-{1}', variables.name, variables.version) }}

内置函数

函数 说明 示例
eq 相等 eq(a, b)
ne 不等 ne(a, b)
and 与 and(a, b)
or 或 or(a, b)
not 非 not(a)
contains 包含 contains(str, 'sub')
startsWith 前缀 startsWith(str, 'pre')
endsWith 后缀 endsWith(str, 'suf')
format 格式化 format('{0}', a)

使用示例

fun evaluateCondition(
    expression: String,
    variables: Map<String, String>
): Boolean {
    val nameValues = variables.map { (k, v) ->
        NamedValueInfo(k, ContextValueNode(v))
    }
    
    val tree = ExpressionParser.createTree(
        expression = expression,
        nameValues = nameValues,
        functions = BuiltInFunctions.all
    )
    
    val context = ExecutionContext()
    val result = tree?.evaluate(context)
    
    return result?.toBoolean() ?: false
}

// 使用
val shouldRun = evaluateCondition(
    expression = "eq(variables.env, 'prod')",
    variables = mapOf("env" to "prod")
)

变量替换

fun replaceVariables(
    template: String,
    variables: Map<String, String>
): String {
    var result = template
    variables.forEach { (key, value) ->
        result = result.replace("\${{ variables.$key }}", value)
    }
    return result
}

最佳实践

  1. 语法验证:解析前先验证语法
  2. 默认值:变量不存在时提供默认值
  3. 安全性:避免执行不可信表达式
  4. 性能:缓存解析树避免重复解析

相关文件

  • common-expression/src/main/kotlin/com/tencent/devops/common/expression/