yovinchen/BigDataTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加文档

Browse Source
This commit is contained in:
YoVinchen
2025-08-05 23:27:25 +08:00
parent 8097e9b769
commit 0ac375eb50
7 changed files with 5677 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
docs/architecture.md Normal file
View File

@@ -0,0 +1,387 @@
# DataTools Pro 系统架构设计
## 1. 系统概述
### 1.1 项目简介
DataTools Pro 是一个企业级数据处理与比对工具平台，专注于提供高效、精准、可视化的数据分析解决方案。系统支持Cassandra数据库和Redis集群的数据比对分析，具备分表查询、多主键查询、配置管理等企业级功能。
### 1.2 设计目标
- **高性能**: 支持大规模数据查询和比对处理
- **高可用**: 企业级稳定性和容错能力
- **易扩展**: 模块化设计，便于功能扩展
- **用户友好**: 直观的Web界面和操作体验
- **安全性**: 数据安全和访问控制
### 1.3 技术栈
```
前端技术栈:
├── 原生JavaScript (ES6+)
├── Bootstrap 5.1.3
├── Font Awesome 6.0.0
└── 模块化架构 (ES6 Modules)
后端技术栈:
├── Python 3.7+
├── Flask 2.3.3
├── Cassandra Driver 3.29.1
├── Redis Client
└── SQLite (配置存储)
数据存储:
├── Apache Cassandra (主要数据源)
├── Redis Cluster (缓存和数据源)
└── SQLite (配置和历史数据)
```
## 2. 整体架构
### 2.1 架构概览
```
┌─────────────────────────────────────────────────────────────┐
│ DataTools Pro 架构图 │
├─────────────────────────────────────────────────────────────┤
│ 前端层 (Frontend Layer) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│ │ 首页模块 │ │ Cassandra工具 │ │ Redis工具 ││
│ │ index.html │ │ db_compare.html │ │redis_compare.html││
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
│ │ │ │ │
│ ┌───────────────────────────────────────────────────────────┐│
│ │ 模块化JavaScript架构 ││
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐││
│ │ │ config │ │ utils │ │ api │ │ ui │ │ nav │││
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘││
│ └───────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│ 网关层 (Gateway Layer) │
│ ┌───────────────────────────────────────────────────────────┐│
│ │ Flask Web Server ││
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐││
│ │ │ 静态资源 │ │ API路由 │ │ 模板渲染 │││
│ │ │ 服务 │ │ 处理 │ │ 引擎 │││
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘││
│ └───────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────┤
│ 业务逻辑层 (Business Logic Layer) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│ │ 查询引擎 │ │ 数据比对 │ │ 配置管理 ││
│ │ QueryEngine │ │ DataComparison │ │ ConfigManager ││
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│ │ 分表处理 │ │ 日志收集 │ │ Redis处理 ││
│ │ ShardingCalc │ │ QueryLogger │ │ RedisClient ││
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
├─────────────────────────────────────────────────────────────┤
│ 数据访问层 (Data Access Layer) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│ │ Cassandra │ │ Redis Cluster │ │ SQLite DB ││
│ │ 客户端 │ │ 客户端 │ │ 本地存储 ││
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
├─────────────────────────────────────────────────────────────┤
│ 数据存储层 (Data Storage Layer) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│
│ │ 生产环境 │ │ 测试环境 │ │ 配置数据 ││
│ │ Cassandra │ │ Cassandra │ │ SQLite ││
│ └─────────────────┘ └─────────────────┘ └─────────────────┘│
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 生产Redis │ │ 测试Redis │ │
│ │ 集群 │ │ 集群 │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 2.2 核心组件
#### 2.2.1 前端架构
```javascript
// 模块化架构设计
static/js/
├── app-main.js // 主应用入口，统一管理
└── modules/
├── config.js // 配置管理 - API端点、UI配置
├── utils.js // 工具函数 - 通用功能库
├── api.js // HTTP客户端 - 统一请求处理
├── ui.js // UI组件 - 提示、模态框、分页
└── navigation.js // 导航管理 - 路由、面包屑、快捷键
```
**设计模式**: 模块化 + 单例模式
**核心特性**:
- ES6模块化，避免全局变量污染
- 统一的配置管理和错误处理
- 响应式UI组件和交互增强
- 键盘快捷键和无障碍支持
#### 2.2.2 后端架构
```python
# 模块化后端设计
modules/
├── api_routes.py // API路由定义和请求处理
├── cassandra_client.py // Cassandra数据库连接和操作
├── redis_client.py // Redis集群连接和操作
├── query_engine.py // 查询引擎和SQL构建
├── data_comparison.py // 数据比对算法和分析
├── sharding.py // 分表计算和时间戳处理
├── config_manager.py // 配置组管理和持久化
├── query_logger.py // 查询日志收集和管理
└── database.py // SQLite数据库操作
```
**设计模式**: 分层架构 + 依赖注入
**核心特性**:
- 单一职责原则，模块解耦
- 统一的错误处理和日志记录
- 连接池管理和资源优化
- 配置驱动的灵活部署
## 3. 核心功能模块
### 3.1 Cassandra数据比对模块
#### 3.1.1 功能特性
- **多模式查询**: 单表查询、分表查询、多主键查询
- **时间分表支持**: TWCS (Time Window Compaction Strategy) 分表计算
- **复合主键**: 支持多字段组合主键查询
- **字段级比对**: 支持包含/排除字段的精细化比较
- **JSON处理**: 智能JSON字段识别和深度比较
#### 3.1.2 核心算法
```python
# 分表索引计算算法
def calculate_shard_index(timestamp, interval_seconds, table_count):
"""
计算分表索引
- timestamp: 从Key中提取的时间戳
- interval_seconds: 分表时间间隔(默认604800秒=7天)
- table_count: 分表数量(默认14张表)
"""
return int(timestamp) // interval_seconds % table_count
# 时间戳提取算法
def extract_timestamp_from_key(key):
"""
从Key中提取时间戳 - 删除所有非数字字符
示例: 'wmid_1609459200' -> 1609459200
"""
return re.sub(r'\D', '', key)
# 复合主键匹配算法
def match_composite_key(record, key_fields, key_values):
"""
复合主键匹配逻辑
- 支持单主键和复合主键统一处理
- 自动类型转换和字段验证
"""
if len(key_fields) == 1:
return str(record.get(key_fields[0])) == str(key_values[0])
else:
return all(
str(record.get(field)) == str(value)
for field, value in zip(key_fields, key_values)
)
```
### 3.2 Redis集群比对模块
#### 3.2.1 功能特性
- **多数据类型支持**: String、Hash、List、Set、ZSet
- **查询模式**: 随机采样、指定Key查询
- **集群管理**: 多节点集群配置和连接管理
- **性能监控**: 连接状态、查询耗时统计
- **批量操作**: 大批量Key的并行处理
#### 3.2.2 Redis集群架构
```python
# Redis集群连接配置
{
"cluster_name": "生产集群",
"nodes": [
{"host": "127.0.0.1", "port": 6379},
{"host": "127.0.0.1", "port": 6380}
],
"password": "optional_password",
"socket_timeout": 3,
"socket_connect_timeout": 3,
"max_connections_per_node": 16
}
```
### 3.3 数据比对引擎
#### 3.3.1 比对算法
```python
# 数据比对核心逻辑
class DataComparison:
def compare_results(self, pro_data, test_data, key_fields):
"""
数据比对主算法:
1. 构建数据索引映射 (基于主键)
2. 逐字段深度比较
3. JSON字段特殊处理
4. 数组字段顺序无关比较
5. 生成差异报告和统计
"""
differences = []
identical_results = []
field_diff_count = {}
# 构建生产数据索引
pro_index = self.build_data_index(pro_data, key_fields)
test_index = self.build_data_index(test_data, key_fields)
# 执行比对逻辑
for key, pro_record in pro_index.items():
if key in test_index:
test_record = test_index[key]
diffs = self.compare_records(pro_record, test_record)
if diffs:
differences.extend(diffs)
else:
identical_results.append({
'key': key,
'pro_fields': pro_record,
'test_fields': test_record
})
return {
'differences': differences,
'identical_results': identical_results,
'field_diff_count': field_diff_count,
'summary': self.generate_summary(differences, identical_results)
}
```
#### 3.3.2 JSON处理算法
```python
def compare_json_values(pro_value, test_value):
"""
JSON值比较算法:
1. 智能检测JSON格式
2. 规范化JSON字符串
3. 深度比较对象结构
4. 数组顺序无关比较
"""
if self.is_json_field(pro_value) and self.is_json_field(test_value):
try:
pro_obj = json.loads(pro_value)
test_obj = json.loads(test_value)
return self.deep_compare_objects(pro_obj, test_obj)
except:
return pro_value == test_value
return pro_value == test_value
```
## 4. 数据流架构
### 4.1 查询执行流程
```mermaid
graph TD
A[用户请求] --> B[前端验证]
B --> C[API路由]
C --> D{查询类型}
D -->|单表查询| E[QueryEngine.execute_query]
D -->|分表查询| F[QueryEngine.execute_sharding_query]
E --> G[数据库连接]
F --> H[分表计算]
H --> G
G --> I[并行查询执行]
I --> J[数据收集]
J --> K[DataComparison.compare_results]
K --> L[结果分析]
L --> M[日志记录]
M --> N[响应返回]
```
### 4.2 配置管理流程
```mermaid
graph TD
A[配置创建/更新] --> B[ConfigManager验证]
B --> C[SQLite持久化]
C --> D[配置缓存更新]
D --> E[前端状态同步]
F[配置加载] --> G[SQLite查询]
G --> H[配置反序列化]
H --> I[前端配置应用]
```
## 5. 性能优化策略
### 5.1 查询优化
- **连接池管理**: 复用数据库连接，减少连接开销
- **并行查询**: 多线程并行执行生产和测试环境查询
- **分批处理**: 大量Key分批查询，避免内存溢出
- **索引优化**: 合理设计Cassandra分区键和聚簇键
### 5.2 前端性能
- **懒加载**: 按需加载JS模块和数据
- **虚拟分页**: 大数据集的分页展示
- **防抖节流**: 用户输入和搜索的性能优化
- **缓存策略**: 查询结果和配置数据的客户端缓存
### 5.3 内存管理
- **流式处理**: 大数据集的流式读取和处理
- **及时释放**: 查询完成后及时释放数据库连接和内存
- **垃圾回收**: Python和JavaScript的内存回收优化
## 6. 扩展性设计
### 6.1 水平扩展
- **无状态设计**: 应用层无状态，支持负载均衡
- **配置外部化**: 支持配置中心和环境变量
- **容器化**: Docker容器化部署
- **微服务拆分**: 可拆分为独立的查询服务和比对服务
### 6.2 功能扩展
- **插件架构**: 支持自定义数据源和比对算法
- **API开放**: RESTful API支持第三方集成
- **规则引擎**: 可配置的数据验证和比对规则
- **报告生成**: 支持多种格式的报告导出
## 7. 安全架构
### 7.1 数据安全
- **连接加密**: 支持SSL/TLS加密连接
- **密码管理**: 敏感信息加密存储
- **访问控制**: 基于角色的权限管理
- **审计日志**: 完整的操作审计记录
### 7.2 系统安全
- **输入验证**: 严格的参数验证和SQL注入防护
- **错误处理**: 不暴露敏感系统信息
- **会话管理**: 安全的会话管理机制
- **网络安全**: 防火墙和网络隔离
## 8. 监控和运维
### 8.1 系统监控
- **性能指标**: 查询耗时、成功率、错误率
- **资源监控**: CPU、内存、网络使用情况
- **业务指标**: 查询量、用户活跃度、功能使用统计
- **告警机制**: 异常情况的实时告警
### 8.2 日志管理
- **结构化日志**: JSON格式的结构化日志
- **日志分级**: INFO、WARNING、ERROR、DEBUG
- **日志轮转**: 自动日志清理和归档
- **日志分析**: 支持ELK等日志分析工具
## 9. 技术债务和改进计划
### 9.1 当前技术债务
- **单体应用**: 所有功能集中在单个Flask应用中
- **前端技术**: 使用原生JavaScript，缺乏现代化框架
- **测试覆盖**: 缺乏完整的单元测试和集成测试
- **文档完善**: API文档和代码注释需要完善
### 9.2 改进计划
- **微服务改造**: 逐步拆分为独立的微服务
- **前端升级**: 考虑引入Vue.js或React框架
- **CI/CD**: 建立完整的持续集成和部署流程
- **性能测试**: 建立性能基准和压力测试
---
**版本**: v2.0.0
**更新日期**: 2024-08-05
**维护者**: DataTools Pro Team