239 lines
9.1 KiB
Markdown
239 lines
9.1 KiB
Markdown
# DDMS 合规性验证软件
|
||
|
||
本项目旨在开发一套DDMS（领域数据管理服务）合规性验证软件。该软件能够自动化地对注册到DMS平台的第三方DDMS进行一系列检查，包括API接口行为、数据模型的规范性、业务流程的正确性、以及数据质量等，确保其符合DMS平台定义的数据共享标准和技术规范。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ddms_compliance_suite/
|
||
├── ddms_compliance_suite/ # Python 包的根目录 (应用核心代码)
|
||
│ ├── __init__.py
|
||
│ ├── main.py # 应用主入口
|
||
│ │
|
||
│ ├── api_caller/ # API 调用模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── caller.py # API 调用逻辑
|
||
│ │
|
||
│ ├── assertion_engine/ # 断言引擎模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── engine.py # 断言逻辑
|
||
│ │
|
||
│ ├── config/ # 配置管理模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── manager.py # 配置加载与管理
|
||
│ │
|
||
│ ├── input_parser/ # 输入解析模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── parser.py # 输入文件解析逻辑
|
||
│ │
|
||
│ ├── json_schema_validator/ # JSON Schema 验证模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── validator.py # Schema 验证逻辑
|
||
│ │
|
||
│ ├── logging_service/ # 日志服务模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── logger.py # 日志配置与记录
|
||
│ │
|
||
│ ├── models/ # Pydantic 数据模型
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base_models.py # 基础模型或通用模型
|
||
│ │ ├── config_models.py # 应用配置相关模型
|
||
│ │ ├── rule_models.py # 规则库相关模型
|
||
│ │ └── validation_models.py # 验证输入/输出相关模型
|
||
│ │
|
||
│ ├── report_generator/ # 报告生成模块
|
||
│ │ ├── __init__.py
|
||
│ │ └── generator.py # 报告生成逻辑
|
||
│ │
|
||
│ ├── rule_repository/ # 规则库模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── repository.py # 规则库核心逻辑
|
||
│ │ └── adapters/ # 规则存储适配器
|
||
│ │ ├── __init__.py
|
||
│ │ ├── base_adapter.py # 适配器基类
|
||
│ │ └── filesystem_adapter.py # 文件系统适配器
|
||
│ │
|
||
│ └── test_executor/ # 测试执行器模块
|
||
│ ├── __init__.py
|
||
│ └── executor.py # 测试编排与执行逻辑
|
||
│
|
||
├── configs/ # 配置文件存放目录
|
||
│ └── config.yaml.example # 示例配置文件
|
||
│
|
||
├── rules/ # 规则文件存放目录 (JSON格式)
|
||
│ ├── api_linting_rules/ # API Linting 规则
|
||
│ │ └── api-naming-convention/
|
||
│ │ └── 1.0.0.json # 版本化的规则文件
|
||
│ ├── business_logic_rules/ # 业务逻辑规则/断言模板
|
||
│ │ └── well-id-format-rule/
|
||
│ │ └── 1.0.0.json
|
||
│ ├── data_quality/ # 数据质量校验规则
|
||
│ │ └── well-depth-range-check/
|
||
│ │ └── 1.0.0.json
|
||
│ └── json_schemas/ # JSON Schema 文件
|
||
│ └── well-data-schema/
|
||
│ └── 1.0.0.json
|
||
│
|
||
├── tests/ # 测试代码目录
|
||
│ ├── __init__.py
|
||
│ ├── test_api_caller.py
|
||
│ ├── test_json_schema_validator.py
|
||
│ └── test_rule_repository.py
|
||
│
|
||
├── README.md # 项目说明文件
|
||
└── requirements.txt # Python 依赖库列表
|
||
```
|
||
|
||
## 安装
|
||
|
||
1. 克隆仓库
|
||
2. 创建并激活虚拟环境 (推荐):
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # macOS/Linux
|
||
# venv\Scripts\activate # Windows
|
||
```
|
||
3. 安装依赖:
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 配置
|
||
|
||
编辑 `configs/config.yaml` (可以从 `configs/config.yaml.example` 复制开始)。这个配置文件包含了各个模块的设置，特别是规则库模块的配置，例如规则文件的存储路径等。
|
||
|
||
## 规则库
|
||
|
||
规则库是本系统的核心组件之一，它使用JSON文件格式存储各类规则，包括：
|
||
|
||
- **JSON Schema 规则**: 用于验证API请求/响应的数据结构
|
||
- **业务逻辑断言**: 定义业务规则和验证逻辑
|
||
- **API Linting 规则**: 用于检查API设计是否符合规范
|
||
- **数据质量规则**: 用于验证数据的质量和准确性
|
||
- **Python 代码规则**: 使用 Python 代码实现复杂的验证逻辑
|
||
|
||
### 规则文件结构
|
||
|
||
规则文件按照类别和版本存储在 `rules/` 目录下。每个规则都有一个唯一的ID和版本号，使用以下目录结构:
|
||
|
||
```
|
||
rules/
|
||
<规则类别>/
|
||
<规则ID>/
|
||
<版本号>.json
|
||
```
|
||
|
||
### 添加新规则
|
||
|
||
要添加新规则，只需在适当的目录下创建新的JSON文件并遵循规则模型的结构。每个规则必须包含`id`, `name`, `category`, `version`等基本字段，以及该类别特定的字段。
|
||
|
||
参考 `rules/` 目录下的示例规则文件以了解格式要求。
|
||
|
||
### Python 代码规则
|
||
|
||
Python 代码规则允许您使用 Python 代码编写复杂的验证逻辑，是一种非常灵活的规则类型。示例：
|
||
|
||
```json
|
||
{
|
||
"id": "complex-validation-rule",
|
||
"name": "复杂验证规则",
|
||
"description": "使用Python代码实现复杂的验证逻辑",
|
||
"category": "PythonCode",
|
||
"version": "1.0.0",
|
||
"severity": "error",
|
||
"is_enabled": true,
|
||
"tags": ["validation"],
|
||
"target_type": "DataObject",
|
||
"target_identifier": "Example",
|
||
"allow_imports": true,
|
||
"allowed_modules": ["math", "re", "json", "datetime"],
|
||
"code": "def validate():\n # In this location write validation logic\n return {'is_valid': True, 'message': '验证通过'}"
|
||
}
|
||
```
|
||
|
||
Python 代码规则的主要字段：
|
||
|
||
- **code**: 包含 Python 代码的字符串
|
||
- **code_file**: 外部Python代码文件的路径（作为code的替代选项）
|
||
- **entry_function**: 入口函数名（默认为 `validate`）
|
||
- **expected_parameters**: 规则执行时需要的参数列表
|
||
- **allow_imports**: 是否允许导入外部模块
|
||
- **allowed_modules**: 允许导入的模块列表
|
||
- **timeout**: 代码执行超时时间（秒）
|
||
|
||
出于安全考虑，Python 代码在受控环境中执行，对可访问的资源和操作进行限制。代码应定义一个与 `entry_function` 指定名称相同的函数，并在参数列表中包含 `expected_parameters` 中的所有参数。
|
||
|
||
#### 从外部文件加载Python代码
|
||
|
||
对于较长的复杂Python代码，可以将代码单独存储在外部文件中，而不是嵌入到JSON规则文件里。这样可以提高代码的可读性和维护性。方法如下：
|
||
|
||
1. 创建具有 `code_file` 属性而非 `code` 属性的规则文件：
|
||
|
||
```json
|
||
{
|
||
"id": "well-coordinates-validation",
|
||
"name": "井坐标复杂验证规则",
|
||
"description": "验证井的坐标数据，包括检查是否在特定区域内、坐标系转换等",
|
||
"category": "PythonCode",
|
||
"version": "1.0.0",
|
||
"severity": "error",
|
||
"is_enabled": true,
|
||
"target_type": "DataObject",
|
||
"target_identifier": "Well",
|
||
"allow_imports": true,
|
||
"allowed_modules": ["math", "re", "json", "datetime"],
|
||
"entry_function": "validate",
|
||
"expected_parameters": ["well_data"],
|
||
"timeout": 5,
|
||
"code_file": "python_code/well-coordinates-validation/1.0.0.py"
|
||
}
|
||
```
|
||
|
||
2. 在对应的路径创建Python代码文件（相对于rules目录）：
|
||
|
||
```python
|
||
# 在 rules/python_code/well-coordinates-validation/1.0.0.py 文件中
|
||
import math
|
||
|
||
def validate():
|
||
# 在这里编写复杂验证逻辑
|
||
return {'is_valid': True, 'message': '验证通过'}
|
||
```
|
||
|
||
3. 系统会自动加载并执行外部Python文件中的代码：
|
||
- 如果规则中指定了`id`和`version`，系统会查找 `rules/python_code/{id}/{version}.py`
|
||
- 否则，系统会使用 `code_file` 属性中指定的相对路径
|
||
|
||
使用外部文件的主要优势：
|
||
- 更好的代码可读性和组织结构
|
||
- 支持代码编辑器的语法高亮和自动完成
|
||
- 便于版本控制和代码审查
|
||
- 可以更轻松地处理复杂逻辑和较长的代码
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
python -m ddms_compliance_suite.main
|
||
```
|
||
|
||
您也可以通过导入模块方式在其他Python代码中使用本软件的功能：
|
||
|
||
```python
|
||
from ddms_compliance_suite.config.manager import ConfigurationManager
|
||
from ddms_compliance_suite.rule_repository.repository import RuleRepository
|
||
|
||
# 加载配置
|
||
config_manager = ConfigurationManager(config_path="path/to/config.yaml")
|
||
config = config_manager.get_config()
|
||
|
||
# 初始化规则库
|
||
rule_repo = RuleRepository(config.rule_repository)
|
||
|
||
# 查询规则
|
||
from ddms_compliance_suite.models.rule_models import RuleQuery, TargetType
|
||
query = RuleQuery(target_type=TargetType.API_RESPONSE, target_identifier="getWellData")
|
||
rules = rule_repo.query_rules(query)
|
||
|
||
# 输出查询到的规则
|
||
for rule in rules:
|
||
print(f"Rule: {rule.name} (ID: {rule.id}, Version: {rule.version})") |