# JSON 解析与写入 —— 教学补充示例

> 对应方案书「C++方向 Day3」："Qt 文件 IO 操作与 JSON 等主流数据格式解析"。
> 仓库 `p03/ch11` 的 wiki 抓取内容覆盖了 `QFile`/`QTextStream`/`QDataStream`，
> 唯独没有 JSON，本示例是手工补写的教学补充，**不属于**
> `tools/gen_part3.py` 的生成产物。

## 概念

Qt 从 5.0 起自带 JSON 支持（`QtCore` 模块，不需要额外依赖第三方 JSON 库），
核心是四个类：

- `QJsonValue` —— 一个 JSON 值（字符串/数字/布尔/数组/对象/null）；
- `QJsonObject` —— 键值对集合，对应 JSON 里的 `{ ... }`；
- `QJsonArray` —— 值的列表，对应 JSON 里的 `[ ... ]`；
- `QJsonDocument` —— 顶层容器，负责整个文档和字节流（`QByteArray`）之间的
  相互转换（序列化/反序列化）。

与 `p03/ch11` 已有的 `QTextStream`/`QDataStream` 对比：那两个解决的是"文本行"
和"二进制结构体"的读写；JSON 解决的是"带层级结构的数据"（对象嵌数组嵌对象）的
读写，是目前最常见的配置文件/网络接口数据格式。

## 代码走读

见 [`qt_json_parse_write.cpp`](qt_json_parse_write.cpp)：

1. 用 `QJsonObject`/`QJsonArray` 构造一份"学员信息"数据；
2. `QJsonDocument(obj).toJson(QJsonDocument::Indented)` 序列化成带缩进的可读
   字节流（`QJsonDocument::Compact` 则是不带空白的紧凑格式，写文件/网络传输
   常用这个）；
3. `QJsonDocument::fromJson(bytes)` 反序列化回来，`.isObject()` 判断顶层类型后
   逐个字段取值。

这个示例不涉及 GUI，纯粹是数据结构的构造/序列化/反序列化，所以用
`QCoreApplication` 而不是 `QApplication`，不需要 `QT_QPA_PLATFORM=offscreen`。

## 验证方式

```bash
tools/run_qt.sh qt_json_parse_write
```

预期终端输出：先打印一段带缩进的 JSON 文本，再打印从中解析出的姓名/分数/标签。

## 练习方向（供任务卡引用）

- 把结果写入一个真实文件（结合 `p03/ch11/qfile_basic.cpp` 的 `QFile` 写法），
  再从文件读回来解析，构成一个完整的"落盘 JSON 配置"流程；
- 故意构造一段格式错误的 JSON 字符串喂给 `fromJson`，观察 `parsed.isNull()`
  为 `true` 时如何做错误提示（而不是让程序崩溃或读到脏数据）。

## 参考

- 本仓库对照：[`p03/ch11/qfile_basic.cpp`](../../../../p03/ch11/qfile_basic.cpp)、
  [`qtextstream_io.cpp`](../../../../p03/ch11/qtextstream_io.cpp)
- Qt 官方文档：*JSON Support in Qt*（doc.qt.io，选读·需联网）