MySQL C API 怎么根据引号类型转义 SQL 字符串

在维护 MySQL C API 的旧式 SQL 拼接代码时，最容易混淆的是：mysql_real_escape_string_quote() 的最后一个参数并不是“随便填一个引号”，而是要描述转义结果将放进哪一种 SQL 引号上下文。字符串放在单引号中就传 '，放在双引号中就传 "，如果处理的是反引号包围的标识符，则传 `。

官方地址：https://dev.mysql.com/doc/c-api/8.4/en/mysql-real-escape-string-quote.html

记住三个边界：quote 要和 SQL 外层写法一致；转义依赖已经打开连接的当前字符集；输出缓冲区至少按 length * 2 + 1 字节准备。能使用预处理语句时，优先让驱动绑定值，减少手工拼接。

quote 参数决定了哪一种引号需要重点转义

官方函数的职责是把 from 的字节内容编码到 to，生成可以放进 SQL 语句的字符串。它会处理反斜杠、单引号、双引号、NUL、换行、回车、Control+Z 和反引号等字符；其中真正决定“当前引号必须被转义”的，是最后的 quote 参数。

因此，下面三种 SQL 片段不能共用同一个假设：

先固定连接字符集，再准备输入和输出

转义不是脱离连接独立完成的字符串替换。MySQL 文档明确说明，函数需要一个有效且已打开的 MYSQL 连接，因为字符转义依赖服务器正在使用的字符集。若程序切换字符集，应调用 mysql_set_character_set()；仅执行 SET NAMES 不会同步改变该函数使用的字符集。

示例只展示参数关系和错误分支，实际项目仍应优先采用预处理语句：

#include 
#include 
#include 

int escape_value(MYSQL *mysql, const char *from, unsigned long from_len,
                 char *to, unsigned long to_cap) {
    // 最坏情况下每个输入字节都可能扩展为两个字节，并保留结尾的 NUL。
    if (to_cap 

这个函数不负责连接初始化，也不负责分配内存：调用方要保证 mysql 已连接、from_len 是字节长度而不是字符个数，并且 to 指向可写空间。返回值是转义后长度，不包含最后的空字节。

返回长度怎样接入查询缓冲区

拼接查询时，不能把转义后的内容当成普通 C 字符串而丢掉长度信息。返回长度既可用于继续移动写指针，也可用于计算最终传给 mysql_real_query() 的查询字节数。下面的示例把用户值放在单引号字符串中，并用指针差值得到查询长度：

char query[1024];
char escaped[2 * 256 + 1];
const char value[] = "O'Reilly\\notes";

// 先写入 SQL 固定部分，外层引号决定 quote 使用单引号。
char *cursor = query;
cursor += sprintf(cursor, "SELECT * FROM customer WHERE name = '");

// 输入长度按字节计算，返回长度不包含结尾 NUL。
unsigned long escaped_len = mysql_real_escape_string_quote(
    mysql, escaped, value, (unsigned long)strlen(value), '\'');
memcpy(cursor, escaped, escaped_len);
cursor += escaped_len;

// 补齐 SQL 的外层引号；mysql_real_query 接收明确的字节长度。
*cursor++ = '\'';
*cursor = '\0';
if (mysql_real_query(mysql, query, (unsigned long)(cursor - query)) != 0) {
    // 生产代码应记录错误上下文，并把连接/事务状态交给上层处理。
    fprintf(stderr, "query failed: %s\\n", mysql_error(mysql));
}

双引号、反引号和 ANSI_QUOTES 的兼容边界

如果 SQL 外层使用双引号，调用时把 quote 改为 "；如果是在动态标识符场景处理反引号，则传 `。这两个场景不能混为一谈：值是字符串，表名或列名是标识符，后续还要遵守标识符命名和白名单规则。

还要注意 ANSI_QUOTES SQL 模式。官方说明指出，mysql_real_escape_string_quote() 无法判断该模式是否开启，因此不能把它当成“双引号标识符”的自动适配器。若代码依赖双引号表示字符串或标识符，应在连接初始化阶段固定 SQL 模式，并把实际上下文作为明确的调用约定。

改造旧式拼接时的采用清单

• 值放在单引号中就传 '，双引号上下文就传 "，反引号只用于标识符。
• to 至少分配 length * 2 + 1 字节，并把长度按字节计算。
• 字符集切换使用 mysql_set_character_set()，不要以为执行 SET NAMES 就同步了客户端转义语义。
• 能使用 prepared statement 时，优先使用参数绑定；必须拼接标识符时采用白名单，不把用户输入直接当作表名或列名。

常见问题

quote 可以始终传单引号吗？

只有当转义结果始终放入单引号字符串时才可以。调用约定与 SQL 外层写法不一致，边界字符的转义就可能不符合目标语法。

为什么需要有效的 MYSQL 连接？

因为转义需要依据连接当前使用的字符集。没有有效连接时，函数无法获得正确的字符集语境。

这类函数适合维护已有的 C API 拼接代码，但新代码应把“值”和“SQL 结构”分开：值用预处理语句绑定，确实需要拼接的标识符用白名单控制，只有在无法迁移的旧路径上才精确使用 quote、长度和字符集约束。