From 8d7c4e37305fa1e8424e2d32ef37740946482ac0 Mon Sep 17 00:00:00 2001 From: YoVinchen Date: Tue, 12 Aug 2025 16:27:21 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=A8=A1=E7=89=88=E5=86=85?= =?UTF-8?q?=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 394 ------------------------------------------------------ 1 file changed, 394 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 1bd9f56..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,394 +0,0 @@ -# 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执行日志，支持日志级别过滤 - -## 开发相关命令 - -### 环境设置 -```bash -# 安装依赖 -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 -``` - -### 测试和验证 -```bash -# 主要通过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/`: 获取特定Cassandra配置组 -- `DELETE /api/config-groups/`: 删除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/`: 获取特定Redis配置组 -- `DELETE /api/redis/config-groups/`: 删除Redis配置组 -- `GET /api/redis/query-history`: 获取Redis查询历史 -- `POST /api/redis/query-history`: 保存Redis查询历史 -- `GET /api/redis/query-history/`: 获取特定Redis历史记录 -- `DELETE /api/redis/query-history/`: 删除Redis历史记录 - -### 通用API端点 -- `POST /api/init-db`: 初始化SQLite数据库 -- `GET /api/query-history`: 获取Cassandra查询历史 -- `POST /api/query-history`: 保存Cassandra查询历史 -- `GET /api/query-history/`: 获取特定Cassandra历史记录 -- `GET /api/query-history//results`: 获取历史记录的完整结果数据 -- `DELETE /api/query-history/`: 删除Cassandra历史记录 -- `GET /api/query-logs`: 获取查询日志（支持limit参数） -- `GET /api/query-logs/history/`: 获取特定历史记录的相关日志 -- `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配置结构 - -**单表查询配置**： -```javascript -{ - 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"] // 单主键或复合主键值 -} -``` - -**分表查询配置**： -```javascript -{ - 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集群配置**： -```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 -// 复合主键配置 -keys: ["docid", "id"] - -// 复合主键查询值（逗号分隔） -values: [ - "8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED", - "9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED" -] -``` - -### 查询结果结构 - -**Cassandra查询结果**： -```javascript -{ - 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查询结果**： -```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 -} -``` - -## 开发注意事项 - -### 代码修改指导 -- **模块化开发**：功能按模块组织，修改时注意模块间的依赖关系 -- **数据库模式变更**：修改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数据库) -``` - -### 开发最佳实践 -- **错误处理**：每个模块都有详细的错误分类和处理机制 -- **日志记录**：使用统一的日志系统，支持不同级别的日志输出 -- **性能监控**：查询时间和连接时间的详细统计 -- **配置管理**：支持配置的导入导出和版本管理 -- **数据安全**：敏感信息（密码）的安全处理 \ No newline at end of file