第4章 预编译语句与绑定参数优化：SQLiteStatement使用、参数绑定减少解析开销

4.1 原理：SQL解析开销从何而来

每次执行 INSERT 或 UPDATE 语句时，SQLite 引擎需要完成以下步骤：

1. 词法分析——将SQL字符串拆解为；
2. 语法分析——构建抽象语法树(AST)；
3. 查询规划——选择最优索引与执行策略；
4. 代码生成——生成虚拟机操作码(VDBE)；
5. 执行——在虚拟机中运行操作码并返回结果。

对于蓝牙批量写入（如一次扫描捕获 200 台设备），若每条记录都走完整 5 步，解析开销占总耗时的 70% 以上。预编译语句将 步骤 1~4 只执行一次，后续仅通过参数绑定送入新数据，直接进入步骤 5 执行。

4.2 SQLiteStatement API 详解

Android 平台通过 SQLiteStatement 封装预编译能力，核心 API 如下：

4.3 实现流程：蓝牙扫描记录批量写入

以下是标准实现流程，以蓝牙扫描结果批量持久化为例：

1. 准备SQL模板：使用 ? 占位符代替所有可变字段；
2. 编译语句：调用 db.compileStatement(sql) 获得 SQLiteStatement 实例；
3. 开启事务：db.beginTransaction() 将批量写入包裹在事务中，避免单条提交开销；
4. 循环绑定与执行：每条记录依次调用 clearBindings() → bindXxx() → executeInsert()；
5. 事务提交：setTransactionSuccessful() + endTransaction()；
6. 释放资源：stmt.close() 在 finally 中保证执行。

4.4 代码实现：两种方式对比

❌ 低效方式：每次拼接SQL并执行完整解析

public void insertDevicesNaive(List<ScanResult> results) {
    SQLiteDatabase db = dbHelper.getWritableDatabase();
    for (ScanResult r : results) {
        String sql = "INSERT INTO scan_log(address, rssi, timestamp) VALUES('"
                + r.address + "', " + r.rssi + ", " + System.currentTimeMillis() + ")";
        db.execSQL(sql);  // 每次完整解析
    }
}

✅ 高效方式：预编译 + 参数绑定 + 事务

public void insertDevicesBatch(List<ScanResult> results) {
    SQLiteDatabase db = dbHelper.getWritableDatabase();
    String sql = "INSERT INTO scan_log(address, rssi, timestamp) VALUES(?, ?, ?)";
    SQLiteStatement stmt = db.compileStatement(sql);

    db.beginTransaction();
    try {
        for (ScanResult r : results) {
            stmt.clearBindings();
            stmt.bindString(1, r.address);
            stmt.bindLong(2, r.rssi);
            stmt.bindLong(3, System.currentTimeMillis());
            long rowId = stmt.executeInsert();
            if (rowId == -1) {
                // 写入失败处理（如日志记录）
            }
        }
        db.setTransactionSuccessful();
    } finally {
        db.endTransaction();
        stmt.close();  // 确保释放预编译资源
    }
}

4.5 性能实测数据

在 Pixel 6 / Android 13 上，写入 2000 条蓝牙扫描记录（每条含 address、name、rssi、timestamp、txPower 五个字段）：

预编译 + 参数绑定不仅降低 CPU 解析开销，还显著减少内存分配与 GC 压力，这对蓝牙设备上频繁的扫描-存储循环至关重要——GC 停顿会直接导致扫描回调延迟、丢包甚至 BLE 连接断开。

4.6 调试与验证方法

可以使用 SQLite 内置的 sqlite3_stmt 状态跟踪或 Android 的 DatabaseUtils 辅助调试：

// 启用 SQLite 日志，观察预编译命中情况
adb shell setprop log.tag.SQLiteStatements VERBOSE

// 在代码中打印执行计划，确认是否命中预编译
String sql = "INSERT INTO scan_log VALUES(?, ?, ?)";
SQLiteStatement stmt = db.compileStatement(sql);
// 通过 explain 查询验证
Cursor c = db.rawQuery("EXPLAIN " + sql, null);
while (c.moveToNext()) {
    Log.d("SQLitePlan", c.getString(0) + " | " + c.getString(1));
}
c.close();

在 logcat 中过滤 SQLiteStatements，如果看到大量 prepare/finalize 日志，说明预编译未正确复用，需要检查 compileStatement 是否被放在了循环内部。

4.7 常见错误与避坑指南

4.8 本章小结与性能基线

• 核心原则：固定模板的 SQL 语句，优先使用预编译 + 参数绑定，避免字符串拼接；
• 事务捆绑：批量写入必须与 beginTransaction 配合，预编译与事务是“双引擎”，缺一不可；
• 资源生命周期：SQLiteStatement 使用完毕后必须在 finally 中 close()，防止 native 内存泄漏；
• 性能基线：蓝牙扫描记录批量写入应达到 单条 < 50 μs，若超过 200 μs 说明预编译或事务未生效。