RLei.RulesJint 1.0.2

Rules.Jint

一个基于 Jint（.NET 的 JavaScript 解释器）封装的规则引擎库，支持表达式缓存、异步求值和 55 个全局 JS 辅助函数。

功能特性

• 表达式预编译缓存 — 基于 ConcurrentDictionary 缓存 Prepared<Script>，避免重复解析
• 输入变量自动小写化 — 所有 JObject 的属性名在注入引擎时自动转为小写
• 55 个全局辅助函数 — 涵盖类型转换、字符串操作、数学运算、日期时间、集合操作、条件判断、属性检测、工具函数
• 异步求值 — 提供 EvaluateExpressionAsync 一个异步 API

快速开始

using Newtonsoft.Json.Linq;
using Rules.Jint;

var factory = new JintEngineFactory();

var expression = "iif(age >= 18, '成人', '未成年')";
var inputs = JObject.FromObject(new { age = 20 });

var result = await factory.EvaluateExpressionAsync(expression, inputs);
Console.WriteLine(result.Result); // 输出: 成人

字符串字面量 vs 变量引用

表达式中的字符串有两种含义，取决于是否使用引号：

核心原则：

• 引号 → 字符串就是它本身，不会被解析
• 无引号 → Jint 将其视为变量名/表达式，从引擎上下文中求值

如何快速识别

1. 查找引号 → 字符串字面量

   // 变量引用的具体值
   var inputs = JObject.FromObject(new { name = "Alice" });
   await Eval("str(name)");     // "Alice"
   
   // 字面量字符串，固定不变
   await Eval("str('name')");   // "name"（与上下文无关，始终返回字面字符串）
   

2. 无引号表示变量引用

   // 变量引用，可从上下文中获取值
   var inputs = JObject.FromObject(new { user = new { name = "Alice" } });
   await Eval("str(user.name)");  // "Alice"
   
   // 字面量字符串，完全保留原值
   await Eval("str('user.name')");  // "user.name"（不解析点号表示法）
   

实际应用

属性检测示例：

// 字面量用法：检查键名是否存在，而非检查值的存在性
var inputs = JObject.FromObject(new { user = new { name = "Alice", age = 30 } });
await Eval("hasProperty('user.name')", inputs);   // true - 检查是否存在 key 'user.name'
await Eval("hasProperty(user, 'name')", inputs); // true - 检查 user 对象是否存在属性 'name'

字符串操作示例：

// 字面量字符串保持原值
await Eval("str('fixed-string')");   // "fixed-string"（与上下文无关）

// 变量引用从上下文中获取值
await Eval("str(fullName)");         // 获取 fullName 变量的实际值

API

核心类

JintEngineFactory

// 创建带输入的引擎
Engine CreateEngine(JObject inputs)

// 异步求值（自动缓存表达式）
Task<ExpressionEvaluateResult> EvaluateExpressionAsync(string expression, JObject inputs)

EvaluateRequest

public record EvaluateRequest(string Expression, JObject Inputs);

ExpressionEvaluateResult

全局辅助函数

所有函数名均为 小写开头驼峰 风格，可在 JS 表达式中直接调用。

类型转换

字符串函数

数学函数

日期时间函数（16 个）

集合函数

条件函数

属性检测

用于检测对象属性和变量值的函数。

hasProperty — 属性存在检查

// 用法一：检查根上下文中是否存在属性
hasProperty('name')                    // true / false
hasProperty('user.address.city')       // 支持点号分隔的嵌套路径

// 用法二：检查指定对象是否存在属性
hasProperty(obj, 'name')               // 指定对象
hasProperty(user, 'address.city')      // 指定对象 + 嵌套路径

嵌套路径规则： 按 . 分隔逐层查找，中间任一节点缺失立即返回 false，不会抛出异常。

// 输入: { user: { name: "Alice", address: { city: "Beijing" } } }
hasProperty('user.name')                // true
hasProperty('user.address.city')        // true
hasProperty('user.address.zip')         // false (zip 不存在)
hasProperty('user.nonexistent')         // false (nonexistent 不存在)

hasValue — 值是否存在

检查值是否为非 null、非 DBNull、非空白字符串。

hasValue(name)           // 变量 name 是否有值
hasValue(user.name)      // 嵌套属性是否有值

isNotNull — 非 null 检查

检查值是否为非 null、非 DBNull。

isNotNull(name)          // 变量 name 是否非 null
isNotNull(user)          // 变量 user 是否非 null

注意： hasValue 和 isNotNull 接收的是已求值的变量，而非字符串属性名。如果要检查上下文中的某个属性值，请使用不带引号的变量引用：

// ✓ 正确：变量引用，检查 age 的值
hasValue(age)

// ✗ 错误：字符串字面量，只检查字符串 "age" 本身
hasValue('age')

工具函数

输入变量

JObject 的属性名会自动转为 小写 注入引擎，因此在表达式中应使用小写变量名。

var inputs = JObject.FromObject(new { UserName = "Alice", Age = 30 });
// 在表达式中使用: username、age
var result = await factory.EvaluateExpressionAsync("concat('Hello, ', username) + ' age: ' + str(age)", inputs);

嵌套变量

JObject 的嵌套对象会自动转为平铺的字典结构，可以通过 . 操作符访问：

var inputs = JObject.FromObject(new
{
    user = new { name = "Alice", address = new { city = "Beijing" } }
});

// 在表达式中使用:
//   user.name          → "Alice"
//   user.address.city  → "Beijing"
var result = await factory.EvaluateExpressionAsync("user.address.city === 'Beijing'", inputs);

完整示例

属性检测与条件判断

var inputs = JObject.FromObject(new
{
    user = new { name = "  Alice  ", age = 25, roles = new[] { "admin", "user" } }
});

var expression = @"
    hasProperty(user, 'name') &&       // 对象是否存在 name 属性
    hasValue(user.name) &&             // 值是否非空
    str(toLowerCase(trim(user.name))) === 'alice' &&  // 字符串处理
    user.age >= 18 &&                  // 数字比较
    arrayContains(user.roles, 'admin') // 集合包含
";
var result = await factory.EvaluateExpressionAsync(expression, inputs);
// result: true

表达式缓存

JintEngineFactory 内部使用 ConcurrentDictionary 缓存已预编译的表达式，重复表达式不会重复解析。

依赖

• Jint 4.8.0
• Newtonsoft.Json 13.0.4

NuGet

PM> Install-Package RLei.RulesJint

开源协议

MIT