QC++ / Qt 学习之路

文件与数据持久化

文件流、QSettings、JSON 与 XML 持久化

进阶第 30 / 48 章第四篇 · Qt 进阶

#先选对格式

持久化不是"把东西存下来"那么简单,选错格式会在半年后反噬你。一个真实的教训:把用户工程文件存成自定义分隔符文本,半年后需求变了要加字段,老文件全部兼容不了,只能写一堆脏代码做猜测式解析。所以第一步永远是选格式,第二步才是写 IO。

判断依据有三条:数据是否要给人看、是否要给别的程序读、结构会不会变。三者都不需要就用二进制;需要前两者就选文本类格式;结构会变就必须带版本号。先看一张决策表:

格式Qt 类优点缺点适用
文本QFile + QTextStream人可读、最简单无结构、解析脆弱日志、纯文本导出
二进制QDataStream快、体积小、类型安全不可读、版本兼容要自己管内部缓存、进程间传递
配置QSettings跨平台(ini/注册表/plist)只适合小量键值用户偏好、窗口状态
JSONQJsonDocument结构化、通用、易调试无注释、无 schema接口数据、工程文件
XMLQXmlStreamReader/Writer有 schema、可注释冗长传统行业格式、配置文件

口诀:配置用 QSettings,结构化数据用 JSON,大批量内部数据用 QDataStream。

#QFile 与文本流

QFile 是 QIODevice 的子类,所有 Qt IO 都遵循同一个模式:open() → 读写 → close()(或依赖 RAII 自动关闭)。

C++
#include <QFile>
#include <QTextStream>
#include <QDebug>

bool writeLog(const QString &path, const QStringList &lines)
{
    QFile f(path);
    // WriteOnly 会清空原文件;想追加用 QIODevice::Append
    if (!f.open(QIODevice::WriteOnly | QIODevice::Text)) {
        qWarning() << "无法写入:" << path << f.errorString();
        return false;
    }

    QTextStream out(&f);
    out.setEncoding(QStringConverter::Utf8);       // Qt 6:显式指定编码
    for (const QString &line : lines) {
        out << line << '\n';
    }
    // f 析构时自动 close(),也可显式 f.flush()
    return f.error() == QFile::NoError;
}

QStringList readLog(const QString &path)
{
    QFile f(path);
    if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) {
        return {};
    }

    QStringList result;
    QTextStream in(&f);
    in.setEncoding(QStringConverter::Utf8);
    while (!in.atEnd()) {
        result << in.readLine();
    }
    return result;
}

最容易出错的地方是编码。不加 setEncoding() 时,QTextStream 使用本地 8 位编码(Windows 中文环境是 GBK),你写出的 UTF-8 字符串在别人机器上乱码。Qt 6 提供了 QStringConverter::Utf8,务必显式写上——这一行代码的收益,远超你花两小时排查"为什么在我机器上好好的"。

另一个细节:QIODevice::Text 标志会在读取时把 \r\n 翻译成 \n,写入时反向翻译(仅在 Windows)。处理文本时加上它,处理二进制时绝不能加。

#QDataStream 二进制序列化

QDataStream 把 QVariant、QString、QList 等 Qt 类型序列化为字节流,读写双方都是 Qt 程序时非常方便。

C++
#include <QFile>
#include <QDataStream>
#include <QDebug>

struct Record {
    QString name;
    qint32  score = 0;
    double  ratio = 0.0;
};

// 让 Record 直接支持 QDataStream
QDataStream &operator<<(QDataStream &out, const Record &r)
{
    out << r.name << r.score << r.ratio;
    return out;
}

QDataStream &operator>>(QDataStream &in, Record &r)
{
    in >> r.name >> r.score >> r.ratio;
    return in;
}

void binaryDemo(const QString &path)
{
    QList<Record> data{{"张三", 95, 0.87}, {"李四", 88, 0.62}};

    {   // 写
        QFile f(path);
        if (!f.open(QIODevice::WriteOnly)) {
            return;
        }
        QDataStream out(&f);
        out.setVersion(QDataStream::Qt_6_5);      // 关键:锁定版本号
        out << quint32(data.size());              // 先写数量
        for (const Record &r : data) {
            out << r;
        }
    }

    {   // 读
        QFile f(path);
        if (!f.open(QIODevice::ReadOnly)) {
            return;
        }
        QDataStream in(&f);
        in.setVersion(QDataStream::Qt_6_5);       // 必须与写入方一致
        quint32 count = 0;
        in >> count;
        for (quint32 i = 0; i < count; ++i) {
            Record r;
            in >> r;
            qDebug() << r.name << r.score << r.ratio;
        }
    }
}

