Qt C++ 解析 JSON 完全指南：从核心概念到工业级实战

文章目录

[Qt C++ 解析 JSON 完全指南：从核心概念到工业级实战](#Qt C++ 解析 JSON 完全指南：从核心概念到工业级实战)
- [一、核心概念：Qt JSON 的四大基石](#一、核心概念：Qt JSON 的四大基石)
- - [1. `QJsonDocument` (文档/解析器)](#1. QJsonDocument (文档/解析器))
  - [2. `QJsonObject` (对象字典：对应 `{}`)](#2. QJsonObject (对象字典：对应 {}))
  - [3. `QJsonArray` (数组列表：对应 `\[\]`)](#3. QJsonArray (数组列表：对应 []))
  - [4. `QJsonValue` (未确定类型的盲盒)](#4. QJsonValue (未确定类型的盲盒))
- [二、工业级实战演练](#二、工业级实战演练)
- - [第一步：定义 C++ 数据结构 (Data Models)](#第一步：定义 C++ 数据结构 (Data Models))
  - 第二步：编写解析流水线 (The Loader)
- [三、高频避坑指南（Best Practices）](#三、高频避坑指南（Best Practices）)

Qt C++ 解析 JSON 完全指南：从核心概念到工业级实战

在 C++ 中解析 JSON 往往比在 Python 或 JavaScript 中繁琐得多。这是因为 JSON 是一棵"无类型"的树，而 C++ 是强类型语言。为了安全地将文本转换为 C++ 结构体，Qt 框架提供了一套专门的解析类。

本文将详细拆解 Qt 处理 JSON 的核心逻辑，并提供一份可以直接用于生产环境的配置解析代码模板。

一、核心概念：Qt JSON 的四大基石

在 Qt 中处理 JSON，只需牢记以下四个核心类。它们层层递进，共同完成了"文本 -> 强类型数据"的转换。

1. `QJsonDocument` (文档/解析器)

作用：负责文本与 JSON 树之间的相互转换。
理解：它是最外层的"集装箱"。把从文件里读出来的纯文本字符串（QByteArray）扔给它，它负责验证格式，并将其转化为 Qt 认识的 JSON 对象。

2. `QJsonObject` (对象字典：对应 `{}`)

作用：表示 JSON 中的大括号 {}。
理解：本质是一个键值对（Key-Value）字典。必须通过字符串名称（Key）去寻找里面的内容，例如 obj["port"]。

3. `QJsonArray` (数组列表：对应 `[]`)

作用：表示 JSON 中的中括号 []。
理解：本质是一个数组。内部元素没有名称，只能通过索引（如 arr.at(0)）去遍历获取。

4. `QJsonValue` (未确定类型的盲盒)

作用：表示 JSON 树上的任何一个节点。
理解：这是最核心的概念 。无论是从 QJsonObject 还是 QJsonArray 中提取出来的数据，**在明确类型之前，统一叫 QJsonValue**。
它可能是一个字符串、一个整数、甚至嵌套着另一个 QJsonObject。在使用前，必须先判断类型，再强转 （例如先 val.isObject()，再 val.toObject()）。

二、工业级实战演练

假设我们需要解析如下的 config.json 配置文件：

json 复制代码

{
  "endpoint": {
    "host": "192.168.1.100",
    "port": 502
  },
  "items": [
    {
      "name": "Temperature",
      "address": 0,
      "scale": 0.1
    }
  ]
}

为了彻底解耦，我们采用"数据图纸 (Struct)"与"解析器 (Loader)"分离的架构。

第一步：定义 C++ 数据结构 (Data Models)

定义与 JSON 节点一一对应的强类型结构体，并赋予默认值（防呆机制）。

cpp 复制代码

// config.h
#pragma once
#include <QString>
#include <QVector>

struct ModbusEndpoint {
    QString host{"127.0.0.1"}; // 默认值
    int port{502};
};

struct PollItem {
    QString name;
    int address{0};
    double scale{1.0};
};

struct AppConfig {
    ModbusEndpoint endpoint;
    QVector<PollItem> items;
};

第二步：编写解析流水线 (The Loader)

解析的核心思路是"剥洋葱"：读取文件 -> 转为 Document -> 提取根 Object -> 分发给私有函数逐个拆解。

cpp 复制代码

#include <QFile>
#include <QJsonDocument>
#include <QJsonObject>
#include <QJsonArray>
#include <QJsonValue>
#include <QDebug>

class ConfigLoader {
public:
    // 1. 主入口：从文件加载
    AppConfig loadFromFile(const QString& filePath) {
        AppConfig config;
        QFile file(filePath);
        
        if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
            qWarning() << "无法打开文件:" << filePath;
            return config;
        }
        
        QJsonParseError error;
        QJsonDocument doc = QJsonDocument::fromJson(file.readAll(), &error);
        file.close();
        
        if (error.error != QJsonParseError::NoError || !doc.isObject()) {
            qWarning() << "JSON 解析失败:" << error.errorString();
            return config;
        }
        
        // 提取根节点 {}，扔给下游处理
        return parseRoot(doc.object()); 
    }

private:
    // 2. 根节点分发
    AppConfig parseRoot(const QJsonObject& rootObj) {
        AppConfig config;
        
        // 检查是否存在 "endpoint" 且确认为 Object ({})
        if (rootObj.contains("endpoint") && rootObj["endpoint"].isObject()) {
            config.endpoint = parseEndpoint(rootObj["endpoint"].toObject());
        }
        
        // 检查是否存在 "items" 且确认为 Array ([])
        if (rootObj.contains("items") && rootObj["items"].isArray()) {
            config.items = parseItems(rootObj["items"].toArray());
        }
        
        return config;
    }

    // 3. 拆解具体的 Object
    ModbusEndpoint parseEndpoint(const QJsonObject& obj) {
        ModbusEndpoint endpoint;
        // toString/toInt 内部可传入默认值。若 JSON 中无此键，则返回默认值
        endpoint.host = obj["host"].toString(endpoint.host);
        endpoint.port = obj["port"].toInt(endpoint.port);
        return endpoint;
    }

    // 4. 拆解具体的 Array
    QVector<PollItem> parseItems(const QJsonArray& arr) {
        QVector<PollItem> items;
        for (int i = 0; i < arr.size(); ++i) {
            QJsonValue val = arr.at(i);
            
            // 数组里装的必须是对象 {}，如果不是，跳过
            if (!val.isObject()) continue;
            
            QJsonObject itemObj = val.toObject();
            PollItem item;
            item.name = itemObj["name"].toString();
            item.address = itemObj["address"].toInt(item.address);
            item.scale = itemObj["scale"].toDouble(item.scale);
            
            items.append(item);
        }
        return items;
    }
};

三、高频避坑指南（Best Practices）

永远不要链式暴力读取

❌ 错误示范：QString ip = doc.object()["endpoint"].toObject()["host"].toString();
原因：如果配置文件中缺少 endpoint 节点，或者它被用户改成了数组，上述链式调用会直接导致程序空指针崩溃。
✅ 正确做法：必须先使用 .contains() 检查键是否存在，并使用 .isObject() / .isArray() 判断类型后再提取。

善用 QJsonValue 的默认值参数

很多时候配置文件可能缺少某个字段，与其写一堆 if(obj.contains("port"))，不如直接利用结构体的默认值：
obj["port"].toInt( 结构体原本的默认值 );
这样只要 JSON 里没写，程序就会安全地使用代码里预设的安全值。

类型强转的后缀对应

提取字符串：toString()
提取整数：toInt()
提取浮点数：toDouble()
提取布尔值：toBool()

总结：在 C++ 中解析 JSON 是一项严谨的工作，将"数据结构声明(Struct)"与"解析逻辑(Loader)"拆分，配合逐层的 isObject/isArray 安全检查，是构建高健壮性工业级软件的不二法门。

Qt C++ 解析 JSON 完全指南：从核心概念到工业级实战

文章目录