readme

readme.md

@@ -0,0 +1,229 @@
+# odbtools / odbctest 测试工具梳理报告
+
+**生成时间:** 2026-05-10 15:50 CST
+
+---
+
+## 一、总览
+
+odbtools 是 odbserver 的配套工具集，包含 MQL 测试框架、数据同步、REST API 测试等模块。
+
+| 模块 | Go文件 | 行数 | MQL测试文件 | 功能 |
+|------|--------|------|------------|------|
+| odbctest/odbcmql | 9 | 3,214 | — | **MQL测试框架核心** |
+| odbctest/mql | 1 | 15 | **899** | MQL测试用例入口+用例集 |
+| datasync | 3 | 897 | — | 数据同步工具 |
+| restapi | 2 | 282 | — | REST API 测试 |
+| syslog | 1 | 117 | — | 系统日志工具 |
+| omtool | 1 | 6 | — | 工具接口定义 |
+| **合计** | **17** | **4,531** | **899** | |
+
+---
+
+## 二、odbctest — MQL 测试框架（核心）
+
+### 2.1 框架架构
+
+```
+odbctest/
+├── odbcmql/          # 测试框架核心引擎（9文件，3,214行Go代码）
+│   ├── mql_run.go         # 主引擎：文件遍历→解析→执行→断言（~1100行）
+│   ├── mql_prepare.go     # MQL预处理：变量替换、动作解析
+│   ├── mqls_action.go     # 动作定义与解析（/** ... **/ 标注块）
+│   ├── mqls_do.go         # 执行器：发送MQL到odbserver
+│   ├── mqls_doaction.go   # 执行后动作处理（output/count/match/schema等）
+│   ├── mqls_match.go      # 结果匹配/断言逻辑
+│   ├── mqls_sub.go        # 订阅/通知机制
+│   ├── mql_odbc_query.go  # ODBC查询封装
+│   └── cfglog.go          # 日志配置
+│
+└── mql/              # 测试用例入口 + MQL脚本集
+    ├── mql_test.go       # Go test入口（15行）
+    ├── mql.conf          # 配置文件（odbpath/keyspace/timeout）
+    ├── mqltest.sh        # Shell启动脚本
+    └── {test_suites}/    # 899个 .mql 测试文件
+```
+
+### 2.2 运行方式
+
+```bash
+# 方式1: Go test
+go test -v -run TestMQL ./odbctest/mql/ -- ./
+
+# 方式2: 预编译的 mql 二进制
+./mql .                           # 循环执行当前目录所有匹配的mql文件
+./mql basic/10basic               # 执行指定目录
+./mql . match=^\d+                # 文件名匹配过滤
+./mql -- "select * from /test"   # 直接执行mql语句
+```
+
+**关键参数：**
+- `odb=ip:port` — 指定odbserver地址
+- `keyspace=xxx` — 指定keyspace
+- `match=正则` — 文件名过滤（默认 `^\d+.*` 即以数字开头）
+- `debug=true` — 调试模式
+
+### 2.3 MQL 测试文件格式
+
+每个 `.mql` 文件包含一条或多条 MQL 语句，语句间用 `;` 分隔。通过 `/** ... **/` 标注块附加执行控制指令。
+
+```sql
+-- 示例：创建类+插入数据+查询验证
+create class if not exists /test/basic (
+    v_int int, v_varchar text,
+    keys(v_varchar)
+) with core=cassandraonly;
+
+insert into /test/basic (v_int, v_varchar) values (5, 'hello')
+/** sleep(3s) **/;
+
+select v_int, v_varchar from /test/basic where v_varchar = 'hello'
+/** output() match(v_int, 5) **/;
+```
+
+### 2.4 标注动作（Actions）体系
+
+**执行前动作：**
+| 动作 | 功能 |
+|------|------|
+| `skip()` | 跳过当前语句 |
+| `params(V)` | 为 prepare 语句提供 JSON 参数 |
+| `loop(N)` | 循环执行 N 次 |
+| `parallel(N)` | 并发执行，N为最大并发数 |
+| `scope(S)` | 作用域：top/dir/file/mql |
+| `timeout(D)` | 超时设置 |
+| `set(S,V)` / `add(S,V)` | 变量操作 |
+| `beforerun(F,...)` | 执行前预定义函数 |
+| `subscribe(S)` / `unsubscribe(S)` | 消息订阅 |
+| `fork(G)` / `wait(G)` | 并行分支控制 |
+| `qmeta(O)` | 查询选项设置 |
+
+**执行后动作（断言/验证）：**
+| 动作 | 功能 |
+|------|------|
+| `output()` | 输出执行结果 |
+| `outputcount()` | 输出结果行数 |
+| `count(N)` | 验证结果记录数为 N |
+| `equal(N,F,V)` | 验证第N条记录字段F的值为V |
+| `match(K,V)` | 验证存在键值匹配的记录 |
+| `matchcount(K,V,N)` | 验证键值匹配记录数为N |
+| `schema(C)` | 验证类C存在 |
+| `sleep(D)` | 执行后等待 |
+| `metainfo()` | 输出元信息 |
+
+**错误处理动作：**
+| 动作 | 功能 |
+|------|------|
+| `retry(N)` | 出错重试N次 |
+| `onerror(O,E)` | 错误处理：break/continue/must/exit |
+| `noerrinfo()` | 屏蔽错误输出 |
+
+### 2.5 变量替换系统
+
+MQL语句中的 `{%fmt,varname}` 会被替换为对应变量值：
+
+| 变量 | 含义 |
+|------|------|
+| `{%d,topi}` / `{%d,diri}` / `{%d,filei}` / `{%d,mqli}` | 各级循环计数 |
+| `{%d,topcount}` / `{%d,dircount}` / `{%d,filecount}` / `{%d,mqlcount}` | 各级总计数 |
+| `{%s,keyspace}` / `{%s,ksnative}` | keyspace名 |
+| `{%d,rand}` | 0~1000000随机数 |
+| `{%t,now}` | 当前时间 |
+
+---
+
+## 三、测试用例分布（899个MQL文件）
+
+| 测试套件 | 文件数 | 测试范围 |
+|----------|--------|---------|
+| **basic/** | 479 | 基础功能全覆盖（最大测试集） |
+| **test/** | 143 | 专项测试（冲突/缓存/分区/压力/事件等） |
+| **uino/** | 83 | UINO相关测试 |
+| **0/** | 58 | 根级散列测试（MQL函数/JSON/搜索等） |
+| **bench/** | 48 | 性能基准测试 |
+| **problem/** | 26 | 已知问题回归测试 |
+| **matrix/** | 21 | 矩阵相关测试 |
+| **basic_scenario/** | 11 | 场景化集成测试 |
+| **create/** | 11 | 并发建类测试 |
+| **uino72/** | 7 | UINO v72测试 |
+| **notify/** | 6 | 消息通知测试 |
+| **auth/** | 4 | 认证授权测试 |
+| **bgrimm/** | 1 | 后台IMM测试 |
+| **vector/** | 1 | 向量检索测试 |
+
+### basic/ 核心测试集细分（479文件）
+
+| 子模块 | 说明 |
+|--------|------|
+| 00init / 01clear | 初始化与清理 |
+| 10basic | 基础CRUD（class/data/valid/field/int/bool/enum） |
+| 10cachedb | 缓存数据库 |
+| 10index | 索引 |
+| 10memdb / 10memdbexpired | 内存数据库及过期 |
+| 10native | Native查询 |
+| 10order | 排序 |
+| 10pubsub | 发布订阅 |
+| 11cacheonly / 11cncachedb / 11cncassdb / 11cnmemdb | 不同存储后端数据源 |
+| 11collect / 11localdb | 数据收集与本地库 |
+| 12datetime | 日期时间 |
+| 13delete / 13tuihualei | 删除与退花类 |
+| 14enum | 枚举类型 |
+| 15oo | 面向对象 |
+| 16alter | 类结构变更 |
+| 17cypher / 17xbase.select | Cypher语法/xbase查询 |
+| 18batch_insert / 19batch_update / 20batch_delete | 批量操作 |
+| 21~24 bucket_* | 时序桶(logs/strulogs/tsdb/promdb) |
+| 25~27 ckey/concat | 组合键 |
+| 30conflict* | 冲突处理（标准/缓存/本地/内存） |
+| 31~37 seq/uuid/network/partition/mpartition/prepare_* | 序列键/UUID键/网络/分区/预编译 |
+| 40~42 search_* | 全文检索 |
+| 49mix | 混合场景 |
+| 51tempclass / 52ootest | 临时类/OO测试 |
+| 98syntax / 99cassdb / 99ver | 语法/Cassandra/版本 |
+
+---
+
+## 四、其他工具模块
+
+### 4.1 datasync（数据同步）
+- 3个Go文件，897行
+- 功能：从源odbserver同步数据到目标odbserver
+- 入口：`datasync/main.go`
+
+### 4.2 restapi（REST接口测试）
+- 2个Go文件，282行
+- `rest.go`：封装HTTP请求+JSON解析+状态校验
+- `insert_test.go`：REST插入测试
+
+### 4.3 omtool（工具接口）
+- 1个Go文件，6行
+- 定义统一的工具接口 `OMTool`（Init/Run）
+
+### 4.4 syslog（系统日志）
+- 1个Go文件，117行
+- 系统日志采集/监控
+
+---
+
+## 五、依赖关系
+
+```
+odbtools
+  ├── git.wecise.com/wecise/odb-go   (数据库SDK)
+  ├── gitee.com/wecisecode/util       (开源工具库)
+  ├── github.com/stretchr/testify     (测试断言)
+  ├── github.com/gofrs/flock          (文件锁)
+  └── (传递依赖)
+      ├── git.wecise.com/wecise/common
+      └── git.wecise.com/wecise/util
+```
+
+---
+
+## 六、关键发现
+
+1. **测试体系完善** — 899个MQL测试文件，覆盖CRUD、缓存、冲突、分区、全文检索、批量操作等几乎所有功能领域
+2. **测试框架设计精巧** — 通过 `/** action() **/` 标注块实现声明式断言，支持循环、并发、作用域、变量替换、错误处理
+3. **basic/ 是最大测试集** — 479个文件覆盖基础功能，test/ 专注边界和异常场景
+4. **生产可用** — 有 `problem/`（回归测试）、`bench/`（性能基准）、`test/stress_*`（压力测试）等生产级质量保障
+5. **框架代码量小** — 核心引擎仅3,214行Go代码，支撑了899个测试用例的执行