两个必须遵守的约定:

  1. setVersion()。不同 Qt 版本的二进制格式可能不同。不锁版本,你的数据文件在升级 Qt 后可能读不出来。锁定了版本号,Qt 保证向后兼容。
  2. 用定宽整数。int 在不同平台可能是 16/32/64 位,序列化必须用 qint32/quint32/qint64 等明确宽度的类型,否则跨平台传输会错位。

QDataStream 还有一个杀手级用法:QByteArray + QDataStream 可以序列化任意 Qt 类型用于进程间通信或剪贴板,配合 QSharedMemory 使用非常顺手。

#QSettings:跨平台配置

QSettings 屏蔽了平台差异:Windows 上写注册表,macOS 上写 plist,Linux 上写 ~/.config/<组织>/<应用>.conf。你也可以强制用 INI 文件,便于调试和 portable 版本。

C++
#include <QSettings>
#include <QCoreApplication>
#include <QRect>
#include <QDebug>

void settingsDemo()
{
    // 只设一次,全局生效
    QCoreApplication::setOrganizationName("MyCompany");
    QCoreApplication::setApplicationName("MyApp");

    QSettings s;                                  // 使用组织名/应用名定位
    s.setValue("user/name", "张三");
    s.setValue("user/rememberMe", true);
    s.setValue("window/geometry", QRect(100, 100, 800, 600));
    s.setValue("recentFiles", QStringList{"/a.txt", "/b.txt"});

    s.beginGroup("view");
    s.setValue("zoom", 1.25);                     // → view/zoom
    s.endGroup();

    s.sync();                                     // 立即落盘(通常不必手动调)

    // 读取,带默认值
    QString name = s.value("user/name", "匿名").toString();
    double  zoom = s.value("view/zoom", 1.0).toDouble();
    qDebug() << name << zoom;
}

void iniDemo(const QString &path)
{
    // 强制 INI 格式,便于 portable 分发
    QSettings s(path, QSettings::IniFormat);
    s.setIniCodec("UTF-8");                       // Qt 6:用 setIniCodec(const char*)
    s.setValue("server/host", "127.0.0.1");
    s.setValue("server/port", 8080);
}

QSettings 支持所有 QVariant 能装的类型,包括 QRect、QStringList、QByteArray、QColor。它是异步写入的:修改先进内存,进程正常退出或事件循环空闲时才落盘。程序可能崩溃的场景下,关键配置写完后调一次 sync()。

读取时用 value(key, defaultValue) 而非 value(key),能避免首次启动时拿到无效 QVariant 导致 .toInt() 返回 0 的隐性 bug。

#JSON:现代结构化数据首选

Qt 的 JSON 类是值语义 + 隐式共享的,可以像内置类型一样拷贝传递,不用担心性能。

核心类只有四个:

类含义
QJsonDocument整个文档,负责 toJson() / fromJson() 解析
QJsonObject键值对象 { }
QJsonArray数组 [ ]
QJsonValue任意值(可转 String/Double/Bool/Array/Object)
C++
#include <QJsonDocument>
#include <QJsonObject>
#include <QJsonArray>
#include <QFile>
#include <QDebug>

struct Task {
    QString title;
    bool    done = false;
    int     priority = 1;
};

bool saveTasks(const QString &path, const QList<Task> &tasks)
{
    QJsonArray arr;
    for (const Task &t : tasks) {
        QJsonObject o;
        o["title"]    = t.title;
        o["done"]     = t.done;
        o["priority"] = t.priority;
        arr.append(o);
    }

    QJsonObject root;
    root["version"] = 1;
    root["tasks"]   = arr;

    QFile f(path);
    if (!f.open(QIODevice::WriteOnly)) {
        return false;
    }
    // Indented 便于人读;Compact 用于网络传输
    f.write(QJsonDocument(root).toJson(QJsonDocument::Indented));
    return true;
}

