简介这是一份面向MFC开发者的MySQL数据库连接示例工程基于ODBC方式实现适合需要在Windows桌面程序中集成数据库操作的C初学者也可供中级开发者参考。压缩包内共含38个文件涵盖C源文件、头文件、对话框资源、图标文件以及编译过程产生的obj、pdb、ilk等中间文件整体约3.54MB便于直接打开Visual C工程查看并运行。目前已有1663人学习下载具有一定的参考价值。工程以DatabaseTest项目为载体完整演示了从配置MySQL ODBC系统DSN、创建CDatabase对象连接数据库到使用CRecordset执行SQL查询与遍历记录再通过ExecuteSQL实现插入、更新、删除并配合事务处理与异常捕获。此外还包括界面交互逻辑和具体SQL命令实现非常适合对照学习MFC数据库编程的关键环节帮助读者快速掌握该类应用的标准开发流程。 接手过不少MFC老项目大家最头疼的往往不是界面逻辑而是怎么让程序和数据库好好说话。MFC连MySQL这个需求几乎隔三差五就有人问一次。有人卡在环境配置上有人被乱码折磨到怀疑人生还有人连基本的增删改查都跑不通。这篇文章我把自己这些年踩过的坑和验证过的方案整理出来从方案选型、环境搭建、核心代码到问题排查一条线讲透希望能让后来的人少走点弯路。1. 项目背景与方案选型1.1 为什么选择MFCMySQL组合MFC这套框架虽然年头不短了但在工业控制、上位机开发、企业内部工具这些领域存量项目依然庞大。很多设备管理软件、数据采集系统都是MFC写的要升级数据存储能力MySQL几乎是绕不开的选择。原因很直接MySQL免费、轻量、部署简单性能对于绝大多数桌面应用场景绰绰有余而且社区资料极其丰富遇到问题随便一搜就有答案。MySQL在中小型项目里的优势还体现在运维成本上。相比Oracle动辄几个G的安装包和复杂的配置流程MySQL的安装包精简得多配置也友好。对于MFC开发者来说很多时候目标机器就是客户现场的Windows主机MySQL的免安装版zip解压版可以直接随软件分发这一点在实际交付中特别实用。我经手的好几个项目就是把MySQL的data目录和mysqld.exe一起打进了安装包客户机器上一条命令就能启动服务完全不需要DBA介入。1.2 连接方式的对比选择MFC程序连MySQL常见路线有四条连接方式优点缺点适合场景MySQL C APIlibmysql.dll直接、高效、跨平台、文档齐全纯C接口需要手动管理资源绝大多数桌面应用推荐优先考虑MySQL Connector/C面向对象RAII管理连接依赖较多Visual Studio版本兼容性偶尔出问题新项目、团队熟悉C11及以上特性ODBCCDatabase/CRecordsetMFC原生支持数据集操作方便多一层ODBC驱动间接层部署时需额外装驱动需要同时兼容多种数据库的通用程序第三方封装库如MySQL封装完善API友好更新频率参差不齐引入额外依赖团队有长期维护计划我个人在MFC项目里通常直接用MySQL C API。理由很朴素它最稳定、最容易排查问题依赖就一个libmysql.dll链接时指定libmysql.lib即可。C API虽然是纯C函数但包一层C类之后完全不影响代码结构。而MFC自带的CDatabase走ODBC虽然和MFC风格统一但部署时要在客户机器上装MySQL ODBC驱动多一个环节就多一个出问题的点在现场排查起来特别麻烦。提示如果你接到的是老项目维护任务优先沿用项目里已有的连接方式。重构连接层属于“看起来简单实际上容易翻车”的改动除非有明确的性能或功能需求不建议顺手把数据库访问方式换掉。2. 环境搭建与开发前准备2.1 MySQL服务端的安装与配置要点开发机上的MySQL建议直接用官方安装包。需要注意的一点MySQL 8.0之后默认的认证插件是caching_sha2_password而老版本驱动特别是5.x系列的libmysql.dll不支持这个协议连接时会直接报Authentication plugin caching_sha2_password cannot be loaded之类的错误。如果你用的是MySQL 5.7或更老的驱动两种办法解决一是升级到MySQL 8.0配套的Connector/C版本二是在MySQL里把账号的认证插件改回mysql_native_passwordALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码; FLUSH PRIVILEGES;这个坑在论坛里反复出现基本都是版本匹配问题。建议开发前先确认好两件事MySQL服务端版本和Connector/C版本。最省心的组合是MySQL 8.0.x配Connector/C 8.0.x两边版本保持同步。2.2 在MFC工程中引入MySQL依赖库拿到MySQL安装目录后你需要关注三个东西include目录下的mysql.hlib目录下的libmysql.lib以及bin目录下的libmysql.dll。在MFC工程里配置步骤如下第一步在项目属性 - VC目录 - 包含目录中加上MySQL的include路径在库目录中加上lib路径。第二步在项目属性 - 链接器 - 输入 - 附加依赖项中填入libmysql.lib。第三步把libmysql.dll复制到项目的输出目录比如Debug或Release文件夹或者直接放到系统目录下。我习惯复制到工程目录下再设置一个生成后事件保证每次编译完dll都能自动拷贝到输出目录copy /Y $(SolutionDir)libs\mysql\lib\libmysql.dll $(OutDir)2.3 工程属性与编译环境的关键设置MFC工程默认使用“使用多字节字符集”和“使用Unicode字符集”两种模式这直接影响MySQL C API的使用方式。MySQL C API的mysql_real_connect函数接收的是const char*参数而Unicode工程里的CString默认是宽字符需要转换后才能传入。我在实践中推荐两种处理方式方式一是把整个工程的字符集设置为“使用多字节字符集”这样CString和const char*可以直接互转省掉大量字符串转换代码。缺点是不利于国际化。方式二是继续保持Unicode在调用MySQL API的地方手动转换。用CW2A宏或CT2A宏都可以CString strHost _T(127.0.0.1); CT2A asciiHost(strHost); mysql_real_connect(m_pMysql, asciiHost, ...);两种方式我都用过如果是老项目维护建议沿用项目原有字符集设置不要为了省事改全局配置。如果是新项目推荐Unicode 手动转换长期看更正规。3. 核心代码实现与原理拆解3.1 连接MySQL的完整流程MySQL C API的连接流程其实就三步初始化、建立连接、执行操作。但每一步都有容易忽略的细节我挨个说。初始化用mysql_init这一步会分配一个MYSQL结构体。网上很多教程直接定义一个MYSQL*指针就用了这是不严谨的。正确做法是MYSQL* mysql mysql_init(nullptr); if (!mysql) { // 内存分配失败 return; }mysql_init(nullptr)内部会自己分配MYSQL结构体。之后设置连接超时、字符集等参数最后调用mysql_real_connect。MYSQL* pMysql mysql_init(nullptr); // 设置连接超时时间单位秒防止网络异常时界面卡死 int nTimeout 5; mysql_options(pMysql, MYSQL_OPT_CONNECT_TIMEOUT, nTimeout); // 设置字符集放到连接前设置更稳妥 mysql_options(pMysql, MYSQL_SET_CHARSET_NAME, utf8mb4); if (!mysql_real_connect( pMysql, 127.0.0.1, // 主机地址 root, // 用户名生产环境不要用root password, // 密码 test_db, // 数据库名可以为null先不指定 3306, // 端口号 nullptr, // Unix socketWindows传nullptr 0 // 客户端标志一般填0 )) { // 连接失败用mysql_error获取原因 CString strError CA2T(mysql_error(pMysql)); AfxMessageBox(_T(数据库连接失败: ) strError); mysql_close(pMysql); return; }连接成功后mysql_real_connect内部已经把默认数据库切换到了test_db上如果指定了数据库名。这里有几个参数需要特别注意端口号必须和MySQL实际监听的端口一致默认3306但如果机器上装了多个实例或者改了配置很容易连错用户名和密码要确认权限root账号虽然开发时方便但交付给客户时一定得创建独立账号只授予必要库的权限避免安全隐患。3.2 增删改查操作的封装实现连上数据库后操作逻辑相对固定执行SQL语句、获取结果集、处理结果。MFC项目里我一般会把数据库操作封装成一个类比如CDbHelper把连接、查询、非查询操作分开。查询操作建议用mysql_store_result把结果一次性取回内存然后通过mysql_fetch_row逐行读取。对于桌面应用数据量通常不会大到内存装不下这个方案简单高效BOOL CDbHelper::Query(LPCTSTR lpszSQL, std::vectorstd::vectorCString vecResult) { if (!m_pMysql) return FALSE; // 统一转为utf8编码发送给服务器 USES_CONVERSION; const char* szSQL T2A(lpszSQL); if (mysql_query(m_pMysql, szSQL) ! 0) { // SQL执行失败记录错误日志 return FALSE; } // 获取结果集 MYSQL_RES* pResult mysql_store_result(m_pMysql); if (pResult) { // 获取列数 unsigned int nCols mysql_num_fields(pResult); MYSQL_ROW row; while ((row mysql_fetch_row(pResult))) { std::vectorCString vecRow; for (unsigned int i 0; i nCols; i) { // 注意row[i]可能为null表示数据库中的NULL值 vecRow.push_back(row[i] ? CA2T(row[i]) : _T()); } vecResult.push_back(vecRow); } mysql_free_result(pResult); } return TRUE; }写增删改时不建议直接拼接SQL字符串去执行特别是涉及用户输入的地方。经典的反例是CString sql; sql.Format(_T(SELECT * FROM user WHERE name %s), strName);这样写一旦strName里包含单引号或分号轻则报错重则被SQL注入。防注入的办法不是写更复杂的字符串处理而是用参数化查询——MySQL C API支持mysql_stmt_prepare和mysql_stmt_bind_param这一套预编译接口。虽然写起来比直接拼串麻烦但对需要处理用户输入的功能这一步不能省。MYSQL_STMT* pStmt mysql_stmt_init(m_pMysql); // 预编译SQL参数用?占位 const char* szSQL INSERT INTO t_user(name, age) VALUES(?, ?); mysql_stmt_prepare(pStmt, szSQL, strlen(szSQL)); MYSQL_BIND bindParams[2]; memset(bindParams, 0, sizeof(bindParams)); // 绑定name参数 char szName[64] { 0 }; strcpy_s(szName, 张三); bindParams[0].buffer_type MYSQL_TYPE_STRING; bindParams[0].buffer szName; bindParams[0].buffer_length strlen(szName); // 绑定age参数 int nAge 25; bindParams[1].buffer_type MYSQL_TYPE_LONG; bindParams[1].buffer nAge; mysql_stmt_bind_param(pStmt, bindParams); mysql_stmt_execute(pStmt); mysql_stmt_close(pStmt);3.3 中文乱码的处理中文乱码基本是MFC MySQL项目里出现频率最高的问题。乱码的根源无非是字符集链路中某个环节不一致。一条查询语句的字符集流转路径是客户端代码字符集 - MySQL客户端API字符集 - 连接字符集 - MySQL服务器字符集 - 表字段字符集。任何一环不一致结果就是乱码。我的经验是统一到utf8mb4第一步建表时明确指定字符集CREATE TABLE t_user ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64) NOT NULL ) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;第二步连接建立后立即设置字符集mysql_set_character_set(m_pMysql, utf8mb4);第三步确保MFC端的字符串能正确转换成UTF-8。这里有个细节T2A在不指定代码页时用的是系统默认ANSI代码页简体中文系统是GBK所以T2A转换后的字符串其实是GBK编码不是UTF-8。要让MySQL C API正确接收UTF-8得用WideCharToMultiByte指定代码页为CP_UTF8或者使用CT2A并指定代码页#include atlconv.h CString strName _T(张三); // 转换成UTF-8 int nLen WideCharToMultiByte(CP_UTF8, 0, strName, -1, nullptr, 0, nullptr, nullptr); char* szUTF8 new char[nLen]; WideCharToMultiByte(CP_UTF8, 0, strName, -1, szUTF8, nLen, nullptr, nullptr); // 执行SQL... delete[] szUTF8;注意mysql_set_character_set设置的是连接层的字符集如果你之前的表已经建成别的字符集比如latin1那么即使连接层改成utf8mb4也没用旧数据依然是乱码。唯一的根治办法是重新建表并迁移数据。4. 常见问题与排查技巧4.1 连接失败的三类高频原因我在处理大大小小的数据库连接故障时发现绝大多数无非三种情况服务没起来、账号密码不对、端口不通。服务没起来表现是报Cant connect to MySQL server on 127.0.0.1 (10061)。排查方法很简单任务管理器里看有没有mysqld.exe进程或者用命令行试mysql -uroot -p账号密码不对或权限不足报错一般是Access denied for user rootlocalhost (using password: YES)。这个在开发机好排查但在客户现场要注意MySQL默认只允许localhost和127.0.0.1连接。如果MFC程序跑在另一台机器上需要创建允许远程访问的账号CREATE USER app_user% IDENTIFIED BY password; GRANT SELECT, INSERT, UPDATE, DELETE ON test_db.* TO app_user%; FLUSH PRIVILEGES;端口不通报Cant connect through socket或Connection refused。先确认MySQL实际监听端口用netstat -ano | findstr 3306。如果这里空白说明MySQL进程没在监听如果显示的不是3306那就是配置文件my.ini里port被改过了代码里也得跟着改。4.2 64位与32位不匹配的坑MFC程序有x86和x64两种编译目标MySQL的Connector/C也分32位和64位。这里有个特别隐蔽的问题如果程序是x86编译的却链接了64位的libmysql.lib或者反过来在编译阶段可能不报错运行阶段加载dll时才崩溃或报Bad Image错误。解决办法是确保三个东西位数一致编译目标平台的位数、libmysql.lib的位数、libmysql.dll的位数。检查方法不复杂用Visual Studio自带的dumpbin工具dumpbin /headers libmysql.dll | findstr machine输出里会明确标出x86还是x64。在项目属性里把编译平台和库路径都统一好这个问题能提前规避。另外我遇到过几次现场报错程序在开发机跑得好好的拷到客户机器上就报找不到libmysql.dll。原因往往是客户机器上没装VC运行库或者动态库的搜索路径不对。最省心的做法是把libmysql.dll直接放在exe同目录下然后在代码里加载前设置好搜索路径。对于Visual C运行库的依赖把项目属性里的运行库改为/MT静态链接可以彻底解决代价是exe会变大一两百KB对于桌面工具完全可接受。4.3 内存释放与资源管理经验MySQL C API是纯C接口所有内存都要手动管理。最容易泄漏的两个地方MYSQL_RES结果集没有释放以及频繁mysql_init/mysql_close导致句柄泄漏。我习惯在封装类里统一处理CDbHelper::~CDbHelper() { if (m_pMysql) { mysql_close(m_pMysql); m_pMysql nullptr; } }查询操作里无论执行成功还是失败只要mysql_store_result成功返回了结果集指针最后必须mysql_free_result。我还见过一个更容易忽略的问题执行非查询语句比如UPDATE后虽然不用取结果集但最好检查一下mysql_affected_rows确认实际影响的行数符合预期if (mysql_query(m_pMysql, szSQL) ! 0) { // 出错处理 return FALSE; } my_ulonglong nAffected mysql_affected_rows(m_pMysql); if (nAffected 0) { // 有可能SQL没问题但条件不匹配这里打日志方便排查 }4.4 编码问题排查思路前面提到中文乱码的解决方案但真遇到乱码光设置字符集还不够得有系统的排查顺序。我的排查路径是这样的第一步先用MySQL命令行工具执行同样的SQL如果命令行也乱码问题在服务端或数据本身如果命令行正常问题在客户端代码。第二步看MFC程序里SQL语句发送前的实际字节。在关键位置加日志把SQL语句以十六进制输出确认中文部分在发送前已经是UTF-8编码// 调试辅助函数输出字节流 void DebugPrintHex(const char* pBuf, int nLen) { CString strDebug; for (int i 0; i nLen; i) { CString strByte; strByte.Format(_T(%02X ), (unsigned char)pBuf[i]); strDebug strByte; } OutputDebugString(strDebug); }第三步确认MySQL连接层的字符集。执行SHOW VARIABLES LIKE character_set%重点看character_set_client和character_set_connection这两个值应该和mysql_set_character_set设置的一致。这套排查法在绝大多数场景下都能定位到乱码的根源而且能快速区分是哪个链路出了问题。4.5 其他值得注意的实战细节MySQL 8.0默认启用了caching_sha2_password密码认证如果开发环境能连但客户环境连不上优先怀疑驱动版本。前面说过老版本Connector/C不支持新认证协议尽量把MySQL Connector/C升级到和服务器大版本一致。还有一个容易被忽略的是防火墙。Windows客户机上如果开着防火墙MFC程序作为客户端连接MySQL 3306端口默认出站连接通常没问题但如果MySQL跑在客户局域网内的另一台服务器上要在那台机器的防火墙入站规则里放行3306端口。这类问题现场排查时容易忽略报错信息会误导人以为是账号或密码的问题。如果程序需要在MySQL服务未启动时也能正常打开界面建议把数据库连接放到工作线程里连接超时设置短一些超时后弹提示框而不是在主线程里直接调用阻塞式连接。这能避免客户在服务异常时看到“程序假死”的糟糕体验。5. 实操过程与核心环节实现5.1 一个完整的MFC查询示例有了前面的基础我给出一个可以直接抄作业的完整流程。假设需求是界面上一个按钮点击后从MySQL的t_user表读取所有记录显示在CListCtrl里。头文件里的核心成员变量class CMyDialog : public CDialogEx { private: MYSQL* m_pMysql; BOOL ConnectDatabase(); void LoadUserList(); };连接函数实现BOOL CMyDialog::ConnectDatabase() { m_pMysql mysql_init(nullptr); if (!m_pMysql) return FALSE; // 设置字符集必须在连接前设置 mysql_options(m_pMysql, MYSQL_SET_CHARSET_NAME, utf8mb4); int nTimeout 3; mysql_options(m_pMysql, MYSQL_OPT_CONNECT_TIMEOUT, nTimeout); if (!mysql_real_connect(m_pMysql, 127.0.0.1, root, 123456, test_db, 3306, nullptr, 0)) { CString strError CA2T(mysql_error(m_pMysql)); AfxMessageBox(_T(连接失败) strError); mysql_close(m_pMysql); m_pMysql nullptr; return FALSE; } return TRUE; }加载数据函数void CMyDialog::LoadUserList() { if (!m_pMysql) return; const char* szSQL SELECT id, name, age FROM t_user ORDER BY id; if (mysql_query(m_pMysql, szSQL) ! 0) { AfxMessageBox(CA2T(mysql_error(m_pMysql))); return; } MYSQL_RES* pResult mysql_store_result(m_pMysql); if (!pResult) return; // 清空列表 m_ListCtrl.DeleteAllItems(); // 插入数据 MYSQL_ROW row; int nIndex 0; while ((row mysql_fetch_row(pResult))) { CString strID CA2T(row[0]); CString strName row[1] ? CA2T(row[1]) : _T(); CString strAge row[2] ? CA2T(row[2]) : _T(); m_ListCtrl.InsertItem(nIndex, strID); m_ListCtrl.SetItemText(nIndex, 1, strName); m_ListCtrl.SetItemText(nIndex, 2, strAge); nIndex; } mysql_free_result(pResult); }这套代码比较朴素胜在结构清晰方便基础上扩展。5.2 线程中访问数据库的注意点MFC程序的界面操作通常在UI线程但数据库查询如果数据量大、表结构复杂UI线程会卡顿。这时候要把查询放到工作线程但MySQL的C API默认不是线程安全的。一个连接在同一时间只能在一个线程里使用。如果多个线程要并发访问数据库最稳妥的方案是每个线程维护自己的MYSQL*连接而不是共享一个连接。我在一个数据采集上位机项目里就吃过共享连接的亏界面卡得没法看。改成“每线程独立连接”之后问题立刻消失。如果你不想每线程都重新连一次数据库可以用连接池的思路——维护一组连接每次从池里取一个空闲连接用完归还。这个方案实现起来有点工作量但对于MFC这种场景简单起见每线程一个连接往往已经够用。5.3 调试数据库代码的几个实用技巧调试MFC连接MySQL的代码最直接的手段是OutputDebugString配合DBMON或Visual Studio的输出窗口。我自己习惯在关键位置输出三类信息SQL语句内容、错误码、错误文本。其中SQL语句里如果带参数一定要把参数填充后的完整SQL打出来否则你很难判断是拼接问题还是执行问题。再就是善用mysql_errno和mysql_error。mysql_error返回的文本信息很详细但它是英文的现场客户看不懂。我通常在debug日志里输出原始错误信息在界面上弹窗时输出自己定义的中文提示并附带错误码// 错误码对应的常见原因映射 switch (mysql_errno(m_pMysql)) { case 1045: // Access denied strUserMsg _T(账号或密码错误); break; case 1049: // Unknown database strUserMsg _T(数据库不存在); break; case 2003: // Cant connect strUserMsg _T(无法连接到数据库服务器请确认服务已启动); break; default: strUserMsg CA2T(mysql_error(m_pMysql)); break; }把错误码翻译成用户能看懂的语言比直接抛一个英文的Unknown column xxx in field list强太多。这对客户现场排查问题特别有帮助。6. 写在最后的几个经验MFC连MySQL这件事技术门槛其实不高但牵扯的细节特别多。回头看我做过的这些项目真正坑人的往往不是API用错了而是环境不匹配、字符集混乱、资源泄漏这些问题。写代码之前先把字符集方案定下来把动态库的位数和依赖关系理清楚后面能省一大半精力。如果遇到同样的问题建议先按我的排查顺序走一遍确认服务在跑、确认账号权限、确认端口通、确认位数一致、确认字符集统一。80%的问题都出在这几个环节。最后再分享一个小技巧给项目写一个简单的数据库自检工具界面上就三个按钮——“测试连接”、“查询当前时间”、“查看版本号”。交付给客户时一并带上出了问题先让客户点一下比远程桌面来回折腾高效得多。这个小工具看起来不起眼但实际现场维护时帮过我太多次了。本文还有配套的精品资源点击获取