简介这是一份面向MFC初学者的SQLite3集成示例工程演示如何在Visual Studio 2010对话框应用中完成数据库的增删改查并重点展示了通过回调函数实现的异步查询与同步查询的写法。资源包共38个文件头文件和源文件各有8个与4个另附sqlite3.dll、sqlite3.lib、sqlite3.exe等运行组件以及测试数据库db.sql和test.db整体压缩后约7.01MB。项目代码路径清晰涉及sqlite3_open、sqlite3_exec、错误处理与资源释放等关键步骤涵盖从加载库、连接数据库、执行SQL到关闭连接的全流程并对回调函数处理多行结果、在线程中避免阻塞UI等场景给出了可运行示范同时利用sqlite3_errcode与sqlite3_errmsg进行错误诊断帮助读者快速定位常见问题。包内同时提供x86与x64版本的库文件便于在不同编译环境下直接使用。已有1338人学习下载可直接打开工程查看完整实现也可将其中封装好的DBTool类迁移至自己的项目。1. MFC 使用 SQLite3别再自己造轮子了这套封装能直接抄进项目做桌面工具时最烦的就是数据存哪。写注册表太散用文本文件得自己处理并发上 SQL Server 又太重。我第一回在 MFC 里接 SQLite3 的时候查了两天资料把 sqlite3.c 下载下来编译一遍又封装了几层接口才跑通。回头看其实没那么玄学就是几个关键环节源码怎么编、工程怎么配、SQL 语句怎么和 CString 安全互转、出问题怎么看错误码。这套东西弄完之后后面再做任何轻量级档案管理、配置存储、本地缓存的小工具我都直接复用这份封装十分钟就能接入一个新的 MFC 对话框工程。这篇文章就把这套路子完整拆给你新手照着敲能跑起来熟手可以跳过基础部分直接看第 4 章的坑。2. 把 SQLite3 揉进 MFC 工程从源码编译到静态库配置的完整链路2.1 选型为什么用源码编译而不是直接装预编译包SQLite3 官方提供两种接入方式一种是直接下载预编译的 sqlite3.dll 和 sqlite3.lib另一种是拿官方发布的合并源码sqlite-amalgamation自己编。很多做 MFC 的朋友图省事直接拖 DLL 进工程结果到客户机器上忘了带上 DLL或者 DLL 位数不匹配运行时直接弹“无法定位程序输入点”。我一般建议走源码编译这条路产出的是静态库 sqlite3.lib链接进 exe 里就完事不需要再分发 DLL。源码编译还有个好处可以用编译选项控制 SQLite3 的特性集。比如不需要全文索引可以定义SQLITE_OMIT_FTS裁剪体积需要支持扩展加载要定义SQLITE_ENABLE_LOAD_EXTENSION。预编译包都是默认配置给你啥你用啥想调都没得调。另外 MFC 工程默认使用多线程调试 DLL/MDd或多线程 DLL/MDSQLite3 官方源码对线程模式是开放编译选项的。自己编译时用THREADSAFE1就能保证多线程访问安全用预编译 DLL 反而说不清它的线程配置。我见过有人把官方预编译的 DLL 用在 MFC 多线程程序里查询一多就偶发性崩溃查了两天才怀疑到线程配置上。2.2 编译步骤一条命令产出 lib 和 def先到官网下载合并源码包解压后你会看到四个文件sqlite3.c、sqlite3.h、sqlite3ext.h、shell.c。我们需要的是前两个。用 Visual Studio 自带的命令行编译工具Developer Command Prompt就能编不用装什么额外工具。我常用的命令是这样cl /O2 /DNDEBUG /D_SQLITE_ENABLE_FTS3 /D_SQLITE_ENABLE_FTS3_PARENTHESIS /D_SQLITE_ENABLE_FTS3_TOKENIZER /D_SQLITE_ENABLE_RTREE /D_SQLITE_ENABLE_COLUMN_METADATA /c sqlite3.c lib /DEF:sqlite3.def /OUT:sqlite3.lib /MACHINE:X86逻辑说明第一行把 sqlite3.c 编译成 sqlite3.obj/O2是优化速度/DNDEBUG表示不启用断言后面几个宏定义按需打开 FTS 全文检索和 RTree 空间索引不用的话可以删掉能省一点编译时间和体积。第二行用 lib 工具根据 sqlite3.def 生成导入库但这里有个前提——你手上得有 sqlite3.def。如果你下载的源码包没带 def 文件可以用dumpbin /EXPORTS sqlite3.obj手工导出函数列表再生成 def比较麻烦。更省事的做法是用sqlite3.def模板网上搜一下就能找到对应你编译出的符号版本我把这一步写成批处理固化下来下次直接双击跑。参数说明/MACHINE:X86是 32 位如果你的 MFC 工程是 x64要改成/MACHINE:X64。这一步最容易翻车32 位的 MFC 工程去链 64 位的 lib链接器直接报LNK1112: module machine type x64 conflicts with target machine type x86。2.3 工程配置把 sqlite3.h 和 sqlite3.lib 放进 MFC 项目的四种方式编译好之后把 sqlite3.h 和 sqlite3.lib 放到你的工程目录下推荐建一个ThirdParty/SQLite3文件夹单独存放。然后在 MFC 工程里做四个配置缺一个都编译不过。第一种方式在解决方案资源管理器里右键项目 → 属性 → 配置属性 → C/C → 常规 → 附加包含目录填上$(ProjectDir)ThirdParty\SQLite3。这样#include sqlite3.h就能找到了。第二种方式在链接器 → 常规 → 附加库目录里填入$(ProjectDir)ThirdParty\SQLite3。第三种方式在链接器 → 输入 → 附加依赖项里写上sqlite3.lib。注意这个依赖项是区分 Debug 和 Release 的你可以分别配置也可以用同一个 lib 文件。我建议 Debug 和 Release 都编译一次各出各的 lib命名成sqlite3_d.lib和sqlite3.lib然后在项目属性里通过$(Configuration)宏区分。第四种方式如果你不想改项目属性可以像下面这样在代码里直接指定#pragma comment(lib, sqlite3.lib)把这一行放在包含 sqlite3.h 的同一个头文件里工程配置里的附加依赖项就可以不填了。我一般只在临时测试工程里这么干正经项目还是养成在项目属性里配置的习惯否则别人接手你的工程时得翻半天代码才能找到链接了哪个库。配置完之后跑一个空工程验证一下。在对话框的 OnInitDialog 里加一句测试代码#include sqlite3.h sqlite3* db nullptr; int rc sqlite3_open_v2(:memory:, db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, nullptr); if (rc SQLITE_OK) { sqlite3_close(db); }逻辑说明:memory:表示创建内存数据库不落盘方便快速验证 sqlite3 函数能不能正常链接。sqlite3_open_v2比老版sqlite3_open多一个 flags 参数推荐始终用新版 API。如果上面这段在 Debug 和 Release 下都能编译通过且不崩溃说明工程配置没问题。3. 封装一个 C 访问层让 CString 与 SQL 语句安全互转3.1 接口设计只暴露 Open/Query/Exec 三个方法裸用 sqlite3 API 写 MFC 程序最别扭的是编码问题。SQLite3 的char*是 UTF-8 编码MFC 的CString在 ANSI 工程里是 GBK在 Unicode 工程里是 UTF-16。直接强制转换传进去中文条件查询大概率查不出结果甚至会把数据库内容写乱。所以第一步是封装一个类我命名为CSQLite3DB头文件长这样#pragma once #include sqlite3.h #include afx.h #include vector class CSQLite3DB { public: CSQLite3DB(); virtual ~CSQLite3DB(); BOOL Open(const CString strDbPath); void Close(); BOOL Exec(const CString strSql); BOOL Query(const CString strSql, std::vectorstd::vectorCString rows); sqlite3* GetHandle() const { return m_db; } private: sqlite3* m_db; };接口设计只有一个原则让调用方不需要知道 sqlite3 的存在。Open 负责打开文件Exec 执行不返回结果集的 SQL建表、插入、更新、删除Query 执行 SELECT 并把结果塞进二维 CString 数组。这样 MFC 界面层只跟 CString 打交道编码转换全部封装在类里。3.2 实现细节回调函数里怎么把行数据转成 CStringArraysqlite3 的sqlite3_exec回调函数是 C 风格的静态函数没法直接访问 MFC 的类成员。一般做法是把this指针塞进回调的第四个参数然后在静态回调里把它还原出来。我写过的最简洁版本是这样BOOL CSQLite3DB::Query(const CString strSql, std::vectorstd::vectorCString rows) { if (!m_db) return FALSE; char* errMsg nullptr; QueryContext ctx; ctx.rows rows; int rc sqlite3_exec(m_db, CT2A(strSql), QueryCallback, ctx, errMsg); if (rc ! SQLITE_OK) { TRACE(_T(SQLite query failed: %hs\n), errMsg ? errMsg : unknown); sqlite3_free(errMsg); return FALSE; } return TRUE; } int CSQLite3DB::QueryCallback(void* param, int argc, char** argv, char** colName) { QueryContext* ctx static_castQueryContext*(param); std::vectorCString row; for (int i 0; i argc; i) { row.push_back(argv[i] ? CString(CA2T(argv[i])) : CString(_T())); } ctx-rows-push_back(row); return 0; }逻辑说明CT2A宏把 CString 转成 ANSI 字符串CA2T把 ANSI 转回 CString。但这只针对 ANSI 工程。如果你的 MFC 工程是 Unicode 编译这里会出问题——CT2A在 Unicode 下会做 UTF-16 到 ANSI 的转换中文数据很可能丢字。所以 QueryContext 里还有一种做法是改用WideCharToMultiByte手工转成 UTF-8然后把 sqlite3_exec 替换成sqlite3_prepare_v2sqlite3_bind_textsqlite3_step的完整流程。我后来统一用 UTF-8 方案见下一节。3.3 参数绑定用 sqlite3_bind_text 避免 SQL 注入翻车写 Exec 方法时最容易犯的错是直接拼 SQLCString strSql; strSql.Format(_T(INSERT INTO user(name) VALUES(%s)), strName);如果strName里带单引号SQL 就断了带恶意内容就是经典的注入翻车。正确做法是用预编译语句加参数绑定BOOL CSQLite3DB::ExecParam(const CString strSql, const std::vectorCString params) { if (!m_db) return FALSE; sqlite3_stmt* stmt nullptr; int rc sqlite3_prepare_v2(m_db, CT2A(strSql), -1, stmt, nullptr); if (rc ! SQLITE_OK) { TRACE(_T(prepare failed: %hs\n), sqlite3_errmsg(m_db)); return FALSE; } for (size_t i 0; i params.size(); i) { CStringA strA CT2A(params[i]); sqlite3_bind_text(stmt, (int)(i 1), strA, -1, SQLITE_TRANSIENT); } rc sqlite3_step(stmt); sqlite3_finalize(stmt); return rc SQLITE_DONE || rc SQLITE_ROW; }逻辑说明sqlite3_prepare_v2把 SQL 文本编译成字节码SQL 里的?占位符用后续的sqlite3_bind_text逐个填充。第 4 个参数传-1表示字符串以\0结尾让 sqlite3 自己数长度SQLITE_TRANSIENT表示 sqlite3 会自己拷贝一份数据不怕调用结束后字符串内存失效。参数说明sqlite3_bind_text的第 2 个参数是索引从 1 开始对应 SQL 里第几个?。如果你要绑定的是整数或浮点分别用sqlite3_bind_int和sqlite3_bind_double。这里要注意CStringA strA CT2A(params[i])这步必须让strA的生命周期覆盖到sqlite3_step结束所以我把它定义在循环内bind 之后 step 之前都不会销毁。4. 排错与避坑我在 MFCSQLite3 里踩过的五个坑4.1 坑一Debug/Release 混用 lib 导致内存崩溃现象程序在 Debug 下跑得好好的切到 Release 发布版一执行查询就崩溃报错位置在 sqlite3_step 里。原因sqlite3 源码编译时默认使用 C 运行库的分配函数而 MFC 的 Debug 版动态分配内存的机制和 Release 不一样。如果 Debug 工程链接了 Release 版 sqlite3.lib或者反过来就会因为堆句柄不匹配导致崩溃。解决老老实实编译两个版本的 lib。Debug 加/D_DEBUG和/MTdRelease 加/DNDEBUG和/MT分别命名。项目属性里用$(Configuration)宏做条件链接。从那以后我再也不偷懒只编一个库了。4.2 坑二路径含中文时 sqlite3_open 打不开数据库现象数据库文件路径里有中文比如D:\项目数据\mydb.dbsqlite3_open返回SQLITE_CANTOPEN数据库文件明明存在就是打不开。原因sqlite3_open接收的是 UTF-8 编码路径MFC 里的 CString 在 Unicode 工程里是 UTF-16 编码。直接把 CString 转成 char* 用的是系统 ANSI 码页GBK并不是 UTF-8。SQLite3 内部按 UTF-8 解析路径遇到 GBK 字节流就认不出来。解决用sqlite3_open_v2加上sqlite3_filename那套太绕最简单的方法是先把 CString 转成 UTF-8 char*。Windows 下有现成 APIstatic char* ToUTF8(const CString str) { int len WideCharToMultiByte(CP_UTF8, 0, str, -1, nullptr, 0, nullptr, nullptr); char* buf new char[len]; WideCharToMultiByte(CP_UTF8, 0, str, -1, buf, len, nullptr, nullptr); return buf; }调用sqlite3_open_v2(ToUTF8(strPath), ...)就正常了。注意这个转换只针对文件路径SQL 语句里的字符串数据也要走同样的转换否则查中文一样翻车。4.3 坑三回调函数里用 MFC 类导致死锁现象在sqlite3_exec的回调函数里调用CString::Format或访问某个窗口的成员变量程序突然卡死或者弹出一个奇怪的断言框。原因sqlite3_exec的回调是在 sqlite3 内部线程触发的如果你的库开了多线程模式而 MFC 的很多类和全局函数并不是任意线程都能乱调。尤其是你在回调里操作了界面资源而主线程正占着窗口消息泵两个线程互相等对方释放资源直接死锁。解决回调函数里只做纯数据收集把结果拷贝到一个局部容器里回到主线程再处理。上面 QueryContext 那个设计就是基于这个原则。如果你非要在回调里访问 MFC 类的静态方法至少确保那个方法不依赖线程局部状态并且不要试图更新窗口。4.4 坑四事务批量插入慢到怀疑人生现象循环里执行一万次 INSERT每次单独sqlite3_exec跑了十几秒还没结束硬盘灯狂闪。原因SQLite3 默认每次 INSERT 都开启一个隐式事务事务要写日志、刷磁盘。一万次就是一万次磁盘同步当然慢。解决手动包一个大事务sqlite3_exec(m_db, BEGIN, nullptr, nullptr, nullptr); for (...) { // 执行 INSERT } sqlite3_exec(m_db, COMMIT, nullptr, nullptr, nullptr);我实际测过批量插入一万行不开事务大约 20 秒开了事务后不到 0.5 秒。那之后我为封装类加了一个ExecWithoutAutoCommit方法专门配合BEGIN/COMMIT使用逻辑上更清晰。4.5 坑五关闭数据库前忘了 Finalize 导致文件锁现象调用sqlite3_close返回SQLITE_BUSY数据库文件被占用无法移动或删除。在资源管理器里怎么删都删不掉。原因程序中某个sqlite3_stmt没有调用sqlite3_finalize释放。SQLite3 关闭数据库时会检查是否有未释放的 prepared statement一个都不放过。解决在封装类的析构函数里做了清理还不够最好在每条语句执行完的入口统一sqlite3_finalize。我后来写了一个 RAII 风格的小工具类class StmtGuard { public: StmtGuard(sqlite3_stmt* stmt) : m_stmt(stmt) {} ~StmtGuard() { if (m_stmt) sqlite3_finalize(m_stmt); } private: sqlite3_stmt* m_stmt; };用StmtGuard guard(stmt);包住每一条预处理语句无论中间是否出错析构都会自动释放。从那以后我再也没遇到过文件锁的问题。5. 进阶把 SQLite3 封装成支持事务的 C 类顺便解决并发读前面的封装类已经能应付单线程场景但真实 MFC 程序里经常会有工作线程在后台查询数据库主线程同时在界面上做别的操作。SQLite3 虽然支持多线程但默认配置下同一时间只能有一个连接写库读可以并发。我用的策略是一个连接只在单线程内使用跨线程就用一个新的只读连接。数据库文件本身支持多连接访问只要不是同时写问题不大。给封装类加两个方法就够BOOL CSQLite3DB::BeginTransaction() { return Exec(_T(BEGIN IMMEDIATE;)); } BOOL CSQLite3DB::CommitTransaction() { return Exec(_T(COMMIT;)); }BEGIN IMMEDIATE和普通的BEGIN区别在于它会在事务一开始就获取写锁避免两个线程同时BEGIN之后一个写一个等最后升级死锁。对于桌面应用来说这个锁粒度足够如果你要做高并发服务器端那该换 PostgreSQL不是 SQLite3 的活。并发读的典型场景是后台线程定期把数据库里的记录加载到std::vector更新到 ListView同时主线程可能做修改操作。我的做法是后台线程用独立的只读连接声明为SQLITE_OPEN_READONLY打开时就不会和写连接互相阻塞。代码如下sqlite3* pReadDb nullptr; sqlite3_open_v2(ToUTF8(strPath), pReadDb, SQLITE_OPEN_READONLY, nullptr);注意SQLITE_OPEN_READONLY连接不能做任何写操作如果你在同一个连接里又跑写语句sqlite3 会返回SQLITE_READONLY错误。所以这种只读连接只用于查询写完数据的主连接照旧。这件事给我留下一个习惯每次写完数据库操作代码我都会强制走一遍自查清单——检查路径有没有做 UTF-8 转换、每个 sqlite3_stmt 是不是都 finalize、批量操作有没有套事务、回调里是不是只做了纯数据收集以及 Debug 和 Release 的 lib 是不是对应上了。这套检查一遍下来基本不会栽在那些野路子上。希望这份拆解能帮到你让你接到类似需求的时候少走两晚上弯路。本文还有配套的精品资源点击获取
