C++ ORM框架 QxORM 快速入门：从模型定义到数据库操作

江岸

发布时间：2026-10-15| 6人浏览过

原创

QxORM 是一款轻量级的 C++ ORM（对象关系映射）库，常用于 Qt 应用中简化数据库交互。它支持 SQLite、MySQL 等主流数据库，并提供 JSON、XML 及二进制序列化功能。本文将演示如何通过定义模型类、建立连接、执行 CRUD 操作及序列化，快速上手 QxORM 的核心流程。

结果与目标

通过本教程，您将在项目中集成 QxORM 框架，能够以面向对象的方式对 SQLite 数据库进行创建表、增删改查操作，并将对象数据导出为 JSON 文本或二进制流，无需编写繁琐的 SQL 语句。

准备条件

已安装 Qt 开发环境及 QxORM 库依赖。
项目代码需关联 QxORM 头文件与编译好的动态/静态库。

真实操作顺序

第1步：建立对象模型

目的：定义 C++ 结构体并将其映射到数据库表，使普通类具备持久化能力。

入口：项目头文件（如 QxModels.h）和源文件（如 QxModels.cpp）。

动作：在头文件中定义结构体，并在源文件中注册属性。

头文件 QxModels.h 定义数据模型：

#include "precompiled.h"
/***************************************************************
* @projectName  pluqt
* @brief        自定义ORM模型
* @author       lzw
* @date         2022-01-04
***************************************************************/
struct User
{
    long id;
    QString name;
    int age;
    QString hobbies;
};
// 必须添加此宏以启用 ORM 功能
QX_REGISTER_HPP_QX_DLL1(User, qx::trait::no_base_class_defined, 1)

源文件 QxModels.cpp 中实现注册逻辑，设置表名及各字段映射：

#include "precompiled.h"
#include "qxmodels.h"
#include <QxOrm_Impl.h>

QX_REGISTER_CPP_QX_DLL1(User)

namespace qx
{
    template <> void register_class(QxClass<User> & t)
    {
        // 设置对应的数据库表名
        t.setName("User");
        
        // 注册主键映射：成员变量指向 db 列名 "id"
        t.id(&User::id, "id");
        
        // 注册普通属性：(成员指针, db列名, 版本号)
        t.data(&User::name, "name", 1);
        t.data(&User::age, "age");
        t.data(&User::hobbies, "hobbies");
    }
}

第2步：连接数据库

目的：初始化全局数据库驱动配置，指定本地文件路径。

入口：程序启动初始化模块或专门的 DAO 层。

动作：配置 SQLite 驱动参数。

以下为配置 SQLite 连接的示例代码（以本地文件数据库为例）：

QString in_db = QCoreApplication::applicationDirPath();
in_db.append("/database/plulocal.db");

// 可选：清除旧数据库以避免重复建表报错
// QFile::remove(in_db);

// 获取单例并配置
auto db = qx::QxSqlDatabase::getSingleton();
db->setDriverName("QSQLITE");
db->setDatabaseName(in_db);
db->setHostName("localhost");
db->setUserName("root");
db->setPassword("");

// 设置占位符风格及调试开关
db->setSqlPlaceHolderStyle(qx::QxSqlDatabase::ph_style_2_point_name);
db->setTraceSqlQuery(true);   // 开启 SQL 打印便于调试
db->setTraceSqlRecord(false);

第3步：执行 CRUD 操作

目的：完成自动建表、批量插入及各类查询。

入口：业务逻辑处理函数。

动作：调用 qx::dao 命名空间下的方法。

自动建表：根据模型定义直接生成表格。

// 自动创建 User 表
QSqlError createErr = qx::dao::create_table<User>();
if(createErr.isValid()) {
    qDebug() << "Table creation failed:" << createErr.text();
}

批量插入数据：模拟生成测试记录。

// 产生10条模拟数据
for(int in_idx=0; in_idx<10; ++in_idx)
{
    auto in_user = new User();
    in_user->name = "lzw" + QString::number(in_idx);
    in_user->age = 20 + in_idx;
    in_user->hobbies = "play";
    
    QSqlError err = qx::dao::insert(in_user);
    if(err.isValid()) {
        qDebug() << "Insert failed:" << err.text();
    }
}

查询单条记录：根据 ID 检索。

User in_pointUser; 
in_pointUser.id = 3;

// fetch_by_id 会自动填充 in_pointUser.name, age 等字段
QSqlError err1 = qx::dao::fetch_by_id(in_pointUser);
qDebug() << "Fetched Name:" << in_pointUser.name;

复杂条件查询：使用自定义 SQL 或内置辅助器查询集合。

// 定义集合类型用于存储多个对象
typedef std::shared_ptr<User> UserPtr;
typedef qx::QxCollection<long, UserPtr> UserList;

UserList in_userList;

// 编写原生 SQL (QxORM 完全支持原生 SQL)
qx_query in_query("select * from user where age >=20 and age <=25");

QSqlError err2 = qx::dao::execute_query(in_query, in_userList);

if (!err2.isValid() && in_userList.count() > 0) {
    // 将结果输出到控制台
    qx::dump(in_userList);
} else {
    qDebug() << "Query error:" << err2.text();
}

第4步：数据序列化

目的：将内存中的对象或集合保存为外部文件格式（JSON 或 Binary）。

动作：调用 qx::serialization 接口。

// 1. 导出单个对象为二进制流文件
// 注意：to_file 需要包含正确的序列化头文件
qx::serialization::qt::to_file(in_pointUser, "user.txt");

// 2. 导出对象集合列表为 JSON 文本文件
// 需要包含 json 相关头文件
qx::serialization::json::to_file(in_userList, "list_of_user.json");

简要总结

通过上述步骤，您可以看到 QxORM 极大地降低了 C++ 访问数据库的门槛。只需定义一次带有宏的结构体，后续的操作全部转化为标准的 C++ 类方法调用。相比传统手写 SQL，这种方式不仅减少了样板代码，还通过序列化扩展了数据交换的维度。以上就是 C++ QxORM ORM框架使用的详细内容，更多关于 Qt 数据持久化的资料请关注本站其它相关文章！