yovinchen/BigDataTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cdf7e36ba3e1f486ef1577c4d098e67b833241bc
BigDataTool/CLAUDE.md
YoVinchen 4a0800a776 优化项目整合内容
2025-08-05 19:56:38 +08:00

14 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和Redis两大数据源的数据一致性验证。采用模块化架构设计，支持单表查询、TWCS分表查询、多主键查询和Redis集群比对等多种复杂场景。

核心组件架构

主应用 (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/index.html: 工具集合首页，提供功能导航
  • templates/db_compare.html: Cassandra比对界面
    • 支持单表、分表和多主键三种查询模式
    • 分表模式切换和参数配置
    • 实时查询日志和性能监控
  • templates/redis_compare.html: Redis比对界面
    • 集群配置和连接管理
    • 随机采样和指定Key两种查询模式
    • 全数据类型支持的结果展示
  • static/js/app.js: Cassandra查询的前端逻辑
    • 配置管理和表单处理
    • 分页展示和数据可视化
    • 多主键查询的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条件组合
  • 数据匹配算法：统一处理单主键和复合主键匹配
  • 向后兼容：完全兼容现有单主键查询

用户界面特性

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

开发相关命令

环境设置

# 安装依赖
pip install -r requirements.txt

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

# 开发模式启动（支持热重载）
# app.py中默认开启debug=True

# 生产环境运行
# 使用WSGI服务器如gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

测试和验证

# 主要通过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界面会自动创建数据库表结构

依赖项

  • Flask==2.3.3
  • cassandra-driver==3.29.1
  • redis==5.0.1

项目特点

  • 模块化架构：清晰的代码组织和职责分离
  • 双数据源支持：同时支持Cassandra和Redis数据比对
  • 智能查询引擎：针对不同数据源的优化查询策略
  • SQLite本地存储：配置组、查询历史和日志的本地持久化
  • 前端原生实现：使用原生JavaScript + Bootstrap，无现代前端框架依赖
  • 多模式支持：单表查询、分表查询、多主键查询、Redis比对的统一架构

API架构说明

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: 获取Cassandra查询历史
  • POST /api/query-history: 保存Cassandra查询历史
  • GET /api/query-history/<id>: 获取特定Cassandra历史记录
  • GET /api/query-history/<id>/results: 获取历史记录的完整结果数据
  • DELETE /api/query-history/<id>: 删除Cassandra历史记录
  • GET /api/query-logs: 获取查询日志（支持limit参数）
  • GET /api/query-logs/history/<id>: 获取特定历史记录的相关日志
  • DELETE /api/query-logs: 清空查询日志

查询比对流程

Cassandra单表查询流程（/api/query）：

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

Cassandra分表查询流程（/api/sharding-query）：

  1. 前端发送配置、Key值列表和分表配置到 /api/sharding-query
  2. 后端使用 sharding.py 中的 ShardingCalculator 解析Key中的时间戳
  3. 根据分表算法计算每个Key对应的分表名称
  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配置结构

单表查询配置：

{
  pro_config: {
    cluster_name, datacenter, hosts[], port, 
    username, password, keyspace, table
  },
  test_config: { /* 同上 */ },
  keys: ["主键字段名"],  // 支持多个字段，如 ["docid", "id"]
  fields_to_compare: ["字段1", "字段2"], // 空数组=全部字段
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"] // 单主键或复合主键值
}

分表查询配置：

{
  pro_config: { /* 基础配置同上 */ },
  test_config: { /* 基础配置同上 */ },
  keys: ["主键字段名"],  // 支持复合主键
  fields_to_compare: ["字段1", "字段2"],
  exclude_fields: ["排除字段"],
  values: ["key1", "key2", "key3"],  // 支持复合主键值
  sharding_config: {
    use_sharding_for_pro: true,    // 生产环境是否使用分表
    use_sharding_for_test: false,  // 测试环境是否使用分表
    interval_seconds: 604800,      // 分表时间间隔（默认7天）
    table_count: 14               // 分表数量（默认14张表）
  }
}

Redis配置结构

Redis集群配置：

{
  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匹配模式（可选）
  }
}

多主键查询格式示例：

// 复合主键配置
keys: ["docid", "id"]

// 复合主键查询值（逗号分隔）
values: [
  "8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED",
  "9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED"
]

查询结果结构

Cassandra查询结果：

{
  total_keys, pro_count, test_count,
  differences: [{ 
    key: {docid: "val1", id: "val2"}, // 支持复合主键对象
    field, pro_value, test_value, message 
  }],
  identical_results: [{ 
    key: {docid: "val1", id: "val2"}, // 支持复合主键对象
    pro_fields, test_fields 
  }],
  field_diff_count: { "field_name": count },
  raw_pro_data: [], raw_test_data: [],
  summary: { overview, percentages, field_analysis, recommendations },
  
  // 分表查询特有字段
  sharding_info: {
    pro_shard_mapping: { "key1": "table_name_0", "key2": "table_name_1" },
    test_shard_mapping: { /* 同上 */ },
    failed_keys: [], // 时间戳提取失败的Key
    shard_stats: {
      pro_tables_used: ["table_0", "table_1"],
      test_tables_used: ["table_0"],
      timestamp_extraction_success_rate: 95.5
    }
  }
}

Redis查询结果：

{
  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
}

开发注意事项

代码修改指导

  • 模块化开发：功能按模块组织，修改时注意模块间的依赖关系
  • 数据库模式变更：修改SQLite表结构需要考虑向后兼容性
  • 前端JavaScript：分别位于 static/js/app.js（Cassandra）和 static/js/redis_compare.js（Redis）
  • HTML模板：使用Jinja2模板引擎，主要文件在 templates/ 目录

关键模块和类位置

  • 主应用：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 - 查询日志系统

模块依赖关系

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数据库)

开发最佳实践

  • 错误处理：每个模块都有详细的错误分类和处理机制
  • 日志记录：使用统一的日志系统，支持不同级别的日志输出
  • 性能监控：查询时间和连接时间的详细统计
  • 配置管理：支持配置的导入导出和版本管理
  • 数据安全：敏感信息（密码）的安全处理