QList<Task> loadTasks(const QString &path)
{
    QFile f(path);
    if (!f.open(QIODevice::ReadOnly)) {
        return {};
    }

    QJsonParseError err;
    QJsonDocument doc = QJsonDocument::fromJson(f.readAll(), &err);
    if (err.error != QJsonParseError::NoError) {
        qWarning() << "JSON 解析失败:" << err.errorString()
                   << ",位置:" << err.offset;
        return {};
    }
    if (!doc.isObject()) {
        return {};
    }

    QList<Task> result;
    const QJsonArray arr = doc.object().value("tasks").toArray();
    for (const QJsonValue &v : arr) {
        QJsonObject o = v.toObject();
        Task t;
        t.title    = o.value("title").toString();
        t.done     = o.value("done").toBool(false);
        t.priority = o.value("priority").toInt(1);
        result << t;
    }
    return result;
}

三个防御要点:

  1. 永远传 QJsonParseError。不传的话解析失败只能得到 isNull() 的 QJsonDocument,不知道哪里错了。
  2. 检查类型再取。doc.object() 在 doc 是数组时会返回空对象,静默失败。先 isObject() / isArray()。
  3. 取值带默认值。toInt(1)、toString(QString()) 比 toInt() 健壮。

root["version"] 这个字段是版本兼容的关键:半年后格式变了,读到 version == 1 走旧解析分支,version == 2 走新分支。不做版本标记的工程文件一旦改格式,老用户的文件就全废了。

#XML:用 QXmlStreamReader

Qt 提供两套 XML API:DOM(QDomDocument,一次性载入内存建树)和流(QXmlStreamReader/QXmlStreamWriter,边读边解析)。

结论:新代码一律用流。DOM 会把整个文档读入内存并构建对象树,一个 100MB 的 XML 可能吃掉 1GB 内存;而流 API 是单向、增量、常量内存的。只有当文档很小且需要随机访问/修改时才考虑 DOM。

C++
#include <QFile>
#include <QXmlStreamReader>
#include <QXmlStreamWriter>
#include <QDebug>

struct Book { QString isbn, title, author; };

// 读取:状态机式解析
QList<Book> parseBooks(const QString &path)
{
    QList<Book> books;
    QFile f(path);
    if (!f.open(QIODevice::ReadOnly | QIODevice::Text)) {
        return books;
    }

    QXmlStreamReader xml(&f);
    while (!xml.atEnd()) {
        xml.readNext();
        if (!xml.isStartElement() || xml.name() != QStringLiteral("book")) {
            continue;
        }
        Book b;
        b.isbn = xml.attributes().value("isbn").toString();
        while (!(xml.isEndElement() && xml.name() == QStringLiteral("book")) && !xml.atEnd()) {
            xml.readNext();
            if (!xml.isStartElement()) {
                continue;
            }
            if (xml.name() == QStringLiteral("title")) {
                b.title = xml.readElementText();
            } else if (xml.name() == QStringLiteral("author")) {
                b.author = xml.readElementText();
            }
        }
        books << b;
    }

    if (xml.hasError()) {
        qWarning() << "XML 错误:" << xml.errorString()
                   << "行" << xml.lineNumber();
    }
    return books;
}

// 写入
bool writeBooks(const QString &path, const QList<Book> &books)
{
    QFile f(path);
    if (!f.open(QIODevice::WriteOnly | QIODevice::Text)) {
        return false;
    }

    QXmlStreamWriter w(&f);
    w.setAutoFormatting(true);                // 自动缩进
    w.setAutoFormattingIndent(2);
    w.writeStartDocument();
    w.writeStartElement("library");

    for (const Book &b : books) {
        w.writeStartElement("book");
        w.writeAttribute("isbn", b.isbn);
        w.writeTextElement("title", b.title);
        w.writeTextElement("author", b.author);
        w.writeEndElement();                  // book
    }

    w.writeEndElement();                      // library
    w.writeEndDocument();
    return true;
}

QXmlStreamReader 的核心是一个 while 循环 + readNext()。要注意 readElementText() 会把光标推进到结束标签之后,所以循环条件里要用 isEndElement() 判断,否则会多读一次导致跳过元素——这是流解析最经典的坑。

#临时文件与标准目录

永远不要硬编码路径。/tmp、`C:\Users、~/Library 在不同平台完全不同,用 QStandardPaths` 查询:

