优化项目整合内容

This commit is contained in:
2025-08-05 19:56:38 +08:00
parent 3f78ce7365
commit 4a0800a776
7 changed files with 2608 additions and 364 deletions

446
CLAUDE.md
View File

@@ -4,94 +4,89 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## 项目架构
这是一个基于 Flask 的数据库查询比对工具,用于比较 Cassandra 数据库中生产环境和测试环境的数据差异。现已支持单表查询、TWCS分表查询和**多主键查询**三种核心功能
这是一个基于Flask的现代化数据库查询比对工具,支持Cassandra和Redis两大数据源的数据一致性验证。采用模块化架构设计支持单表查询、TWCS分表查询多主键查询和Redis集群比对等多种复杂场景
### 核心组件架构
**后端 (Flask)**
- `app.py`: 主应用文件包含所有API端点和数据处理逻辑
- 数据库连接管理Cassandra + SQLite
- 查询执行和结果比对算法
- 配置组管理CRUD操作
- JSON字段特殊处理和数组比较逻辑
- 查询历史记录管理
- **分表查询功能**
- `ShardingCalculator`TWCS时间分表计算器
- `execute_sharding_query()`:分表查询执行
- `execute_mixed_query()`:混合查询支持(生产分表+测试单表组合)
- `/api/sharding-query`分表查询API端点
- **多主键查询功能(新增)**
- `execute_query()`函数支持复合主键SQL构建
- `compare_results()`函数支持复合主键匹配
- `match_composite_key()`辅助函数处理复合主键比较
- `config_groups.db`: SQLite数据库存储用户保存的配置组、查询历史和分表配置
**主应用 (app.py)**
- 应用入口和全局配置管理
- 模块导入和路由设置
- 日志系统初始化
**模块化后端 (modules/)**
- `api_routes.py`: 所有Flask路由和请求处理逻辑
- Cassandra查询API`/api/query`, `/api/sharding-query`
- Redis比对API`/api/redis/compare`
- 配置管理API配置组CRUD操作
- 查询历史API历史记录的保存和回放
- `database.py`: SQLite数据库管理
- 数据库初始化和表结构创建
- 版本控制和字段动态添加
- 事务处理和连接管理
- `query_engine.py`: Cassandra查询引擎
- 单表查询和分表查询执行
- 多主键查询支持复合主键SQL构建
- 并行查询和性能优化
- `redis_query.py`: Redis查询引擎
- 全Redis数据类型支持String/Hash/List/Set/ZSet/Stream
- 随机采样和指定Key两种查询模式
- 集群模式的自动检测和连接
- `data_comparison.py`: 数据比对引擎
- JSON和数组的智能深度比较
- 复合主键的精确匹配算法
- 数据质量评估和建议生成
- `cassandra_client.py` / `redis_client.py`: 数据库客户端
- 连接管理和错误处理
- 性能监控和连接池优化
- `config_groups.db`: SQLite数据库存储配置组、查询历史和日志
**前端 (原生JavaScript + Bootstrap)**
- `templates/db_compare.html`: 主界面模板,**现已支持单表、分表和多主键三种模式**
- 分表模式切换开关
- 生产/测试环境独立分表配置
- 分表参数配置(时间间隔、分表数量)
- 分表查询信息展示
- **多主键查询支持**UI提示和占位符文本更新
- `templates/index.html`: 工具集合首页
- `static/js/app.js`: 核心前端逻辑
- `templates/index.html`: 工具集合首页,提供功能导航
- `templates/db_compare.html`: Cassandra比对界面
- 支持单表、分表和多主键三种查询模式
- 分表模式切换和参数配置
- 实时查询日志和性能监控
- `templates/redis_compare.html`: Redis比对界面
- 集群配置和连接管理
- 随机采样和指定Key两种查询模式
- 全数据类型支持的结果展示
- `static/js/app.js`: Cassandra查询的前端逻辑
- 配置管理和表单处理
- 差异结果的分页展示系统
- 原生数据展示(多种视图模式:格式化、原始、差异对比、树形)
- 高级错误处理和用户反馈
- **分表查询支持**
- `toggleShardingMode()`:分表模式切换
- `getShardingConfig()`:分表配置获取
- `displayShardingInfo()`:分表查询结果展示
- **多主键查询支持(新增)**
- `getCurrentConfig()`函数解析复合主键配置
- `formatCompositeKey()`:复合主键显示格式化
- UI占位符和提示文本支持复合主键格式
**分表查询功能模块(重要新增)**
- **时间戳提取算法(已更新)**
- **新规则**:使用 `re.sub(r'\D', '', key)` 删除Key中所有非数字字符
- 将提取到的数字字符串转换为整数作为时间戳
- 支持任意格式的Key只要包含数字即可
- 示例:`wmid_1609459200``1609459200``abc123def456``123456`
- **分表索引计算**
- 公式:`int(numbers) // interval_seconds % table_count`
- 默认配置604800秒间隔7天14张分表
- 支持自定义配置
- **混合查询场景**
- 生产环境分表 + 测试环境单表
- 生产环境分表 + 测试环境分表
- 生产环境单表 + 测试环境分表
- 生产环境单表 + 测试环境单表
**多主键查询功能模块(最新功能)**
- **复合主键格式**
- 主键字段:逗号分隔,如 `docid,id`
- 查询值:逗号分隔,如 `8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED`
- 一行一组复合主键值
- **SQL构建逻辑**
- 单主键:`key IN (val1, val2, val3)`
- 复合主键:`(key1='val1' AND key2='val2') OR (key1='val3' AND key2='val4')`
- **数据匹配算法**
- `match_composite_key()`函数处理单主键和复合主键的统一匹配
- 支持字段数量验证和类型转换
- **向后兼容**
- 完全兼容现有单主键查询
- 自动识别主键类型并采用相应处理逻辑
**核心文件**
- `app.py`: 唯一的主应用文件,包含所有功能实现
- `config_groups.db`: SQLite数据库文件
- 分页展示和数据可视化
- 多主键查询的UI适配
- `static/js/redis_compare.js`: Redis比对的前端逻辑
- Redis集群配置管理
- 查询模式切换和参数设置
- 多类型数据的格式化展示
### 关键功能模块
**数据比对引擎**
**Cassandra数据比对引擎**
- 支持复杂JSON字段的深度比较
- 数组字段的顺序无关比较
- 字段级别的差异统计和分析
- 数据质量评估和建议生成
- 支持包含和排除特定字段的比较
- **多主键数据比对**:支持复合主键的精确匹配和差异检测
- 多主键数据比对:支持复合主键的精确匹配和差异检测
**Redis数据比对引擎**
- 全数据类型支持String、Hash、List、Set、ZSet、Stream
- 智能JSON检测和深度比较
- 集群和单节点模式的自动适配
- 随机采样和指定Key两种查询模式
- 性能监控和连接时间统计
**分表查询功能模块**
- **时间戳提取算法**:使用 `re.sub(r'\D', '', key)` 删除Key中所有非数字字符
- **分表索引计算**:公式 `int(numbers) // interval_seconds % table_count`
- **混合查询场景**:支持生产分表+测试单表等组合
- **并行查询**:多分表同时查询以提高性能
**多主键查询功能模块**
- **复合主键格式**:主键字段逗号分隔,查询值逗号分隔
- **SQL构建逻辑**自动选择IN查询或OR条件组合
- **数据匹配算法**:统一处理单主键和复合主键匹配
- **向后兼容**:完全兼容现有单主键查询
**用户界面特性**
- 分页系统(差异记录和相同记录)
@@ -100,12 +95,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- 配置导入导出和管理
- 详细的错误诊断和故障排查指南
- 查询历史记录和复用
- **查询日志系统(新增)**
- 实时显示SQL执行日志
- 支持日志级别过滤INFO/WARNING/ERROR
- SQL语句语法高亮显示
- 执行时间和记录数统计
- 日志清空和刷新功能
- 查询日志系统实时显示SQL执行日志支持日志级别过滤
## 开发相关命令
@@ -117,95 +107,113 @@ pip install -r requirements.txt
# 运行应用默认端口5000
python app.py
# 自定义端口运行
# 修改app.py最后一行app.run(debug=True, port=XXXX)
# 开发模式启动(支持热重载)
# app.py中默认开启debug=True
# 生产环境运行
# python app.py 或使用WSGI服务器如gunicorn
```
### 调试和日志
```bash
# 应用启动后查询日志可通过以下API获取
# GET /api/query-logs - 获取查询日志
# DELETE /api/query-logs - 清空查询日志
# 日志级别INFO, WARNING, ERROR
# 所有Cassandra查询和SQL操作都会记录到查询日志中
# 使用WSGI服务器如gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```
### 测试和验证
```bash
# 主要通过Web界面进行功能测试
# 单表查询测试http://localhost:5000/db-compare
# 分表查询测试在Web界面中开启分表模式
# Cassandra单表查询http://localhost:5000/db-compare
# Redis数据比对http://localhost:5000/redis-compare
# 工具集合首页http://localhost:5000
# 多主键查询测试示例:
# Cassandra多主键查询测试示例:
# 1. 在主键字段中输入docid,id
# 2. 在查询Key值中输入每行一组
# 8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED
# 9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED
# Redis查询测试示例
# 1. 配置两个Redis集群连接
# 2. 选择随机采样模式,设置采样数量
# 3. 或选择指定Key模式输入要比对的Key列表
# 数据库初始化如果config_groups.db不存在
# 通过访问Web界面会自动创建数据库表结构
```
### 开发模式
应用默认运行在debug模式代码修改后自动重启。访问
- http://localhost:5000 - 工具集合首页
- http://localhost:5000/db-compare - 数据库比对工具
### 依赖项
- Flask==2.3.3
- cassandra-driver==3.29.1
- redis==5.0.1
### 项目特点
- **单文件架构**所有后端逻辑都在 `app.py` 中实现2230+行代码)
- **内存+数据库日志系统**:使用 `QueryLogCollector` 类在内存和SQLite中收集查询日志
- **SQLite本地存储**:配置组、查询历史和日志存储在本地 `config_groups.db` 文件中
- **前端原生实现**使用原生JavaScript + Bootstrap无现代前端框架
- **多模式支持**:单表查询、分表查询、多主键查询的统一架构
- **模块化架构**清晰的代码组织和职责分离
- **双数据源支持**同时支持Cassandra和Redis数据比对
- **智能查询引擎**:针对不同数据源的优化查询策略
- **SQLite本地存储**:配置组、查询历史和日志的本地持久化
- **前端原生实现**使用原生JavaScript + Bootstrap无现代前端框架依赖
- **多模式支持**单表查询、分表查询、多主键查询、Redis比对的统一架构
## API架构说明
### 核心API端点
- `GET /api/default-config`: 获取默认数据库配置
- `POST /api/query`: 执行单表数据库查询比对(**支持多主键查询**
- `POST /api/sharding-query`: 执行分表查询比对(**支持多主键查询**
- `GET /api/config-groups`: 获取所有配置组
- `POST /api/config-groups`: 创建新配置组
- `GET /api/config-groups/<id>`: 获取特定配置组
- `DELETE /api/config-groups/<id>`: 删除配置组
### Cassandra相关API端点
- `GET /api/default-config`: 获取默认Cassandra配置
- `POST /api/query`: 执行单表数据库查询比对(支持多主键查询)
- `POST /api/sharding-query`: 执行分表查询比对(支持多主键查询)
- `GET /api/config-groups`: 获取所有Cassandra配置组
- `POST /api/config-groups`: 创建新Cassandra配置组
- `GET /api/config-groups/<id>`: 获取特定Cassandra配置组
- `DELETE /api/config-groups/<id>`: 删除Cassandra配置组
### Redis相关API端点
- `POST /api/redis/compare`: 执行Redis数据比对
- `POST /api/redis/test-connection`: 测试Redis连接
- `GET /api/redis/config-groups`: 获取所有Redis配置组
- `POST /api/redis/config-groups`: 创建新Redis配置组
- `GET /api/redis/config-groups/<id>`: 获取特定Redis配置组
- `DELETE /api/redis/config-groups/<id>`: 删除Redis配置组
- `GET /api/redis/query-history`: 获取Redis查询历史
- `POST /api/redis/query-history`: 保存Redis查询历史
- `GET /api/redis/query-history/<id>`: 获取特定Redis历史记录
- `DELETE /api/redis/query-history/<id>`: 删除Redis历史记录
### 通用API端点
- `POST /api/init-db`: 初始化SQLite数据库
- `GET /api/query-history`: 获取查询历史
- `POST /api/query-history`: 保存查询历史
- `GET /api/query-history/<id>`: 获取特定历史记录
- `GET /api/query-history`: 获取Cassandra查询历史
- `POST /api/query-history`: 保存Cassandra查询历史
- `GET /api/query-history/<id>`: 获取特定Cassandra历史记录
- `GET /api/query-history/<id>/results`: 获取历史记录的完整结果数据
- `DELETE /api/query-history/<id>`: 删除历史记录
- `DELETE /api/query-history/<id>`: 删除Cassandra历史记录
- `GET /api/query-logs`: 获取查询日志支持limit参数
- `GET /api/query-logs/history/<id>`: 获取特定历史记录的相关日志
- `DELETE /api/query-logs`: 清空查询日志
### 查询比对流程
**单表查询流程(`/api/query`**
**Cassandra单表查询流程(`/api/query`**
1. 前端发送配置和Key值列表到 `/api/query`
2. 后端创建两个Cassandra连接生产+测试)
3. 并行执行查询,获取原始数据
4. 运行比较算法,生成差异报告
2. 后端通过 `cassandra_client.py` 创建两个Cassandra连接生产+测试)
3. `query_engine.py` 并行执行查询,获取原始数据
4. `data_comparison.py` 运行比较算法,生成差异报告
5. 返回完整结果(差异、统计、原始数据)
**分表查询流程(`/api/sharding-query`**
**Cassandra分表查询流程(`/api/sharding-query`**
1. 前端发送配置、Key值列表和分表配置到 `/api/sharding-query`
2. 后端使用 `ShardingCalculator` 解析Key中的时间戳
2. 后端使用 `sharding.py` 中的 `ShardingCalculator` 解析Key中的时间戳
3. 根据分表算法计算每个Key对应的分表名称
4. 创建分表映射关系,并行执行分表查询
4. `query_engine.py` 创建分表映射关系,并行执行分表查询
5. 汇总所有分表结果,执行比较算法
6. 返回包含分表信息的完整结果
**Redis数据比对流程`/api/redis/compare`**
1. 前端发送Redis集群配置和查询参数到 `/api/redis/compare`
2. 后端通过 `redis_client.py` 创建两个Redis连接
3. `redis_query.py` 根据查询模式执行数据获取:
- 随机采样模式从源集群随机获取指定数量的Key
- 指定Key模式查询用户提供的Key列表
4. 针对每个Key查询其在两个集群中的值和数据类型
5. 执行智能数据比较(根据数据类型选择比较策略)
6. 返回比对结果和统计信息
## 数据结构和配置
### 数据库配置结构
### Cassandra配置结构
**单表查询配置**
```javascript
@@ -240,6 +248,32 @@ python app.py
}
```
### Redis配置结构
**Redis集群配置**
```javascript
{
source_config: {
name: "源集群名称",
nodes: [
{host: "192.168.1.200", port: 7000},
{host: "192.168.1.201", port: 7001}
],
password: "redis_password",
socket_timeout: 3,
socket_connect_timeout: 3,
max_connections_per_node: 16
},
target_config: { /* 同上 */ },
query_config: {
mode: "random_sample", // 或 "specific_keys"
sample_size: 1000, // 随机采样数量random_sample模式
keys: ["key1", "key2"], // 指定Key列表specific_keys模式
key_pattern: "*" // Key匹配模式可选
}
}
```
**多主键查询格式示例**
```javascript
// 复合主键配置
@@ -253,6 +287,8 @@ values: [
```
### 查询结果结构
**Cassandra查询结果**
```javascript
{
total_keys, pro_count, test_count,
@@ -282,103 +318,77 @@ values: [
}
```
**Redis查询结果**
```javascript
{
total_keys, source_count, target_count,
identical_count, different_count, source_only_count, target_only_count,
// 详细比对结果
identical_keys: ["key1", "key2"],
different_keys: [
{
key: "key3",
source_type: "string", target_type: "string",
source_value: "value1", target_value: "value2",
message: "Value mismatch"
}
],
source_only_keys: ["key4"], // 仅源集群存在
target_only_keys: ["key5"], // 仅目标集群存在
// 统计信息
type_distribution: {
"string": 500, "hash": 200, "list": 100,
"set": 50, "zset": 30, "stream": 20
},
consistency_percentage: 85.5,
// 性能统计
query_time: 2.5,
source_connection_time: 0.1,
target_connection_time: 0.15
}
```
## 开发注意事项
### 代码修改指导
- **单文件开发**所有后端功能都在 `app.py`,修改时注意代码结构清晰
- **模块化开发**功能按模块组织,修改时注意模块间的依赖关系
- **数据库模式变更**修改SQLite表结构需要考虑向后兼容性
- **前端JavaScript**:位于 `static/js/app.js`使用原生JS注意浏览器兼容性
- **前端JavaScript**分别位于 `static/js/app.js`Cassandra`static/js/redis_compare.js`Redis
- **HTML模板**使用Jinja2模板引擎主要文件在 `templates/` 目录
### 核心类和函数位置app.py
- `QueryLogCollector`日志收集系统第23-276行
- `ShardingCalculator`分表计算器第291行开始
- 数据库连接:`create_connection()` (第1072行)
- 查询比对:`execute_query()` (第1177行) 和 `execute_sharding_query()` (第1250行)
- **多主键支持**`match_composite_key()` (第1407行)
- API路由使用Flask装饰器定义
### 关键模块和类位置
- **主应用**`app.py` - 应用入口和模块集成
- **路由管理**`modules/api_routes.py` - 所有API端点的实现
- **数据库管理**`modules/database.py` - SQLite数据库操作
- **Cassandra客户端**`modules/cassandra_client.py` - 连接管理和查询执行
- **Redis客户端**`modules/redis_client.py` - Redis连接和性能监控
- **查询引擎**`modules/query_engine.py` - Cassandra查询逻辑
- **Redis查询**`modules/redis_query.py` - Redis数据比对逻辑
- **数据比较**`modules/data_comparison.py` - 智能数据比较算法
- **分表计算**`modules/sharding.py` - TWCS分表逻辑
- **配置管理**`modules/config_manager.py` - 配置组管理
- **日志收集**`modules/query_logger.py` - 查询日志系统
### 分表功能开发指导
- **时间戳解析(已更新)**`ShardingCalculator.extract_timestamp_from_key()` 新规则
- 使用 `re.sub(r'\D', '', key)` 删除所有非数字字符
- 将提取的数字字符串转换为整数作为时间戳
- 不再进行时间戳有效性验证,支持任意数字组合
- **分表索引计算**:使用公式 `int(numbers) // interval_seconds % table_count`
- **错误处理**Key中没有数字字符时会记录到 `failed_keys`
- **混合查询**:支持生产环境分表+测试环境单表的组合场景
- **前端状态**:分表模式通过 `toggleShardingMode()` 切换影响UI和提示文本
### 模块依赖关系
```
app.py
├── modules/api_routes.py (路由层)
├── modules/config_manager.py (配置管理)
├── modules/cassandra_client.py (Cassandra连接)
├── modules/redis_client.py (Redis连接)
├── modules/query_engine.py (Cassandra查询)
│ ├── modules/sharding.py (分表计算)
│ └── modules/data_comparison.py (数据比较)
├── modules/redis_query.py (Redis查询)
└── modules/database.py (SQLite数据库)
```
### 多主键功能开发指导
- **主键解析**:前端通过逗号分隔解析主键字段和值
- **SQL构建**:后端 `execute_query()` 根据主键数量选择不同的WHERE条件构建策略
- **数据匹配**`match_composite_key()` 函数统一处理单主键和复合主键匹配逻辑
- **UI适配**:占位符和提示文本根据模式动态更新
- **结果展示**:支持复合主键对象格式的显示和格式化
### Cassandra连接处理
- 连接包含详细的错误诊断和重试机制
- 使用DCAwareRoundRobinPolicy避免负载均衡警告
- 连接超时设置为10秒
- 失败时提供网络连通性测试
- 支持认证PlainTextAuthProvider
- 支持集群配置cluster_name, datacenter
### 前端状态管理
- `currentResults`: 存储最新查询结果
- 分页状态:`currentIdenticalPage`, `currentDifferencePage`
- 过滤状态:`filteredIdenticalResults`, `filteredDifferenceResults`
- **日志状态(新增)**`allQueryLogs` - 存储所有查询日志
### JSON和数组字段处理
- `normalize_json_string()`: 标准化JSON字符串用于比较
- `compare_array_values()`: 数组的顺序无关比较
- `is_json_field()`: 智能检测JSON字段
- 前端提供专门的JSON语法高亮和树形展示
### 错误处理策略
- 后端分类错误connection_error, validation_error, query_error, system_error
- 前端:详细错误展示,包含配置信息、解决建议、连接测试工具
- 提供交互式故障排查指南
- **查询日志(新增)**所有SQL执行和错误信息都会记录到查询日志中
### 性能考虑
- 大数据集的分页处理
- 原生数据的延迟加载
- JSON格式化的客户端缓存
- 搜索和过滤的防抖处理
### SQLite数据库表结构
**config_groups表**
- id: 主键
- name: 配置组名称(唯一)
- description: 描述
- pro_config: 生产环境配置JSON
- test_config: 测试环境配置JSON
- query_config: 查询配置JSON
- **sharding_config: 分表配置JSON新增字段**
- created_at/updated_at: 时间戳
**query_history表**
- id: 主键
- name: 查询名称
- description: 描述
- pro_config/test_config/query_config: 配置JSON
- query_keys: 查询的键值JSON
- results_summary: 结果摘要JSON
- execution_time: 执行时间
- total_keys/differences_count/identical_count: 统计数据
- **sharding_config: 分表配置JSON新增字段**
- **query_type: 查询类型('single'/'sharding',新增字段)**
- **raw_results/differences_data/identical_data: 查询结果数据(新增字段)**
- created_at: 时间戳
**query_logs表新增表**
- id: 主键
- batch_id: 批次ID
- **history_id: 关联历史记录ID外键**
- timestamp: 时间戳
- level: 日志级别INFO/WARNING/ERROR
- message: 日志消息
- query_type: 查询类型
- created_at: 创建时间
### 开发最佳实践
- **错误处理**:每个模块都有详细的错误分类和处理机制
- **日志记录**:使用统一的日志系统,支持不同级别的日志输出
- **性能监控**:查询时间和连接时间的详细统计
- **配置管理**:支持配置的导入导出和版本管理
- **数据安全**:敏感信息(密码)的安全处理