21-expression-parser

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

⭐2.5kstars🔀514forks📁View on GitHub🕐Updated Jan 9, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive guide and implementation framework for a high-performance expression parser. It enables developers to handle variable interpolation, evaluate complex conditional logic, and extend system capabilities with custom functions, all within a secure and cached environment. It is particularly optimized for CI/CD pipelines, dynamic configuration engines, and scenarios requiring sandboxed execution of user-defined logic.

Use Cases

  • Dynamic Pipeline Control: Implementing conditional logic in CI/CD workflows to determine execution paths based on branch names, tags, or environment variables.
  • Automated Template Processing: Handling complex variable substitution and string interpolation within configuration files or deployment manifests.
  • Extensible Rule Engines: Building custom business rules or evaluation engines by extending the parser with domain-specific functions.
  • Secure Sandbox Execution: Safely evaluating user-provided expressions using syntax validation and security sandboxing to prevent unauthorized code execution.
  • Performance-Critical Parsing: Utilizing expression caching and optimized tree structures to handle high-frequency calculation tasks efficiently.
name21-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/