yovinchen/BigDataTool

Fork 0

Files

YoVinchen 689328eeca 完善对比内容

2025-07-31 23:45:15 +08:00

5.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目架构

这是一个基于 Flask 的数据库查询比对工具，用于比较 Cassandra 数据库中生产环境和测试环境的数据差异。

核心组件架构

后端 (Flask)

app.py: 主应用文件，包含所有API端点和数据处理逻辑
- 数据库连接管理（Cassandra + SQLite）
- 查询执行和结果比对算法
- 配置组管理（CRUD操作）
- JSON字段特殊处理和数组比较逻辑
- 查询历史记录管理
config_groups.db: SQLite数据库，存储用户保存的配置组和查询历史

前端 (原生JavaScript + Bootstrap)

templates/db_compare.html: 主界面模板，包含配置表单和结果展示
templates/index.html: 工具集合首页
static/js/app.js: 核心前端逻辑
- 配置管理和表单处理
- 差异结果的分页展示系统
- 原生数据展示（多种视图模式：格式化、原始、差异对比、树形）
- 高级错误处理和用户反馈

示例代码

demo/Query.py: 独立的Cassandra查询比对脚本示例
demo/twcsQuery.py: 另一个查询示例

关键功能模块

数据比对引擎

支持复杂JSON字段的深度比较
数组字段的顺序无关比较
字段级别的差异统计和分析
数据质量评估和建议生成
支持包含和排除特定字段的比较

用户界面特性

分页系统（差异记录和相同记录）
实时搜索和过滤
原生数据展示（JSON语法高亮、树形视图）
配置导入导出和管理
详细的错误诊断和故障排查指南
查询历史记录和复用

开发相关命令

环境设置

# 安装依赖（仅需要Flask和cassandra-driver）
pip install -r requirements.txt

# 运行应用（默认端口5000）
python app.py

# 自定义端口运行
# 修改app.py最后一行：app.run(debug=True, port=5001)

开发模式

应用默认运行在debug模式，代码修改后自动重启。访问 http://localhost:5000 查看首页，http://localhost:5000/db-compare 使用比对工具。

依赖项

Flask==2.3.3
cassandra-driver==3.29.1

API架构说明

核心API端点

GET /api/default-config: 获取默认数据库配置
POST /api/query: 执行数据库查询比对（主要功能）
GET /api/config-groups: 获取所有配置组
POST /api/config-groups: 创建新配置组
GET /api/config-groups/<id>: 获取特定配置组
DELETE /api/config-groups/<id>: 删除配置组
POST /api/init-db: 初始化SQLite数据库
GET /api/query-history: 获取查询历史
POST /api/query-history: 保存查询历史
GET /api/query-history/<id>: 获取特定历史记录
DELETE /api/query-history/<id>: 删除历史记录

查询比对流程

前端发送配置和Key值列表到 /api/query
后端创建两个Cassandra连接（生产+测试）
并行执行查询，获取原始数据
运行比较算法，生成差异报告
返回完整结果（差异、统计、原始数据）

数据结构和配置

数据库配置结构

{
  pro_config: {
    cluster_name, datacenter, hosts[], port, 
    username, password, keyspace, table
  },
  test_config: { /* 同上 */ },
  keys: ["主键字段名"],
  fields_to_compare: ["字段1", "字段2"], // 空数组=全部字段
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"] // 要查询的Key值
}

查询结果结构

{
  total_keys, pro_count, test_count,
  differences: [{ key, field, pro_value, test_value, message }],
  identical_results: [{ key, pro_fields, test_fields }],
  field_diff_count: { "field_name": count },
  raw_pro_data: [], raw_test_data: [],
  summary: { overview, percentages, field_analysis, recommendations }
}

开发注意事项

Cassandra连接处理

连接包含详细的错误诊断和重试机制
使用DCAwareRoundRobinPolicy避免负载均衡警告
连接超时设置为10秒
失败时提供网络连通性测试
支持认证（PlainTextAuthProvider）
支持集群配置（cluster_name, datacenter）

前端状态管理

currentResults: 存储最新查询结果
分页状态：currentIdenticalPage, currentDifferencePage
过滤状态：filteredIdenticalResults, filteredDifferenceResults

JSON和数组字段处理

normalize_json_string(): 标准化JSON字符串用于比较
compare_array_values(): 数组的顺序无关比较
is_json_field(): 智能检测JSON字段
前端提供专门的JSON语法高亮和树形展示

错误处理策略

后端：分类错误（connection_error, validation_error, query_error, system_error）
前端：详细错误展示，包含配置信息、解决建议、连接测试工具
提供交互式故障排查指南

性能考虑

大数据集的分页处理
原生数据的延迟加载
JSON格式化的客户端缓存
搜索和过滤的防抖处理

SQLite数据库表结构

config_groups表

id: 主键
name: 配置组名称（唯一）
description: 描述
pro_config: 生产环境配置（JSON）
test_config: 测试环境配置（JSON）
query_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: 统计数据
created_at: 时间戳

5.5 KiB Raw Blame History Unescape Escape