# 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个测试用例的执行