MySQL C API 缓冲结果集后怎么跳回指定行

我在做一个“结果集前后浏览”的 C API 小工具时，第一次踩坑不是行号算错，而是把未缓冲的结果集当成了可以回跳的数组。MySQL C API 里，mysql_stmt_data_seek() 只对已经由 mysql_stmt_store_result() 完整缓冲到客户端的预处理语句结果集生效。

实际写法可以压缩成四个动作：绑定结果缓冲区，调用 mysql_stmt_store_result()，把目标行号限制在 0 到 mysql_stmt_num_rows(stmt) - 1，再调用 mysql_stmt_data_seek() 并执行一次 mysql_stmt_fetch()。其中 offset 是零基行号，不是字节偏移，也不是从 1 开始的页码。

官方文档：https://dev.mysql.com/doc/c-api/8.4/en/mysql-stmt-data-seek.html

要跳回指定行，先把完整结果集留在客户端；mysql_stmt_data_seek 只负责改变当前行位置，真正把这一行写入列变量的动作仍然是 mysql_stmt_fetch。

为什么先缓冲，才能在结果集中回跳

预处理语句执行出结果后，默认是一次从服务器取一行。这个模式适合顺序消费，因为客户端不需要一次保存全部数据；但它没有一个可以任意索引的完整客户端结果集。mysql_stmt_store_result 的作用，就是在绑定结果缓冲区后，把本次查询的完整结果集准备在客户端。

这也解释了一个常见现象：如果跳过 mysql_stmt_store_result 直接调用 mysql_stmt_data_seek，问题不是 offset 写错，而是结果集根本不具备 seek 条件。官方文档明确要求，mysql_stmt_data_seek 只能与 mysql_stmt_store_result 一起使用。

最小调用关系：store、seek、fetch 各自做什么

下面的片段只保留定位所需的核心顺序。为了让示例可迁移，查询参数绑定部分用省略号表示，读者需要按自己的列类型补齐 MYSQL_BIND。

/* 假设 stmt 已完成 prepare、参数绑定和 execute。 */
MYSQL_BIND result_bind[2] = {0};
unsigned long id = 0;
char name[128] = {0};
unsigned long name_len = 0;

/* 把查询结果的两列绑定到本地缓冲区。 */
result_bind[0].buffer_type = MYSQL_TYPE_LONG;
result_bind[0].buffer = &id;
result_bind[1].buffer_type = MYSQL_TYPE_STRING;
result_bind[1].buffer = name;
result_bind[1].buffer_length = sizeof(name);
result_bind[1].length = &name_len;

if (mysql_stmt_bind_result(stmt, result_bind) != 0) {
    /* 绑定失败时不要继续使用未准备好的列缓冲区。 */
    return report_stmt_error(stmt);
}

/* 只有完整缓冲后，结果集才支持 data_seek。 */
if (mysql_stmt_store_result(stmt) != 0) {
    /* 这里通常需要记录内存不足或调用顺序错误。 */
    return report_stmt_error(stmt);
}

my_ulonglong total = mysql_stmt_num_rows(stmt);
my_ulonglong target = 5; /* offset 是从 0 开始的第 6 行。 */
if (target >= total) {
    /* 越界时不调用 data_seek，避免把不存在的行当成有效结果。 */
    mysql_stmt_free_result(stmt);
    return report_out_of_range(target, total);
}

/* 定位只改变当前行位置，仍需 fetch 才会更新 id/name。 */
mysql_stmt_data_seek(stmt, target);
int fetch_status = mysql_stmt_fetch(stmt);
if (fetch_status != 0 && fetch_status != MYSQL_DATA_TRUNCATED) {
    /* 读取失败时保留 stmt 错误信息，再释放客户端结果。 */
    mysql_stmt_free_result(stmt);
    return report_stmt_error(stmt);
}

/* name_len 是有效字符串长度，不能假设整个 name 缓冲区都有效。 */
consume_row(id, name, name_len);
mysql_stmt_free_result(stmt); /* 释放 store_result 占用的客户端内存。 */

这个调用关系里最容易混淆的是两件事：

• mysql_stmt_data_seek 没有返回值，它只改变结果集的当前位置。
• mysql_stmt_fetch 才会把当前位置对应的列值写入已经绑定的变量，因此 seek 后不能省略 fetch。

offset 怎么算，边界应该放在哪里

官方定义的 offset 范围是 0 到 mysql_stmt_num_rows(stmt) - 1。因此当结果总数为 10 时，有效行号是 0 到 9；用户界面若显示“第 1 行”，传给 API 的值应是 0。

我更建议把边界判断放在一个小函数里，而不是让每个“上一行/下一行/跳到末尾”按钮各自计算。这样能把 UI 的一基行号和 C API 的零基行号隔开：

/* 把界面使用的 1 基行号转换为 C API 使用的 0 基 offset。 */
int seek_display_row(MYSQL_STMT *stmt, unsigned long long display_row) {
    my_ulonglong total = mysql_stmt_num_rows(stmt);
    if (display_row == 0 || display_row > total) {
        /* 0 表示非法的界面行号，total 表示最后一行之外的位置。 */
        return 0;
    }

    my_ulonglong offset = (my_ulonglong)(display_row - 1);
    mysql_stmt_data_seek(stmt, offset);
    return mysql_stmt_fetch(stmt) == 0;
}

如果你的结果列可能被截断，fetch 返回值还要结合绑定结构中的长度和截断标记处理；不能把所有非零状态都当成“没有这一行”。但这属于取值缓冲区的处理，不改变 data_seek 的零基定位规则。

回跳的收益和代价：它不是服务端分页

缓冲结果集的收益是定位简单：客户端已经保留整批结果，前后浏览时不必重新构造 SQL，也不需要为每次回跳维护服务端分页条件。对结果集规模可控、需要反复浏览同一批记录的管理工具或导入预览，这个取舍很直接。

代价也同样直接：结果集越大，客户端需要承担的内存越多；mysql_stmt_store_result 还可能因为内存不足返回错误。对很大的表，不能因为想“跳到第 N 行”就把全表结果一次性缓冲。此时应该回到查询层设计稳定排序和服务端分页，而不是把 mysql_stmt_data_seek 当成通用分页 API。

我会在代码评审里重点看这四处

结论

mysql_stmt_data_seek 适合“已经在客户端缓冲、需要按行回看”的结果集。正确组合是 mysql_stmt_bind_result → mysql_stmt_store_result → 边界检查 → mysql_stmt_data_seek → mysql_stmt_fetch，结束后调用 mysql_stmt_free_result。

如果你的真正问题是大数据量分页，应该采用带稳定排序条件的 SQL 分页；如果只是交互式浏览一批有限结果，才适合用这个客户端定位能力。

相关问题

• mysql_stmt_data_seek 的 offset 是从 0 还是从 1 开始？ 从 0 开始，最大值是总行数减 1。
• 调用 data_seek 后还要调用 mysql_stmt_fetch 吗？ 要，data_seek 只改变位置，fetch 才把当前行写入绑定缓冲区。
• 没有调用 mysql_stmt_store_result 能否回跳？ 不能；该 API 要求结果集已经完整缓冲到客户端。
• 结果集很大时还适合用 data_seek 吗？ 通常不适合，应评估内存成本并考虑服务端分页。