枚举典型位置
AppConfigLocation配置目录
AppDataLocation应用数据目录
DocumentsLocation用户文档
DownloadLocation下载目录
TempLocation临时目录
CacheLocation缓存目录(可被系统清理)
DesktopLocation桌面
C++
#include <QStandardPaths>
#include <QTemporaryFile>
#include <QTemporaryDir>
#include <QDir>
#include <QDebug>

void pathsDemo()
{
    // 配置目录(会自动带组织名/应用名)
    const QString configDir = QStandardPaths::writableLocation(
        QStandardPaths::AppConfigLocation);
    QDir().mkpath(configDir);                 // 务必先创建!
    qDebug() << "配置目录:" << configDir;

    // 拼接路径用 QDir::filePath 或 / 运算符,别手写分隔符
    const QString dbPath = QDir(configDir).filePath("data.db");
}

void tempDemo()
{
    // 临时文件:析构即删除,保证不残留
    QTemporaryFile tmp;
    tmp.setAutoRemove(true);                  // 默认就是 true
    if (tmp.open()) {
        tmp.write("中间结果");
        tmp.close();
        qDebug() << "临时文件:" << tmp.fileName();  // 系统生成的唯一名字

        // 常用模式:先写临时文件,成功后再 rename 到目标位置
        const QString target = QDir::temp().filePath("result.dat");
        QFile::remove(target);                // rename 前必须先删除目标
        tmp.rename(target);
    }

    // 临时目录:批量处理完后整体删除
    QTemporaryDir dir;
    if (dir.isValid()) {
        QFile(QDir(dir.path()).filePath("part1.bin")).open(QIODevice::WriteOnly);
        // dir 析构时递归删除整个目录
    }
}

QStandardPaths::writableLocation() 只返回路径字符串,不会帮你创建目录,写入前必须 QDir().mkpath()。

QTemporaryFile 的一个高级用法是"原子写入":先把数据完整写入临时文件,确认无误后 rename() 到目标路径。这样即使写入过程中崩溃,目标文件也不会处于半损坏状态。

#CMake 配置

本章所有功能都在 Qt6::Core 中,无需额外模块:

CMake
cmake_minimum_required(VERSION 3.16)
project(PersistenceDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Core)

qt_standard_project_setup()

qt_add_executable(PersistenceDemo
    main.cpp
    battery.cpp
)

target_link_libraries(PersistenceDemo PRIVATE Qt6::Core)

需要界面时把 Core 换成 Widgets 并加 find_package(Qt6 REQUIRED COMPONENTS Widgets)。

Qt 5 提示:编码设置差异最大。Qt 5 用 out.setCodec("UTF-8") 和 s.setIniCodec("UTF-8"),Qt 6 改为 out.setEncoding(QStringConverter::Utf8) 和 s.setIniCodec("UTF-8")(后者签名变为 const char*)。此外 Qt 6 中 QStringConverter 是新的编码枚举类型,Qt 5 无此 API。

#小结

  1. 格式选择口诀:配置用 QSettings,结构化数据用 JSON,大批量内部数据用 QDataStream。
  2. 文本读写必须显式指定 UTF-8 编码,否则 Windows 下会按 GBK 处理导致乱码。
  3. QDataStream 必须 setVersion() 锁定版本,并使用 qint32 等定宽类型保证跨平台。
  4. JSON 解析务必传 QJsonParseError、检查 isObject()、取值带默认值,并保留 version 字段以便格式演进。
  5. 路径用 QStandardPaths 查询并 mkpath() 创建;临时数据用 QTemporaryFile/QTemporaryDir 自动清理,重要文件用"临时文件 + rename"实现原子写入。

#练习

  1. 写一个日志工具类,用 QTextStream 按天分文件写入 UTF-8 日志,并自动清理 30 天前的旧文件。
  2. 用 QDataStream 序列化一个包含 QString、QList<int>、QColor 的结构体到 QByteArray,再反序列化回来验证一致。
  3. 实现一个支持版本迁移的配置文件:v1 为纯键值,v2 改为嵌套结构,读取时自动将 v1 升级为 v2 并存回。
  4. 用 QXmlStreamWriter 导出一个多层级的部门-员工 XML,再用 QXmlStreamReader 解析回内存,并统计每个部门的人数。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。