简介这是一份基于Visual Studio 2010的MFC对话框应用示例解决MFC项目中接入SQLite3数据库的问题。代码涵盖添加、删除、修改与查询等基础CRUD操作并特别演示了通过回调函数处理查询结果的方式适合刚开始接触MFC数据库编程的Windows开发者参考。压缩包共38个文件大小约7.01MB除h/cpp源码和sln/vcxproj等工程文件外还包含exe可执行程序、dll/lib运行库、db/sql数据库文件以及pdb调试信息可对照运行和断点学习。已有1338人学习下载可先运行Release目录中的exe体验效果再结合源码理解sqlite3_open、sqlite3_exec、sqlite3_close及错误处理等关键接口。示例还给出查询时带回调函数的写法便于处理逐行返回的大数据量结果同时涉及同步查询与后台异步查询的区分对理解MFC界面线程与数据库操作的配合也有帮助。1. MFC工程要用sqlite3先想清楚这三件事MFC工程要用sqlite3问得最多的其实不是SQL语法而是怎么把这堆C接口接进MFC的Unicode字符串、资源管理和多线程背景下。过去做MFC工具存配置常写ini数据一多、查询一复杂就顶不住换用sqlite3后一台电脑不用装数据库服务一个.db文件全搞定特别适合离线工具、内部管理系统和小型桌面客户端。这篇笔记按一套可复现的MFCsqlite3例子的落地过程来写先解决编译连接和字符集再封装数据访问层然后给增删改查和二进制存取的范例最后把最容易踩的坑挨个点名。适合刚开始在MFC里试点SQLite的开发者也适合准备从文件型存储切到关系型存储的熟手照着步骤走完基本能拿到一套能直接改来用的骨架。2. 接入sqlite3源码、字符集与三个配置关键点2.1 源码编译还是DLL按分发场景选接触过sqlite3的人都知道官方给的接入姿态非常灵活但落到MFC工程里无非两条路。方式A把sqlite3.c、sqlite3.h拖进工程当成普通源文件参与编译方式B链接预编译好的sqlite3.dll和配套lib。两者在调用层没有任何区别都是sqlite3_open、sqlite3_prepare_v2那一套API真正拉开差距的是运行时依赖和调试体验。大部分时候我推荐源码编译方式。第一交付时只带一个exe给同事拷工具不怕漏带DLL第二断点能直接进sqlite3的C源码遇到SQLITE_BUSY、SQLITE_CORRUPT这类返回码时可以直接看内部状态第三SQLITE_THREADSAFE这种编译期选项完全由自己控制不会被预编译包预设的值带偏。缺点只有一个工程编译时间会多个十几秒到几十秒日常开发完全能接受。DLL方式适合对exe体积敏感、或者团队里已经有统一DLL组件库的场景。用它省了编译时间但多出来的是部署心智调试时偶尔会遇到“明明DLL放在exe旁边程序还是报找不到”的灵异现场。这类问题通常出在VS调试目录没有指向exe输出目录或者系统PATH里捡到了一个旧版本DLL排查起来特别消耗耐心。决策项源码编译DLL方式交付文件单个exeexe sqlite3.dll调试排错断点可进sqlite3源码只能看接口返回码编译宏控制完全可控取决于DLL编译者配置构建时间增加不多无增加部署隐患少注意搜索顺序和版本混用2.2 MFC字符集与sqlite3的UTF-8契约这一节是整套例子里最容易被忽略的部分。MFC工程默认按Unicode字符集编译CString底层是UTF-16LE宽字符而sqlite3对外文本接口统一按UTF-8处理sqlite3_open的第一个参数、sqlite3_bind_text的文本参数、sqlite3_column_text返回的字符串全部默认视为UTF-8。两端编码不一致强制转换不做的话结果就是中文路径打不开数据库、中文数据写入后再读变成问号。处理思路是在数据访问层统一做转换而不是在业务代码里到处写转码。打开数据库时标准写法是这样的CString dbPath _T(D:\\工具数据\\local.db); // CW2A 将 UTF-16 宽字符 CString 转为 UTF-8 的 CStringA CStringA utf8Path CW2A(dbPath, CP_UTF8); sqlite3* db nullptr; int rc sqlite3_open(utf8Path, db); if (rc ! SQLITE_OK) { // sqlite3_errmsg 返回的也是 UTF-8展示前要逆转换成宽字符 CString errMsg CStringFromUtf8(sqlite3_errmsg(db)); AfxMessageBox(errMsg); if (db) { sqlite3_close(db); db nullptr; } }逻辑说明sqlite3_open要求UTF-8路径这里先用CW2A把宽字符CString转成CStringA再交给接口。错误信息从sqlite3_errmsg返回时同样是UTF-8编码里面的中文在弹窗前必须转回宽字符否则对话框里全是乱码。参数说明CP_UTF8是Windows代码页常量表示按UTF-8编解码sqlite3_errmsg返回的是连接内部的静态缓冲区不需要手动释放但拿到指针后要尽快转存后续任何sqlite3调用都可能覆盖它。如果工程里同时存在CStringA和CStringW的混用建议把两个方向的转换收拢成独立函数业务层只认这两个入口// 宽字符 CString - UTF-8 CStringA CStringA Utf8FromCString(const CString text) { return CW2A(text, CP_UTF8); } // UTF-8 char* - 宽字符 CString CString CStringFromUtf8(const char* utf8Text) { return CA2W(utf8Text, CP_UTF8); }这两个函数放进公共工具模块后后面所有sqlite3相关调用都走它们编码问题基本就隔离了。2.3 工程配置的三个关键点把sqlite3源码加进MFC工程后还有三个配置细节要检查到位。第一预编译头处理。MFC工程默认开了预编译头sqlite3.c直接加进去如果没做处理编译时会报“无法找到预编译头文件”。解决办法是选中sqlite3.c在属性页里把它单独设成“不使用预编译头”或者干脆在sqlite3.c顶部的宏定义区域加一句强制跳过预编译头。我一般选前者改文件不如改工程配置。第二字符集设置。工程属性里的“字符集”如果是“使用Unicode字符集”上面第2.2节的转换代码原样可用如果项目老还停留在“使用多字节字符集”这时候CString本身是CStringACW2A依然能编译但中间会绕一次从char到wchar再到char的转换白耗性能。多字节工程里直接用char* sqlite3_bind_text反而更直接。第三SQLITE_THREADSAFE宏。sqlite3的线程模式在编译期决定。源码编译时系统默认值是1即串行模式多线程调用安全但同一时刻只有一个线程能进入sqlite3内部操作如果链接的DLL当初以SQLITE_THREADSAFE0编的那你在线程池里同时调用就可能崩。我在工程属性里加了一条预处理定义SQLITE_THREADSAFE1强制走串行模式后续在后台线程里操作数据库省心得多。2.4 最小验证建表并确认返回值配置全部完成后先做一个最小验证确认整条链路已经通了const char* sql CREATE TABLE IF NOT EXISTS user_info ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, score INTEGER DEFAULT 0); char* errMsg nullptr; int rc sqlite3_exec(db, sql, nullptr, nullptr, errMsg); if (rc ! SQLITE_OK) { CString msg CStringFromUtf8(errMsg ? errMsg : unknown error); AfxMessageBox(msg); sqlite3_free(errMsg); }逻辑说明sqlite3_exec适合执行不带结果集返回、不带参数的DDL语句这里用来创建user_info表。errMsg由sqlite3内部通过malloc分配使用后必须调用sqlite3_free释放否则每个失败操作都会泄漏一块内存。参数说明四个参数分别是“数据库句柄、SQL文本、回调函数指针、回调上下文”回调参数和上下文传nullptr即可因为建表不需要处理行数据。这一步能正常跑通就说明sqlite3核心、字符集转换、返回码检查三件事都已经就位可以开始封装了。3. 封装数据访问层让MFC代码别再裸写sqlite3查询3.1 为什么必须包一层网上搜MFCsqlite3例子会看到大量直接在按钮事件里写sqlite3_open、sqlite3_prepare、sqlite3_step的代码。这种写法临时验证没问题但项目一旦有十几个窗口、几十个查询代码就变成黑匣子statement忘了释放、返回码散落在各处、错误信息只能靠断点看。所以我通常把sqlite3的C接口包成两层连接会话层和语句层。连接层负责sqlite3的打开、关闭、错误信息提取业务窗口永远不直接持有sqlite3语句层负责prepare、bind、step、finalize的完整生命周期。这样UI层写出来的是接近业务语义的代码比如db.Execute(sql)、db.QueryRows(sql, params)而不是满屏的C接口调用。3.2 连接会话类 CDbSession先看头文件接口尽量收敛暴露给外面调用的方法越少越好class CDbSession { public: CDbSession(); virtual ~CDbSession(); bool Open(const CString dbPath); void Close(); bool Execute(const CString sql); sqlite3* GetHandle() const { return m_db; } CString GetLastError() const; private: sqlite3* m_db; CString m_lastError; };实现文件里Open负责UTF-8路径转换和sqlite3_open失败时记下错误信息bool CDbSession::Open(const CString dbPath) { Close(); // 先清理上次可能残留的连接 CStringA utf8Path CW2A(dbPath, CP_UTF8); int rc sqlite3_open(utf8Path, m_db); if (rc ! SQLITE_OK) { m_lastError CStringFromUtf8(sqlite3_errmsg(m_db)); sqlite3_close(m_db); m_db nullptr; return false; } return true; } void CDbSession::Close() { if (m_db) { sqlite3_close(m_db); m_db nullptr; } }逻辑说明m_db在打开失败后必须置空否则析构时Close会对同一个指针二次关闭。sqlite3_open成功时句柄内部引用计数加一失败时sqlite3_errmsg拿到的错误信息仍然有效但随后sqlite3_close会立刻释放连接所以错误信息要先拷贝到CString里再关。很多裸写代码在这里翻车直接用sqlite3_errmsg的返回值拼完了再close顺序反了拿到的是被释放的内存。3.3 语句类 CDbStatement为了避免sqlite3_stmt泄漏写一个RAII风格的语句包装。析构函数负责finalize业务函数只关心绑定参数和取列值class CDbStatement { public: CDbStatement() : m_stmt(nullptr) {} ~CDbStatement() { if (m_stmt) sqlite3_finalize(m_stmt); } bool Prepare(sqlite3* db, const CString sql); void BindInt(int index, int value); void BindText(int index, const CString value); bool StepRow(); void Reset(); int GetInt(int col); CString GetText(int col); private: sqlite3_stmt* m_stmt; };Prepare和Bind的典型实现如下bool CDbStatement::Prepare(sqlite3* db, const CString sql) { CStringA utf8Sql CW2A(sql, CP_UTF8); int rc sqlite3_prepare_v2(db, utf8Sql, -1, m_stmt, nullptr); return rc SQLITE_OK; } void CDbStatement::BindText(int index, const CString value) { CStringA utf8Value CW2A(value, CP_UTF8); // SQLITE_TRANSIENT 表示 sqlite3 内部拷贝一份局部变量销毁不影响后续执行 sqlite3_bind_text(m_stmt, index, utf8Value, -1, SQLITE_TRANSIENT); }逻辑说明prepare_v2的第三个参数传-1表示按SQL文本的完整长度处理不用手动数字节数最后一个参数pzTail传nullptr表示不关心SQL文本末尾是否还有未解析的内容。BindText最容易出错的地方是第五个参数utf8Value是局部变量函数返回后内存立即失效所以这里绝不能传SQLITE_STATIC必须传SQLITE_TRANSIENT让sqlite3在绑定的瞬间把文本数据拷贝到自己的内部缓冲区。3.4 错误信息统一出口会话类和语句类的所有方法失败时统一把错误记到m_lastError。业务层出现异常操作后调GetLastError去弹窗或写日志。有些开发者习惯在每个sqlite3调用后自己弹一个AfxMessageBox我见过不少MFC工程这么干一点都不推荐。第一弹窗会打断用户操作SQLITE_BUSY这种瞬时错误弹一次就够了第二弹窗信息无法留痕事后排查还是要靠日志。所以错误统一收口到会话层界面只关心“这次操作有没有成功”具体原因交给日志文件。4. 增删改查落地参数绑定、结果集读取与二进制存取4.1 参数绑定代替SQL拼接MFC里最容易出问题的写法是用CString::Format拼SQL例如CString sql; sql.Format(_T(INSERT INTO user_info(name, score) VALUES(%s, %d)), name, score);这段代码在用户名为“OBrien”时直接语法错误更别提把SQL语句拼接到日志里去查问题。参数绑定是更稳的做法sqlite3官方接口就支持bool InsertUser(CDbSession db, const CString name, int score) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T(INSERT INTO user_info(name, score) VALUES(?, ?)))) { return false; } stmt.BindText(1, name); // 参数索引从1开始 stmt.BindInt(2, score); return stmt.StepRow(); // 执行INSERT返回false表示完成 }逻辑说明SQL文本里的问号是占位符sqlite3_bind_xxx系列函数负责把实际值绑上去。BindText内部已经做了UTF-8转换业务层不再关心编码。参数说明绑定索引从1开始不是0第2个参数score是整数没有编码问题直接BindInt。StepRow的返回值在这里表示是否取到行INSERT没有结果集返回false恰恰说明执行成功。如果SQL执行失败错误信息会留在会话层的m_lastError里。4.2 查询结果提取与类型转换查询场景需要一个稍完整的结果集结构。简单做法是返回“行列表”每行里面按列名取值struct UserRow { int id; CString name; int score; }; bool QueryUsers(CDbSession db, CArrayUserRow, UserRow results) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T(SELECT id, name, score FROM user_info ORDER BY id))) { return false; } results.RemoveAll(); while (stmt.StepRow()) { UserRow row; row.id stmt.GetInt(0); row.name stmt.GetText(1); row.score stmt.GetInt(2); results.Add(row); } return true; }逻辑说明StepRow每调用一次让sqlite3_stmt前进到下一行返回true表示还有数据返回false表示行取完或出错。GetInt和GetText内部的实现分别调用sqlite3_column_int和sqlite3_column_text列索引从0开始与SELECT语句里的列顺序一致。特别提醒sqlite3_column_text返回的char*指针只在下一次sqlite3_step或sqlite3_reset之前有效所以在GetText实现里必须立刻把它转成CString拷贝走绝不能存下指针后面再用。4.3 BLOB字段读写图片与文件业务里偶尔要把图片、附件塞进数据库。sqlite3对二进制数据用BLOB类型存储绑定和读取都有专门接口// 写入二进制数据如文件内容 CFile file; if (file.Open(_T(D:\\temp\\avatar.png), CFile::modeRead)) { ULONGLONG len file.GetLength(); BYTE* buf new BYTE[(size_t)len]; file.Read(buf, (UINT)len); CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T(UPDATE user_info SET avatar ? WHERE id ?)); // SQLITE_TRANSIENTsqlite3 内部拷贝一份buf 释放不影响数据 sqlite3_bind_blob(stmt.GetHandle(), 1, buf, (int)len, SQLITE_TRANSIENT); stmt.BindInt(2, userId); stmt.StepRow(); delete[] buf; }读取时用sqlite3_column_bytes拿长度sqlite3_column_blob拿指针再memcpy出来转存到CByteArray或直接写文件。逻辑说明bind_blob和bind_text一样第五个参数用SQLITE_TRANSIENT让sqlite3内部拷贝数据缓冲区用完即可释放。读取端指针同样只在下一次step前有效需要立刻拷贝。5. 避坑报告MFCsqlite3组合里的五个真实翻车记录5.1 数据库文件打不开返回值却是SQLITE_OK现象sqlite3_open执行后rc返回SQLITE_OK没有报错但紧接着建表、插入全部失败错误信息是“unable to open database file”。头两次遇到这个问题容易在返回值上绕圈明明第一步没报错后面全挂。原因sqlite3_open的行为是“路径指向的文件不存在时自动创建”但如果路径的目录不存在或者路径字符串里包含了文件名之外的非法字符open阶段能通过真正读写时才发现文件根本没落盘。MFC里常见的触发点是CString转UTF-8时用了ANSI代码页中文目录名被转成GBK存进数据库路径数据库实际写到另一个名字去了后续操作全对着错误路径操作。解决在调用sqlite3_open之前先检查目录是否存在用PathFileExists或者直接判断父目录。对路径字符串做预处理统一走CW2A(dbPath, CP_UTF8)不要图省事用(W2A)默认转换。还有一点sqlite3_open返回后马上调用sqlite3_errmsg(db)确认是否是SQLITE_OK正常情况是“not an error”。5.2 中文数据写入后读出来全是问号现象界面输入中文用户名insert后马上select表格里显示“”或者“口口口”。数据库里用十六进制工具查看存的字节和输入完全对不上。原因绑定参数时把CString直接传给了sqlite3_bind_text没有转UTF-8。CString在Unicode工程下是UTF-16LEsqlite3按UTF-8去解析高低字节被拆开重组出来全是乱码。另一种常见触发点是错误地用了CString::GetBuffer返回的指针绑文本然后把SQLITE_STATIC传给了第五个参数局部缓冲销毁后sqlite3内部还引用着原地址。解决所有文本参数进出数据库都要经过封装层的Utf8FromCString和CStringFromUtf8两个函数不要在业务代码里做裸转换绑定文本一律使用SQLITE_TRANSIENT让sqlite3拷贝数据不要依赖外部缓冲区的生命周期。5.3 sqlite3_close返回SQLITE_BUSY数据库文件一直在占用现象程序退出后数据库文件被占用无法手动复制或删除任务管理器里看进程已经结束但.db文件仍然被某个句柄锁住。原因某个sqlite3_stmt执行完之后只调用了sqlite3_reset没有调sqlite3_finalize。reset只是把语句状态重置回初始状态占用的连接资源没有释放close时检测到还有未完成的语句返回SQLITE_BUSY连接也不关闭。MFC程序里窗口销毁和线程退出的时序一乱这类泄漏特别隐蔽Debug跑几小时才出现一次。解决给CDbStatement写析构函数析构里强制sqlite3_finalize。封装之后业务层不需要记得finalize语句对象出作用域就自动释放。如果还有什么临时手写的sqlite3_stmt裸指针务必养成prepare和finalize成对出现的习惯。5.4 后台线程复用同一个连接时崩溃或报locked现象程序开了后台工作线程做批量导入同时UI线程偶尔要查询数据同一个CDbSession连接被两个线程交替使用跑几十次后要么崩溃要么报“database table is locked”。原因sqlite3的串行模式保证SQL层面的线程安全但它不等于“多线程共享同一个sqlite3*并发操作”。多个线程在同一时间用同一个连接prepare不同的语句即使SQLITE_THREADSAFE1也不能保证跨语句的资源互不干扰。加上UI线程和后台线程的调用时序一旦交错WAL模式下还可能碰到锁等待超时。解决两条路选一条要么给CDbSession加临界区让每个sqlite3操作序列在锁内完成要么干脆每个线程单独Open一个连接。我一般选后者MFC工具类程序的连接数不大独立连接省去锁竞争也避免了跨线程传递SQLITE_HANDLE的隐性问题。5.5 批量插入几千行耗时爆炸UI卡死几秒现象程序里循环insert一百条数据每一条都是单条INSERT语句插入到五百条的时候UI直接卡死几秒钟。Release和Debug表现还不一样Release下更容易崩。原因每条INSERT默认自动提交一个事务意味着每插一条就做一次磁盘写入同步几千行就是几千次fsync。Release崩的原因常和语句泄漏糅合在一起Debug下对象销毁慢时序被掩盖Release下指针释放提前触发访问野指针。解决批量写入时手动包一个事务外面加BEGIN全部插入完成后再COMMIT。一个事务里几千条insert会快到接近内存操作。至于Release表现不一致先把语句泄漏修干净然后确认绑定参数是SQLITE_TRANSIENT再谈优化。批处理代码在下一章给出。6. 进阶收尾事务批量写、WAL与备份检查6.1 批量写入的最终形态外面包一层事务批量插入的耗时能压缩到原来的十分之一甚至更低db.Execute(_T(BEGIN)); for (int i 0; i itemCount; i) { CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T(INSERT INTO log_table(tag, content) VALUES(?, ?))); stmt.BindText(1, tagArray[i]); stmt.BindText(2, contentArray[i]); stmt.StepRow(); } db.Execute(_T(COMMIT));注意中途出错时的处理我一般在循环里判断StepRow返回值遇到失败就执行ROLLBACK并记录日志。事务开着不做回滚连接会一直持有写锁其他线程的读操作会被卡住这个状态最容易忽略。6.2 WAL模式与锁等待建库后立刻执行一条PRAGMA把连接切到WAL模式sqlite3_exec(db, PRAGMA journal_modeWAL;, nullptr, nullptr, nullptr); sqlite3_exec(db, PRAGMA busy_timeout3000;, nullptr, nullptr, nullptr);WAL模式的好处是读写不互相阻塞桌面工具里后台写数据时UI线程还能正常查询。busy_timeout设为3000毫秒遇到锁冲突先等三秒而不是立刻报错。代价是会多生成.db-wal和.db-shm两个文件交付时别漏掉否则另一台机器无法读到最新数据。6.3 交付前备份检查每轮版本交付前我都会在测试版里加一段自检逻辑先执行PRAGMA integrity_check确认数据库完整性再执行一次checkpoint让WAL文件内容合并回主库最后把.db文件复制出去留档。这套动作跑完才敢把工具交给别人用不然对方拷走的数据很可能缺了WAL里还没合并的记录。从那以后我每次交付MFC工具程序前都强制走一遍“完整性检查、WAL合并、文件复制”的流程数据类的坑基本不再找上门。希望这套经验能帮到你少走两趟弯路。本文还有配套的精品资源点击获取
简介这是一份基于Visual Studio 2010的MFC对话框应用示例解决MFC项目中接入SQLite3数据库的问题。代码涵盖添加、删除、修改与查询等基础CRUD操作并特别演示了通过回调函数处理查询结果的方式适合刚开始接触MFC数据库编程的Windows开发者参考。压缩包共38个文件大小约7.01MB除h/cpp源码和sln/vcxproj等工程文件外还包含exe可执行程序、dll/lib运行库、db/sql数据库文件以及pdb调试信息可对照运行和断点学习。已有1338人学习下载可先运行Release目录中的exe体验效果再结合源码理解sqlite3_open、sqlite3_exec、sqlite3_close及错误处理等关键接口。示例还给出查询时带回调函数的写法便于处理逐行返回的大数据量结果同时涉及同步查询与后台异步查询的区分对理解MFC界面线程与数据库操作的配合也有帮助。1. MFC工程要用sqlite3先想清楚这三件事MFC工程要用sqlite3问得最多的其实不是SQL语法而是怎么把这堆C接口接进MFC的Unicode字符串、资源管理和多线程背景下。过去做MFC工具存配置常写ini数据一多、查询一复杂就顶不住换用sqlite3后一台电脑不用装数据库服务一个.db文件全搞定特别适合离线工具、内部管理系统和小型桌面客户端。这篇笔记按一套可复现的MFCsqlite3例子的落地过程来写先解决编译连接和字符集再封装数据访问层然后给增删改查和二进制存取的范例最后把最容易踩的坑挨个点名。适合刚开始在MFC里试点SQLite的开发者也适合准备从文件型存储切到关系型存储的熟手照着步骤走完基本能拿到一套能直接改来用的骨架。2. 接入sqlite3源码、字符集与三个配置关键点2.1 源码编译还是DLL按分发场景选接触过sqlite3的人都知道官方给的接入姿态非常灵活但落到MFC工程里无非两条路。方式A把sqlite3.c、sqlite3.h拖进工程当成普通源文件参与编译方式B链接预编译好的sqlite3.dll和配套lib。两者在调用层没有任何区别都是sqlite3_open、sqlite3_prepare_v2那一套API真正拉开差距的是运行时依赖和调试体验。大部分时候我推荐源码编译方式。第一交付时只带一个exe给同事拷工具不怕漏带DLL第二断点能直接进sqlite3的C源码遇到SQLITE_BUSY、SQLITE_CORRUPT这类返回码时可以直接看内部状态第三SQLITE_THREADSAFE这种编译期选项完全由自己控制不会被预编译包预设的值带偏。缺点只有一个工程编译时间会多个十几秒到几十秒日常开发完全能接受。DLL方式适合对exe体积敏感、或者团队里已经有统一DLL组件库的场景。用它省了编译时间但多出来的是部署心智调试时偶尔会遇到“明明DLL放在exe旁边程序还是报找不到”的灵异现场。这类问题通常出在VS调试目录没有指向exe输出目录或者系统PATH里捡到了一个旧版本DLL排查起来特别消耗耐心。决策项源码编译DLL方式交付文件单个exeexe sqlite3.dll调试排错断点可进sqlite3源码只能看接口返回码编译宏控制完全可控取决于DLL编译者配置构建时间增加不多无增加部署隐患少注意搜索顺序和版本混用2.2 MFC字符集与sqlite3的UTF-8契约这一节是整套例子里最容易被忽略的部分。MFC工程默认按Unicode字符集编译CString底层是UTF-16LE宽字符而sqlite3对外文本接口统一按UTF-8处理sqlite3_open的第一个参数、sqlite3_bind_text的文本参数、sqlite3_column_text返回的字符串全部默认视为UTF-8。两端编码不一致强制转换不做的话结果就是中文路径打不开数据库、中文数据写入后再读变成问号。处理思路是在数据访问层统一做转换而不是在业务代码里到处写转码。打开数据库时标准写法是这样的CString dbPath _T(D:\\工具数据\\local.db); // CW2A 将 UTF-16 宽字符 CString 转为 UTF-8 的 CStringA CStringA utf8Path CW2A(dbPath, CP_UTF8); sqlite3* db nullptr; int rc sqlite3_open(utf8Path, db); if (rc ! SQLITE_OK) { // sqlite3_errmsg 返回的也是 UTF-8展示前要逆转换成宽字符 CString errMsg CStringFromUtf8(sqlite3_errmsg(db)); AfxMessageBox(errMsg); if (db) { sqlite3_close(db); db nullptr; } }逻辑说明sqlite3_open要求UTF-8路径这里先用CW2A把宽字符CString转成CStringA再交给接口。错误信息从sqlite3_errmsg返回时同样是UTF-8编码里面的中文在弹窗前必须转回宽字符否则对话框里全是乱码。参数说明CP_UTF8是Windows代码页常量表示按UTF-8编解码sqlite3_errmsg返回的是连接内部的静态缓冲区不需要手动释放但拿到指针后要尽快转存后续任何sqlite3调用都可能覆盖它。如果工程里同时存在CStringA和CStringW的混用建议把两个方向的转换收拢成独立函数业务层只认这两个入口// 宽字符 CString - UTF-8 CStringA CStringA Utf8FromCString(const CString text) { return CW2A(text, CP_UTF8); } // UTF-8 char* - 宽字符 CString CString CStringFromUtf8(const char* utf8Text) { return CA2W(utf8Text, CP_UTF8); }这两个函数放进公共工具模块后后面所有sqlite3相关调用都走它们编码问题基本就隔离了。2.3 工程配置的三个关键点把sqlite3源码加进MFC工程后还有三个配置细节要检查到位。第一预编译头处理。MFC工程默认开了预编译头sqlite3.c直接加进去如果没做处理编译时会报“无法找到预编译头文件”。解决办法是选中sqlite3.c在属性页里把它单独设成“不使用预编译头”或者干脆在sqlite3.c顶部的宏定义区域加一句强制跳过预编译头。我一般选前者改文件不如改工程配置。第二字符集设置。工程属性里的“字符集”如果是“使用Unicode字符集”上面第2.2节的转换代码原样可用如果项目老还停留在“使用多字节字符集”这时候CString本身是CStringACW2A依然能编译但中间会绕一次从char到wchar再到char的转换白耗性能。多字节工程里直接用char* sqlite3_bind_text反而更直接。第三SQLITE_THREADSAFE宏。sqlite3的线程模式在编译期决定。源码编译时系统默认值是1即串行模式多线程调用安全但同一时刻只有一个线程能进入sqlite3内部操作如果链接的DLL当初以SQLITE_THREADSAFE0编的那你在线程池里同时调用就可能崩。我在工程属性里加了一条预处理定义SQLITE_THREADSAFE1强制走串行模式后续在后台线程里操作数据库省心得多。2.4 最小验证建表并确认返回值配置全部完成后先做一个最小验证确认整条链路已经通了const char* sql CREATE TABLE IF NOT EXISTS user_info ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, score INTEGER DEFAULT 0); char* errMsg nullptr; int rc sqlite3_exec(db, sql, nullptr, nullptr, errMsg); if (rc ! SQLITE_OK) { CString msg CStringFromUtf8(errMsg ? errMsg : unknown error); AfxMessageBox(msg); sqlite3_free(errMsg); }逻辑说明sqlite3_exec适合执行不带结果集返回、不带参数的DDL语句这里用来创建user_info表。errMsg由sqlite3内部通过malloc分配使用后必须调用sqlite3_free释放否则每个失败操作都会泄漏一块内存。参数说明四个参数分别是“数据库句柄、SQL文本、回调函数指针、回调上下文”回调参数和上下文传nullptr即可因为建表不需要处理行数据。这一步能正常跑通就说明sqlite3核心、字符集转换、返回码检查三件事都已经就位可以开始封装了。3. 封装数据访问层让MFC代码别再裸写sqlite3查询3.1 为什么必须包一层网上搜MFCsqlite3例子会看到大量直接在按钮事件里写sqlite3_open、sqlite3_prepare、sqlite3_step的代码。这种写法临时验证没问题但项目一旦有十几个窗口、几十个查询代码就变成黑匣子statement忘了释放、返回码散落在各处、错误信息只能靠断点看。所以我通常把sqlite3的C接口包成两层连接会话层和语句层。连接层负责sqlite3的打开、关闭、错误信息提取业务窗口永远不直接持有sqlite3语句层负责prepare、bind、step、finalize的完整生命周期。这样UI层写出来的是接近业务语义的代码比如db.Execute(sql)、db.QueryRows(sql, params)而不是满屏的C接口调用。3.2 连接会话类 CDbSession先看头文件接口尽量收敛暴露给外面调用的方法越少越好class CDbSession { public: CDbSession(); virtual ~CDbSession(); bool Open(const CString dbPath); void Close(); bool Execute(const CString sql); sqlite3* GetHandle() const { return m_db; } CString GetLastError() const; private: sqlite3* m_db; CString m_lastError; };实现文件里Open负责UTF-8路径转换和sqlite3_open失败时记下错误信息bool CDbSession::Open(const CString dbPath) { Close(); // 先清理上次可能残留的连接 CStringA utf8Path CW2A(dbPath, CP_UTF8); int rc sqlite3_open(utf8Path, m_db); if (rc ! SQLITE_OK) { m_lastError CStringFromUtf8(sqlite3_errmsg(m_db)); sqlite3_close(m_db); m_db nullptr; return false; } return true; } void CDbSession::Close() { if (m_db) { sqlite3_close(m_db); m_db nullptr; } }逻辑说明m_db在打开失败后必须置空否则析构时Close会对同一个指针二次关闭。sqlite3_open成功时句柄内部引用计数加一失败时sqlite3_errmsg拿到的错误信息仍然有效但随后sqlite3_close会立刻释放连接所以错误信息要先拷贝到CString里再关。很多裸写代码在这里翻车直接用sqlite3_errmsg的返回值拼完了再close顺序反了拿到的是被释放的内存。3.3 语句类 CDbStatement为了避免sqlite3_stmt泄漏写一个RAII风格的语句包装。析构函数负责finalize业务函数只关心绑定参数和取列值class CDbStatement { public: CDbStatement() : m_stmt(nullptr) {} ~CDbStatement() { if (m_stmt) sqlite3_finalize(m_stmt); } bool Prepare(sqlite3* db, const CString sql); void BindInt(int index, int value); void BindText(int index, const CString value); bool StepRow(); void Reset(); int GetInt(int col); CString GetText(int col); private: sqlite3_stmt* m_stmt; };Prepare和Bind的典型实现如下bool CDbStatement::Prepare(sqlite3* db, const CString sql) { CStringA utf8Sql CW2A(sql, CP_UTF8); int rc sqlite3_prepare_v2(db, utf8Sql, -1, m_stmt, nullptr); return rc SQLITE_OK; } void CDbStatement::BindText(int index, const CString value) { CStringA utf8Value CW2A(value, CP_UTF8); // SQLITE_TRANSIENT 表示 sqlite3 内部拷贝一份局部变量销毁不影响后续执行 sqlite3_bind_text(m_stmt, index, utf8Value, -1, SQLITE_TRANSIENT); }逻辑说明prepare_v2的第三个参数传-1表示按SQL文本的完整长度处理不用手动数字节数最后一个参数pzTail传nullptr表示不关心SQL文本末尾是否还有未解析的内容。BindText最容易出错的地方是第五个参数utf8Value是局部变量函数返回后内存立即失效所以这里绝不能传SQLITE_STATIC必须传SQLITE_TRANSIENT让sqlite3在绑定的瞬间把文本数据拷贝到自己的内部缓冲区。3.4 错误信息统一出口会话类和语句类的所有方法失败时统一把错误记到m_lastError。业务层出现异常操作后调GetLastError去弹窗或写日志。有些开发者习惯在每个sqlite3调用后自己弹一个AfxMessageBox我见过不少MFC工程这么干一点都不推荐。第一弹窗会打断用户操作SQLITE_BUSY这种瞬时错误弹一次就够了第二弹窗信息无法留痕事后排查还是要靠日志。所以错误统一收口到会话层界面只关心“这次操作有没有成功”具体原因交给日志文件。4. 增删改查落地参数绑定、结果集读取与二进制存取4.1 参数绑定代替SQL拼接MFC里最容易出问题的写法是用CString::Format拼SQL例如CString sql; sql.Format(_T(INSERT INTO user_info(name, score) VALUES(%s, %d)), name, score);这段代码在用户名为“OBrien”时直接语法错误更别提把SQL语句拼接到日志里去查问题。参数绑定是更稳的做法sqlite3官方接口就支持bool InsertUser(CDbSession db, const CString name, int score) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T(INSERT INTO user_info(name, score) VALUES(?, ?)))) { return false; } stmt.BindText(1, name); // 参数索引从1开始 stmt.BindInt(2, score); return stmt.StepRow(); // 执行INSERT返回false表示完成 }逻辑说明SQL文本里的问号是占位符sqlite3_bind_xxx系列函数负责把实际值绑上去。BindText内部已经做了UTF-8转换业务层不再关心编码。参数说明绑定索引从1开始不是0第2个参数score是整数没有编码问题直接BindInt。StepRow的返回值在这里表示是否取到行INSERT没有结果集返回false恰恰说明执行成功。如果SQL执行失败错误信息会留在会话层的m_lastError里。4.2 查询结果提取与类型转换查询场景需要一个稍完整的结果集结构。简单做法是返回“行列表”每行里面按列名取值struct UserRow { int id; CString name; int score; }; bool QueryUsers(CDbSession db, CArrayUserRow, UserRow results) { CDbStatement stmt; if (!stmt.Prepare(db.GetHandle(), _T(SELECT id, name, score FROM user_info ORDER BY id))) { return false; } results.RemoveAll(); while (stmt.StepRow()) { UserRow row; row.id stmt.GetInt(0); row.name stmt.GetText(1); row.score stmt.GetInt(2); results.Add(row); } return true; }逻辑说明StepRow每调用一次让sqlite3_stmt前进到下一行返回true表示还有数据返回false表示行取完或出错。GetInt和GetText内部的实现分别调用sqlite3_column_int和sqlite3_column_text列索引从0开始与SELECT语句里的列顺序一致。特别提醒sqlite3_column_text返回的char*指针只在下一次sqlite3_step或sqlite3_reset之前有效所以在GetText实现里必须立刻把它转成CString拷贝走绝不能存下指针后面再用。4.3 BLOB字段读写图片与文件业务里偶尔要把图片、附件塞进数据库。sqlite3对二进制数据用BLOB类型存储绑定和读取都有专门接口// 写入二进制数据如文件内容 CFile file; if (file.Open(_T(D:\\temp\\avatar.png), CFile::modeRead)) { ULONGLONG len file.GetLength(); BYTE* buf new BYTE[(size_t)len]; file.Read(buf, (UINT)len); CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T(UPDATE user_info SET avatar ? WHERE id ?)); // SQLITE_TRANSIENTsqlite3 内部拷贝一份buf 释放不影响数据 sqlite3_bind_blob(stmt.GetHandle(), 1, buf, (int)len, SQLITE_TRANSIENT); stmt.BindInt(2, userId); stmt.StepRow(); delete[] buf; }读取时用sqlite3_column_bytes拿长度sqlite3_column_blob拿指针再memcpy出来转存到CByteArray或直接写文件。逻辑说明bind_blob和bind_text一样第五个参数用SQLITE_TRANSIENT让sqlite3内部拷贝数据缓冲区用完即可释放。读取端指针同样只在下一次step前有效需要立刻拷贝。5. 避坑报告MFCsqlite3组合里的五个真实翻车记录5.1 数据库文件打不开返回值却是SQLITE_OK现象sqlite3_open执行后rc返回SQLITE_OK没有报错但紧接着建表、插入全部失败错误信息是“unable to open database file”。头两次遇到这个问题容易在返回值上绕圈明明第一步没报错后面全挂。原因sqlite3_open的行为是“路径指向的文件不存在时自动创建”但如果路径的目录不存在或者路径字符串里包含了文件名之外的非法字符open阶段能通过真正读写时才发现文件根本没落盘。MFC里常见的触发点是CString转UTF-8时用了ANSI代码页中文目录名被转成GBK存进数据库路径数据库实际写到另一个名字去了后续操作全对着错误路径操作。解决在调用sqlite3_open之前先检查目录是否存在用PathFileExists或者直接判断父目录。对路径字符串做预处理统一走CW2A(dbPath, CP_UTF8)不要图省事用(W2A)默认转换。还有一点sqlite3_open返回后马上调用sqlite3_errmsg(db)确认是否是SQLITE_OK正常情况是“not an error”。5.2 中文数据写入后读出来全是问号现象界面输入中文用户名insert后马上select表格里显示“”或者“口口口”。数据库里用十六进制工具查看存的字节和输入完全对不上。原因绑定参数时把CString直接传给了sqlite3_bind_text没有转UTF-8。CString在Unicode工程下是UTF-16LEsqlite3按UTF-8去解析高低字节被拆开重组出来全是乱码。另一种常见触发点是错误地用了CString::GetBuffer返回的指针绑文本然后把SQLITE_STATIC传给了第五个参数局部缓冲销毁后sqlite3内部还引用着原地址。解决所有文本参数进出数据库都要经过封装层的Utf8FromCString和CStringFromUtf8两个函数不要在业务代码里做裸转换绑定文本一律使用SQLITE_TRANSIENT让sqlite3拷贝数据不要依赖外部缓冲区的生命周期。5.3 sqlite3_close返回SQLITE_BUSY数据库文件一直在占用现象程序退出后数据库文件被占用无法手动复制或删除任务管理器里看进程已经结束但.db文件仍然被某个句柄锁住。原因某个sqlite3_stmt执行完之后只调用了sqlite3_reset没有调sqlite3_finalize。reset只是把语句状态重置回初始状态占用的连接资源没有释放close时检测到还有未完成的语句返回SQLITE_BUSY连接也不关闭。MFC程序里窗口销毁和线程退出的时序一乱这类泄漏特别隐蔽Debug跑几小时才出现一次。解决给CDbStatement写析构函数析构里强制sqlite3_finalize。封装之后业务层不需要记得finalize语句对象出作用域就自动释放。如果还有什么临时手写的sqlite3_stmt裸指针务必养成prepare和finalize成对出现的习惯。5.4 后台线程复用同一个连接时崩溃或报locked现象程序开了后台工作线程做批量导入同时UI线程偶尔要查询数据同一个CDbSession连接被两个线程交替使用跑几十次后要么崩溃要么报“database table is locked”。原因sqlite3的串行模式保证SQL层面的线程安全但它不等于“多线程共享同一个sqlite3*并发操作”。多个线程在同一时间用同一个连接prepare不同的语句即使SQLITE_THREADSAFE1也不能保证跨语句的资源互不干扰。加上UI线程和后台线程的调用时序一旦交错WAL模式下还可能碰到锁等待超时。解决两条路选一条要么给CDbSession加临界区让每个sqlite3操作序列在锁内完成要么干脆每个线程单独Open一个连接。我一般选后者MFC工具类程序的连接数不大独立连接省去锁竞争也避免了跨线程传递SQLITE_HANDLE的隐性问题。5.5 批量插入几千行耗时爆炸UI卡死几秒现象程序里循环insert一百条数据每一条都是单条INSERT语句插入到五百条的时候UI直接卡死几秒钟。Release和Debug表现还不一样Release下更容易崩。原因每条INSERT默认自动提交一个事务意味着每插一条就做一次磁盘写入同步几千行就是几千次fsync。Release崩的原因常和语句泄漏糅合在一起Debug下对象销毁慢时序被掩盖Release下指针释放提前触发访问野指针。解决批量写入时手动包一个事务外面加BEGIN全部插入完成后再COMMIT。一个事务里几千条insert会快到接近内存操作。至于Release表现不一致先把语句泄漏修干净然后确认绑定参数是SQLITE_TRANSIENT再谈优化。批处理代码在下一章给出。6. 进阶收尾事务批量写、WAL与备份检查6.1 批量写入的最终形态外面包一层事务批量插入的耗时能压缩到原来的十分之一甚至更低db.Execute(_T(BEGIN)); for (int i 0; i itemCount; i) { CDbStatement stmt; stmt.Prepare(db.GetHandle(), _T(INSERT INTO log_table(tag, content) VALUES(?, ?))); stmt.BindText(1, tagArray[i]); stmt.BindText(2, contentArray[i]); stmt.StepRow(); } db.Execute(_T(COMMIT));注意中途出错时的处理我一般在循环里判断StepRow返回值遇到失败就执行ROLLBACK并记录日志。事务开着不做回滚连接会一直持有写锁其他线程的读操作会被卡住这个状态最容易忽略。6.2 WAL模式与锁等待建库后立刻执行一条PRAGMA把连接切到WAL模式sqlite3_exec(db, PRAGMA journal_modeWAL;, nullptr, nullptr, nullptr); sqlite3_exec(db, PRAGMA busy_timeout3000;, nullptr, nullptr, nullptr);WAL模式的好处是读写不互相阻塞桌面工具里后台写数据时UI线程还能正常查询。busy_timeout设为3000毫秒遇到锁冲突先等三秒而不是立刻报错。代价是会多生成.db-wal和.db-shm两个文件交付时别漏掉否则另一台机器无法读到最新数据。6.3 交付前备份检查每轮版本交付前我都会在测试版里加一段自检逻辑先执行PRAGMA integrity_check确认数据库完整性再执行一次checkpoint让WAL文件内容合并回主库最后把.db文件复制出去留档。这套动作跑完才敢把工具交给别人用不然对方拷走的数据很可能缺了WAL里还没合并的记录。从那以后我每次交付MFC工具程序前都强制走一遍“完整性检查、WAL合并、文件复制”的流程数据类的坑基本不再找上门。希望这套经验能帮到你少走两趟弯路。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
