MySQL C API mysql_stmt_fetch 返回 MYSQL_DATA_TRUNCATED 怎么处理

使用 MySQL C API 读取预处理语句结果时，mysql_stmt_fetch() 返回 MYSQL_DATA_TRUNCATED，通常不代表 SQL 执行失败，而是某个绑定字段装不进当前缓冲区。正确处理方式是先定位哪个 MYSQL_BIND 被截断，再根据 length 取出完整长度；长字符串或 BLOB 则改用 mysql_stmt_fetch_column() 读取。

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

看到这个返回值时不要立刻中断整个结果集。检查每列的 error，用 length 判断真实字节数；能预估长度就扩大绑定缓冲区，无法预估就先探测长度，再按列取回。

先把 MYSQL_DATA_TRUNCATED 当作可定位状态

一次 mysql_stmt_fetch() 会把当前行的各列写入绑定数组。返回值为 0 表示本行按绑定成功写入，MYSQL_NO_DATA 表示结果集已经读完，返回 1 才是普通错误；MYSQL_DATA_TRUNCATED 介于两者之间，说明需要处理截断但当前行仍有可用数据。

定位时不要只看返回值。为每个绑定项准备 error、length 和 is_null，然后逐项判断：

• error[i] 为真：第 i 列发生了截断或转换层面的截断。
• length[i]：字符串或二进制列的非截断长度，单位是字节。
• buffer_length：当前缓冲区最多能接收多少字节；实际已经写入的长度可取两者较小值。
• is_null[i] 为真：这是 NULL，不要把缓冲区内容当成空字符串。

一个最小的判断骨架如下，示例只展示结果处理，不包含数据库连接与 SQL 准备。

int status;
/* 这些数组与 MYSQL_BIND 一一对应，便于定位具体列。 */
bool is_null[2] = {false, false};
bool truncated[2] = {false, false};
unsigned long length[2] = {0, 0};

/* 先取当前行，再分别判断空值、截断和实际长度。 */
status = mysql_stmt_fetch(stmt);
if (status == MYSQL_DATA_TRUNCATED) {
    /* error 只表示对应绑定项需要进一步处理。 */
    for (int i = 0; i 

上面的 truncated 必须实际绑定到每个 MYSQL_BIND.error，否则只能知道返回了截断，却不知道哪一列需要补救。

缓冲区大小决定了你能拿到多少内容

对字符或二进制列，buffer_length 是输出缓冲区的容量，length 则由 MySQL 在 fetch 后写回。若字段实际长度是 4096，而缓冲区只有 256 字节，返回 MYSQL_DATA_TRUNCATED 时，length 仍能告诉你完整值有多长；不要用 strlen() 推断 BLOB 的长度，也不要把被截断的文本直接当成完整业务值。

如果业务允许固定上限，最简单的方案是按长度上限分配缓冲区，并在绑定时为 buffer_length 写入真实容量。若长度超过上限，应显式记录“字段过长”，不要静默截断。数字和时间类型的长度由绑定类型决定，本文的动态补取方案主要针对字符串和 BLOB。

另外，读取循环不能因为一次截断就停止。处理完当前行后仍应继续调用 mysql_stmt_fetch()，直到返回 MYSQL_NO_DATA；否则未读完结果集就执行下一条语句，容易触发命令顺序错误。

长字段用 fetch_column 分块取回

无法预估字段大小时，可以让目标列先使用零长度缓冲区。第一次 fetch 的目标不是拿到内容，而是拿到 real_length；随后为该列分配足够内存，调用 mysql_stmt_fetch_column()。它针对当前结果集行的某一列取值，第一列的编号是 0，offset 从 0 开始。

MYSQL_BIND bind;
bool truncated = false;
bool is_null_value = false;
unsigned long real_length = 0;
char *data = NULL;

/* 清空绑定，先用零容量探测当前列的真实字节数。 */
memset(&bind, 0, sizeof(bind));
bind.buffer_type = MYSQL_TYPE_STRING;
bind.buffer = NULL;
bind.buffer_length = 0;
bind.length = &real_length;
bind.error = &truncated;

if (mysql_stmt_bind_result(stmt, &bind) != 0) {
    /* 绑定失败时不再继续 fetch，避免使用无效的结果布局。 */
    fprintf(stderr, "bind result failed: %s\n", mysql_stmt_error(stmt));
    return 1;
}

/* 这次 fetch 得到当前行各列状态和目标列真实长度。 */
int status = mysql_stmt_fetch(stmt);
if (status != 0 && status != MYSQL_DATA_TRUNCATED) {
    /* MYSQL_NO_DATA 或普通错误都不能进入动态取回分支。 */
    return status == MYSQL_NO_DATA ? 0 : 1;
}

if (!is_null_value && real_length > 0) {
    /* 多留一个字节，便于把文本作为 C 字符串使用。 */
    data = malloc(real_length + 1);
    if (data == NULL) {
        /* 分配失败必须先结束当前资源路径，再向上层报告。 */
        return 1;
    }
    memset(&bind, 0, sizeof(bind));
    bind.buffer_type = MYSQL_TYPE_STRING;
    bind.buffer = data;
    bind.buffer_length = real_length;
    bind.length = &real_length;

    /* 从当前行的第 0 个字节开始补取这一列。 */
    if (mysql_stmt_fetch_column(stmt, &bind, 0, 0) != 0) {
        free(data); /* 补取失败也要释放动态缓冲区。 */
        return 1;
    }
    data[real_length] = '\0'; /* 仅对文本场景添加 C 字符串结尾。 */
}
free(data); /* 业务处理完成后释放当前行的临时内存。 */

生产代码要根据实际列号、MYSQL_TYPE_BLOB 与 NULL 标志调整这段示例。对特别大的 BLOB，还可以按偏移分段调用 mysql_stmt_fetch_column()，每次把 offset 向后移动，避免一次申请整个值。

把返回码、资源和边界记录清楚

最后检查三件事：绑定数组数量与结果列数一致；每行都继续 fetch 到 MYSQL_NO_DATA；动态缓冲区、结果元数据和 statement 都按创建的反向顺序释放。这样既能保留长字段，也不会把一次可恢复的截断扩大成结果集不同步。

常见追问

返回 MYSQL_DATA_TRUNCATED 时能直接忽略吗？ 如果业务明确允许丢弃超长内容可以记录后忽略，但必须先确认哪些列被截断；对用户可见文本、签名、JSON 或 BLOB，通常应该补取或拒绝这行。

一定要调用 mysql_stmt_store_result() 吗？ 不一定。它用于把结果集整体缓存在客户端；是否调用取决于内存与访问方式。本文的截断定位和 mysql_stmt_fetch_column() 重点是正确绑定、读取当前行并继续消费结果集。