172 lines
4.7 KiB
Markdown
172 lines
4.7 KiB
Markdown
# Python 代码规则详解
|
||
|
||
## 概述
|
||
|
||
Python 代码规则是 DDMS 合规性验证软件中最灵活的规则类型，允许使用 Python 编写复杂的验证逻辑。与其他基于JSON结构的规则不同，Python 代码规则能够实现任何自定义逻辑，如复杂的数学计算、字符串处理、条件判断等。
|
||
|
||
## 规则结构
|
||
|
||
Python 代码规则由两部分组成：
|
||
|
||
1. **元数据文件** (JSON格式)：包含规则的基本信息和配置参数
|
||
2. **代码文件** (Python格式)：包含实际的验证逻辑代码
|
||
|
||
### 元数据文件格式
|
||
|
||
```json
|
||
{
|
||
"id": "rule-id",
|
||
"name": "规则名称",
|
||
"description": "规则描述",
|
||
"category": "PythonCode",
|
||
"version": "1.0.0",
|
||
"severity": "error",
|
||
"source": "Standard-2023",
|
||
"is_enabled": true,
|
||
"tags": ["tag1", "tag2"],
|
||
"target_type": "DataObject",
|
||
"target_identifier": "TargetName",
|
||
"allow_imports": true,
|
||
"allowed_modules": ["math", "re", "json", "datetime"],
|
||
"entry_function": "validate",
|
||
"expected_parameters": ["param1", "param2"],
|
||
"timeout": 5,
|
||
"code_file": "path/to/code/file.py"
|
||
}
|
||
```
|
||
|
||
### 主要字段说明
|
||
|
||
- **id**: 规则的唯一标识符
|
||
- **name**: 规则名称
|
||
- **description**: 规则功能描述
|
||
- **category**: 固定为 "PythonCode"
|
||
- **version**: 规则版本号
|
||
- **severity**: 规则严重级别，如 "error", "warning", "info"
|
||
- **is_enabled**: 规则是否启用
|
||
- **tags**: 用于分类和筛选的标签列表
|
||
- **target_type**: 规则适用的目标类型，如 "DataObject", "API", "Process"
|
||
- **target_identifier**: 具体目标的标识符，如 "Well", "Seismic"
|
||
- **allow_imports**: 是否允许导入外部模块
|
||
- **allowed_modules**: 允许导入的模块列表
|
||
- **entry_function**: 入口函数名（默认为 "validate"）
|
||
- **expected_parameters**: 规则执行所需的参数列表
|
||
- **timeout**: 代码执行超时时间（秒）
|
||
- **code_file**: 外部Python代码文件的路径（相对于rules目录）
|
||
|
||
## 代码文件
|
||
|
||
代码文件应包含与 `entry_function` 字段指定的同名函数（默认是 "validate"），该函数作为验证逻辑的入口点。
|
||
|
||
### 代码文件示例
|
||
|
||
```python
|
||
"""
|
||
井坐标验证规则
|
||
|
||
此规则验证井的坐标是否在有效范围内，并检查与参考井的距离。
|
||
"""
|
||
|
||
import math
|
||
|
||
def is_valid_coordinate(lat, lon):
|
||
# 验证逻辑
|
||
return True
|
||
|
||
def calculate_distance(lat1, lon1, lat2, lon2):
|
||
# 计算距离的逻辑
|
||
return 0.0
|
||
|
||
def validate():
|
||
"""
|
||
验证入口函数
|
||
|
||
在这里实现完整的验证逻辑
|
||
"""
|
||
# 从全局命名空间获取参数
|
||
param1 = globals().get('param1')
|
||
|
||
# 执行验证逻辑
|
||
# ...
|
||
|
||
# 返回验证结果
|
||
return {
|
||
'is_valid': True,
|
||
'message': '验证通过',
|
||
'details': {
|
||
'additional_info': 'some value'
|
||
}
|
||
}
|
||
```
|
||
|
||
## 验证结果
|
||
|
||
验证函数应返回以下格式的结果：
|
||
|
||
1. **布尔值**：简单地表示验证成功或失败
|
||
2. **字典**：包含详细的验证结果，推荐格式如下：
|
||
```python
|
||
{
|
||
'is_valid': True/False, # 必需，表示验证结果
|
||
'message': '验证结果消息', # 可选，描述验证结果
|
||
'details': { ... } # 可选，包含详细信息的字典
|
||
}
|
||
```
|
||
|
||
## 安全限制
|
||
|
||
为了确保系统安全，Python 代码规则在执行时受到以下限制：
|
||
|
||
1. 只能导入明确允许的模块
|
||
2. 代码执行有超时限制
|
||
3. 无法访问文件系统、网络或系统命令
|
||
4. 在隔离的执行环境中运行
|
||
|
||
## 代码规则存储结构
|
||
|
||
推荐的存储结构如下：
|
||
|
||
```
|
||
rules/
|
||
python_code/
|
||
<rule-id>/
|
||
<version>.json # 元数据文件
|
||
<version>.py # Python代码文件
|
||
```
|
||
|
||
例如：
|
||
|
||
```
|
||
rules/
|
||
python_code/
|
||
well-coordinates-validation/
|
||
1.0.0.json
|
||
1.0.0.py
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
Python 代码规则适用于以下场景：
|
||
|
||
1. **复杂的数值计算**：如坐标转换、距离计算、范围检查等
|
||
2. **字符串处理**：解析和验证具有特定格式的字符串
|
||
3. **条件逻辑**：需要多个条件组合的复杂判断
|
||
4. **时间处理**：日期和时间的验证和计算
|
||
5. **数据转换**：在验证前需要对数据进行转换或规范化
|
||
|
||
## 测试代码规则
|
||
|
||
可以使用提供的测试工具来验证规则的正确性：
|
||
|
||
```bash
|
||
python -m ddms_compliance_suite.test_executor.test_python_external_code
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **代码注释**：添加详细的注释，特别是对于复杂的逻辑
|
||
2. **模块化**：将复杂逻辑拆分为多个小函数
|
||
3. **错误处理**：使用异常处理捕获可能的错误
|
||
4. **参数验证**：在函数开始时验证参数的有效性
|
||
5. **详细结果**：返回详细的验证结果，便于理解验证失败的原因
|
||
6. **版本管理**：为每个版本的规则创建单独的代码文件 |