C/C++ 連接 MySQL 時設置字符集的三種方法與最佳實踐

背景

在 C/C++ 中使用 MySQL C API 連接數據庫時，正確設置字符集至關重要，否則會導致中文亂碼、mysql_real_escape_string 轉義錯誤等問題。本文總結三種主流方法，對比優缺點並給出推薦方案。

方法一：mysql_set_character_set() —— 推薦首選

[cpp]
MYSQL *mysql = mysql_init(NULL);
mysql_real_connect(mysql, "host", "user", "pass", "db", 3306, NULL, 0);

// 設置連接字符集為 utf8（或 utf8mb4）
if (mysql_set_character_set(mysql, "utf8mb4")) {
    fprintf(stderr, "設置字符集失敗: %s\n", mysql_error(mysql));
}

優點

• 影響 mysql_real_escape_string()，確保轉義使用正確字符集。
• 支持自動重連（MYSQL_OPT_RECONNECT）後保持字符集設置。
• API 設計專門用於此目的，語義清晰。

限制

需 MySQL 5.0.5 或更高版本。

方法二：執行 SQL 語句 SET NAMES

[cpp]
const char *sql = "SET NAMES utf8mb4";
mysql_real_query(mysql, sql, (unsigned long)strlen(sql));

缺點

• 僅影響當前連接，斷線重連後字符集重置為默認值。
• 不影響 mysql_real_escape_string() 的行為，可能導致安全漏洞（如 SQL 注入）。
• 屬於「副作用式」設置，不如 API 直觀。

方法三：mysql_options() 設置 MYSQL_SET_CHARSET_NAME

[cpp]
// 必須在 mysql_real_connect() 之前調用！
mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "utf8mb4");
mysql_real_connect(mysql, ...);

特點

• 兼容舊版本（MySQL 5.0.5 以前亦可用）。
• 重連後保持字符集。
• 不影響 mysql_real_escape_string()。
• 關鍵限制：必須在 mysql_real_connect() 之前調用，否則無效。

對比總結表

最佳實踐建議

1. 優先使用 mysql_set_character_set(mysql, "utf8mb4")，並在連接屬性中開啟自動重連：
   mysql_options(mysql, MYSQL_OPT_RECONNECT, &(my_bool){1});
2. 若項目強制使用舊版 MySQL（< 5.0.5），改用 mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "utf8mb4") 並在連接前調用。
3. 永遠不要 僅依賴 SET NAMES，除非你確定不使用 mysql_real_escape_string 且不開啟自動重連。
4. 生產環境建議使用 utf8mb4 而非 utf8，以完整支持 Emoji 及補充字符平面。