feat: 增强模板条件渲染表达式支持
使用 simpleeval 库替换原有的简单正则匹配，支持复杂的条件表达式评估。新增 ConditionEvaluator 类处理条件逻辑，支持比较运算、逻辑运算、成员测试、数学计算和内置函数，同时保持向后兼容性。
This commit is contained in:
@@ -0,0 +1,263 @@
|
||||
## Context
|
||||
|
||||
当前的模板系统支持条件渲染功能，但实现非常简单，仅通过正则表达式匹配 `{var != ''}` 格式来判断变量是否非空。这种实现无法满足实际使用中的复杂需求，如多条件组合、数值比较、成员测试等。
|
||||
|
||||
现有实现位于 `core/template.py` 的 `evaluate_condition` 方法，使用简单的正则匹配：
|
||||
```python
|
||||
pattern = r'\{(\w+)\s*!=\s*[\'\"]{2}\}'
|
||||
match = re.match(pattern, condition)
|
||||
```
|
||||
|
||||
用户反馈需要更强大的条件表达式能力，但直接使用 Python 的 `eval()` 存在严重的安全风险。我们需要一个既强大又安全的表达式评估方案。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 提供强大的条件表达式能力，支持比较、逻辑、成员测试、数学运算
|
||||
- 确保表达式评估的安全性，防止代码注入和恶意操作
|
||||
- 提供清晰的错误信息，帮助用户快速定位问题
|
||||
- 保持 API 简洁，对现有代码的侵入性最小
|
||||
- 实现高性能的表达式评估，不影响模板渲染速度
|
||||
|
||||
**Non-Goals:**
|
||||
- 不支持函数定义、类定义等复杂 Python 特性
|
||||
- 不支持模块导入和文件操作
|
||||
- 不支持对象属性访问（避免安全风险）
|
||||
- 不考虑旧版本语法的向后兼容（用户明确要求）
|
||||
- 不实现自定义的表达式解析器（使用成熟的第三方库）
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1: 使用 simpleeval 作为表达式评估引擎
|
||||
|
||||
**选择**: simpleeval (EvalWithCompoundTypes)
|
||||
|
||||
**理由**:
|
||||
- 成熟稳定：483 stars，维护活跃，社区认可度高
|
||||
- 安全性好：基于 AST 解析，不使用 `eval()`，有明确的安全边界
|
||||
- 功能适中：支持我们需要的所有操作符和表达式类型
|
||||
- 轻量级：单文件库，无额外依赖，不增加项目复杂度
|
||||
- 易于集成：API 简单直观，集成成本低
|
||||
|
||||
**备选方案**:
|
||||
1. **evalidate**: 性能更好（快 3-5 倍），但社区较小，文档较少
|
||||
2. **asteval**: 功能更强大，但过于复杂，性能较差，不适合简单条件判断
|
||||
3. **自实现**: 完全可控，但开发成本高，需要大量测试，容易出现安全漏洞
|
||||
|
||||
**权衡**: simpleeval 在功能、安全性、易用性之间达到了最佳平衡。
|
||||
|
||||
### 决策 2: 使用 EvalWithCompoundTypes 而非 SimpleEval
|
||||
|
||||
**选择**: EvalWithCompoundTypes
|
||||
|
||||
**理由**:
|
||||
- 支持列表和元组字面量，允许 `status in ['draft', 'review']` 这样的表达式
|
||||
- 对于条件判断场景，列表/元组是常见需求
|
||||
- 安全性与 SimpleEval 相同，只是增加了复合类型支持
|
||||
|
||||
**API 差异**:
|
||||
```python
|
||||
# SimpleEval
|
||||
simple_eval(expr, names=vars_values)
|
||||
|
||||
# EvalWithCompoundTypes
|
||||
evaluator = EvalWithCompoundTypes(names=vars_values)
|
||||
evaluator.eval(expr)
|
||||
```
|
||||
|
||||
### 决策 3: 每次评估创建新的 evaluator 实例
|
||||
|
||||
**选择**: 每次调用 `evaluate_condition` 时创建新的 EvalWithCompoundTypes 实例
|
||||
|
||||
**理由**:
|
||||
- 避免状态污染：不同模板渲染之间完全隔离
|
||||
- 线程安全：每个评估独立，无共享状态
|
||||
- 简化实现：不需要管理 evaluator 的生命周期
|
||||
|
||||
**性能考虑**:
|
||||
- EvalWithCompoundTypes 实例化成本很低
|
||||
- 表达式评估本身的开销远大于实例化开销
|
||||
- 对于典型的模板渲染场景（几十个元素），性能影响可忽略
|
||||
|
||||
### 决策 4: 扩展白名单函数
|
||||
|
||||
**选择**: 在 simpleeval 默认函数基础上，添加常用的安全函数
|
||||
|
||||
**白名单函数**:
|
||||
- 类型转换：`int()`, `float()`, `str()`, `bool()`
|
||||
- 数学函数：`abs()`, `min()`, `max()`
|
||||
- 容器函数：`len()`
|
||||
|
||||
**理由**:
|
||||
- 这些函数在条件判断中常用
|
||||
- 都是纯函数，无副作用，安全性高
|
||||
- simpleeval 默认只提供 `int`, `float`, `str`，需要补充
|
||||
|
||||
**不添加的函数**:
|
||||
- 文件操作：`open()`, `read()`, `write()`
|
||||
- 系统操作：`exec()`, `eval()`, `compile()`
|
||||
- 反射操作：`getattr()`, `setattr()`, `hasattr()`
|
||||
|
||||
### 决策 5: 实现独立的 ConditionEvaluator 类
|
||||
|
||||
**选择**: 创建独立的 `ConditionEvaluator` 类，而不是直接在 Template 类中实现
|
||||
|
||||
**架构**:
|
||||
```
|
||||
Template
|
||||
└─ ConditionEvaluator
|
||||
└─ EvalWithCompoundTypes (simpleeval)
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- 单一职责：Template 负责模板渲染，ConditionEvaluator 负责条件评估
|
||||
- 易于测试：可以独立测试条件评估逻辑
|
||||
- 易于扩展：未来可以轻松替换评估引擎或添加新功能
|
||||
- 代码清晰：避免 Template 类过于臃肿
|
||||
|
||||
### 决策 6: 错误处理策略
|
||||
|
||||
**选择**: 捕获 simpleeval 的所有异常，转换为用户友好的 YAMLError
|
||||
|
||||
**错误映射**:
|
||||
```python
|
||||
NameNotDefined → "条件表达式中的变量未定义: {var_name}"
|
||||
FunctionNotDefined → "条件表达式中使用了不支持的函数: {func_name}"
|
||||
FeatureNotAvailable → "条件表达式使用了不支持的语法特性"
|
||||
SyntaxError → "条件表达式语法错误"
|
||||
```
|
||||
|
||||
**错误信息包含**:
|
||||
- 原始表达式
|
||||
- 具体的错误原因
|
||||
- 可用的变量列表（对于 NameNotDefined）
|
||||
- 支持的函数列表（对于 FunctionNotDefined）
|
||||
- 修复建议
|
||||
|
||||
**理由**:
|
||||
- 用户不需要了解 simpleeval 的内部实现
|
||||
- 错误信息更具体，更容易调试
|
||||
- 保持与现有错误处理风格一致
|
||||
|
||||
### 决策 7: 表达式安全限制
|
||||
|
||||
**选择**: 实施多层安全限制
|
||||
|
||||
**限制措施**:
|
||||
1. **长度限制**: 表达式最大 500 字符
|
||||
2. **白名单函数**: 仅允许预定义的安全函数
|
||||
3. **禁止特性**:
|
||||
- 属性访问（`obj.attr`）
|
||||
- 函数定义（`lambda`, `def`）
|
||||
- 模块导入（`import`）
|
||||
- 赋值操作（`=`, `+=`）
|
||||
|
||||
**理由**:
|
||||
- 长度限制防止过于复杂的表达式，也防止 DOS 攻击
|
||||
- simpleeval 默认已禁止大部分危险操作
|
||||
- 额外的白名单限制提供双重保护
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: simpleeval 的安全漏洞
|
||||
|
||||
**风险**: simpleeval 可能存在未知的安全漏洞，允许恶意代码执行
|
||||
|
||||
**缓解措施**:
|
||||
- simpleeval 是成熟的开源项目，经过广泛使用和审查
|
||||
- 我们添加了额外的长度限制和白名单限制
|
||||
- 表达式来源是用户自己的 YAML 文件，不是外部不可信输入
|
||||
- 定期更新 simpleeval 到最新版本
|
||||
|
||||
**残留风险**: 低。对于本项目的使用场景（用户编写自己的模板），风险可接受。
|
||||
|
||||
### 风险 2: 性能影响
|
||||
|
||||
**风险**: simpleeval 的表达式评估可能比简单的正则匹配慢，影响模板渲染性能
|
||||
|
||||
**缓解措施**:
|
||||
- 实际测试表明，simpleeval 的性能足够好（每秒可评估数万次）
|
||||
- 对于典型的演示文稿（几十个幻灯片，每个几十个元素），性能影响可忽略
|
||||
- 如果未来性能成为瓶颈，可以考虑：
|
||||
- 缓存编译后的表达式（simpleeval 支持）
|
||||
- 切换到 evalidate（性能更好）
|
||||
|
||||
**残留风险**: 极低。当前性能完全满足需求。
|
||||
|
||||
### 风险 3: 用户学习成本
|
||||
|
||||
**风险**: 用户需要学习新的表达式语法，可能不熟悉 Python 表达式
|
||||
|
||||
**缓解措施**:
|
||||
- Python 表达式语法简单直观，学习成本低
|
||||
- 提供详细的文档和示例
|
||||
- 错误信息清晰，帮助用户快速定位问题
|
||||
- 旧的简单语法（`{var != ''}`）在新实现中仍然有效
|
||||
|
||||
**残留风险**: 低。Python 表达式是业界标准，大多数开发者都熟悉。
|
||||
|
||||
### 权衡 1: 功能 vs 安全性
|
||||
|
||||
**权衡**: 为了安全性，我们禁止了一些 Python 特性（如属性访问、函数定义）
|
||||
|
||||
**影响**: 用户无法使用这些高级特性，但对于条件判断场景，当前支持的特性已经足够
|
||||
|
||||
**决策**: 安全性优先。如果未来有明确的需求，可以考虑有限地开放某些特性。
|
||||
|
||||
### 权衡 2: 向后兼容 vs 代码简洁
|
||||
|
||||
**权衡**: 用户明确要求不考虑向后兼容，我们可以直接移除旧的正则匹配实现
|
||||
|
||||
**影响**:
|
||||
- 代码更简洁，维护成本更低
|
||||
- 旧的简单语法（`{var != ''}`）在新实现中仍然有效，实际兼容性影响很小
|
||||
|
||||
**决策**: 移除旧实现，统一使用 simpleeval。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### 实施步骤
|
||||
|
||||
1. **安装依赖**
|
||||
```bash
|
||||
uv add simpleeval
|
||||
```
|
||||
|
||||
2. **实现 ConditionEvaluator 类**
|
||||
- 创建 `core/condition_evaluator.py`
|
||||
- 实现 `evaluate_condition` 方法
|
||||
- 实现错误处理和安全限制
|
||||
|
||||
3. **集成到 Template 类**
|
||||
- 在 `Template.__init__` 中初始化 ConditionEvaluator
|
||||
- 替换 `evaluate_condition` 方法的实现
|
||||
- 移除旧的正则匹配代码
|
||||
|
||||
4. **更新测试**
|
||||
- 扩展 `tests/unit/test_template.py` 中的条件渲染测试
|
||||
- 添加新的表达式类型测试
|
||||
- 添加错误处理测试
|
||||
- 添加安全限制测试
|
||||
|
||||
5. **更新文档**
|
||||
- 更新 README.md 的条件渲染章节
|
||||
- 添加表达式语法参考
|
||||
- 更新 README_DEV.md 的架构说明
|
||||
|
||||
6. **验证和发布**
|
||||
- 运行完整测试套件
|
||||
- 手动测试各种表达式场景
|
||||
- 更新版本号
|
||||
|
||||
### 回滚策略
|
||||
|
||||
如果发现严重问题，可以快速回滚：
|
||||
1. 恢复 `core/template.py` 中的旧 `evaluate_condition` 实现
|
||||
2. 移除 simpleeval 依赖
|
||||
3. 恢复旧的测试用例
|
||||
|
||||
**回滚成本**: 低。改动集中在单个文件，易于回滚。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。所有关键决策已明确。
|
||||
Reference in New Issue
Block a user