文件与数据持久化
文件流、QSettings、JSON 与 XML 持久化
#先选对格式
持久化不是"把东西存下来"那么简单,选错格式会在半年后反噬你。一个真实的教训:把用户工程文件存成自定义分隔符文本,半年后需求变了要加字段,老文件全部兼容不了,只能写一堆脏代码做猜测式解析。所以第一步永远是选格式,第二步才是写 IO。
判断依据有三条:数据是否要给人看、是否要给别的程序读、结构会不会变。三者都不需要就用二进制;需要前两者就选文本类格式;结构会变就必须带版本号。先看一张决策表:
| 格式 | Qt 类 | 优点 | 缺点 | 适用 |
|---|---|---|---|---|
| 文本 | QFile + QTextStream | 人可读、最简单 | 无结构、解析脆弱 | 日志、纯文本导出 |
| 二进制 | QDataStream | 快、体积小、类型安全 | 不可读、版本兼容要自己管 | 内部缓存、进程间传递 |
| 配置 | QSettings | 跨平台(ini/注册表/plist) | 只适合小量键值 | 用户偏好、窗口状态 |
| JSON | QJsonDocument | 结构化、通用、易调试 | 无注释、无 schema | 接口数据、工程文件 |
| XML | QXmlStreamReader/Writer | 有 schema、可注释 | 冗长 | 传统行业格式、配置文件 |
口诀:配置用 QSettings,结构化数据用 JSON,大批量内部数据用 QDataStream。
#QFile 与文本流
QFile 是 QIODevice 的子类,所有 Qt IO 都遵循同一个模式:open() → 读写 → close()(或依赖 RAII 自动关闭)。
#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 程序时非常方便。
#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;
}
}
}两个必须遵守的约定:
setVersion()。不同 Qt 版本的二进制格式可能不同。不锁版本,你的数据文件在升级 Qt 后可能读不出来。锁定了版本号,Qt 保证向后兼容。- 用定宽整数。
int在不同平台可能是 16/32/64 位,序列化必须用qint32/quint32/qint64等明确宽度的类型,否则跨平台传输会错位。
QDataStream 还有一个杀手级用法:QByteArray + QDataStream 可以序列化任意 Qt 类型用于进程间通信或剪贴板,配合 QSharedMemory 使用非常顺手。
#QSettings:跨平台配置
QSettings 屏蔽了平台差异:Windows 上写注册表,macOS 上写 plist,Linux 上写 ~/.config/<组织>/<应用>.conf。你也可以强制用 INI 文件,便于调试和 portable 版本。
#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) |
#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;
}三个防御要点:
- 永远传
QJsonParseError。不传的话解析失败只能得到isNull()的QJsonDocument,不知道哪里错了。 - 检查类型再取。
doc.object()在 doc 是数组时会返回空对象,静默失败。先isObject()/isArray()。 - 取值带默认值。
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。
#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 | 桌面 |
#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_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。
#小结
- 格式选择口诀:配置用
QSettings,结构化数据用 JSON,大批量内部数据用QDataStream。 - 文本读写必须显式指定 UTF-8 编码,否则 Windows 下会按 GBK 处理导致乱码。
QDataStream必须setVersion()锁定版本,并使用qint32等定宽类型保证跨平台。- JSON 解析务必传
QJsonParseError、检查isObject()、取值带默认值,并保留version字段以便格式演进。 - 路径用
QStandardPaths查询并mkpath()创建;临时数据用QTemporaryFile/QTemporaryDir自动清理,重要文件用"临时文件 + rename"实现原子写入。
#练习
- 写一个日志工具类,用
QTextStream按天分文件写入 UTF-8 日志,并自动清理 30 天前的旧文件。 - 用
QDataStream序列化一个包含QString、QList<int>、QColor的结构体到QByteArray,再反序列化回来验证一致。 - 实现一个支持版本迁移的配置文件:v1 为纯键值,v2 改为嵌套结构,读取时自动将 v1 升级为 v2 并存回。
- 用
QXmlStreamWriter导出一个多层级的部门-员工 XML,再用QXmlStreamReader解析回内存,并统计每个部门的人数。