Jsoncpp
JsonUtils 工具类使用说明
一、工具概述
本工具基于 Jsoncpp 1.8.0+ 封装，支持 C++11+ 标准，提供 JSON 序列化 / 反序列化核心能力：
- 内存级：Json::Value ↔ JSON 字符串（支持紧凑 / 格式化、宽松 / 严格模式）
- 文件级：Json::Value ↔ 本地 JSON 文件（直接读写，无需手动处理文件流）
- 健壮性：完善的参数校验、异常捕获、精细化错误码反馈，避免内存泄漏 / 程序崩溃
二、前置准备步骤
1. 环境依赖
- 编译器：需支持 C++11 及以上（g++ 5.0+/MSVC 2015+）
- 库依赖：已集成 Jsoncpp 1.8.0+，编译时需链接-ljsoncpp（Linux）/ 引入库文件（Windows）
2. 代码集成
- 将本文件保存为 JsonUtils.h，在业务代码中通过
#include "JsonUtils.h"引入 - 所有接口封装在 JsonUtils 命名空间内，避免全局命名冲突
三、核心功能使用步骤
1. 序列化（Json::Value → JSON 字符串）
- 步骤 1：构建待序列化的 Json::Value 对象，填充业务数据；
- 步骤 2：（可选）创建 JsonSerializeConfig 配置对象，自定义格式（默认格式化模式）；
- 紧凑模式：config.setCompactMode ()（一行输出、无缩进，适用于生产环境）
- 格式化模式：config.setFormatMode (4)（4 空格缩进，适用于调试）
- 步骤 3：调用
JsonUtils::Serialize(val, dst_str, config)，参数详细解析：
| 参数名 | 详细说明 |
|---|---|
| val | 参数类型为const Json::Value &，必填项，代表待序列化的 JSON 数据对象；加 const 修饰表示函数内部不会修改该对象，加引用 & 是为了避免大对象拷贝，提升性能；若传入空的 Json::Value（val.isNull () 为 true），会直接返回无效参数错误 |
| dst_str | 参数类型为std::string &，必填项，代表接收序列化结果的输出字符串；加引用 & 是为了直接修改外部传入的字符串变量，无需返回大字符串，节省内存；调用前可初始化为空字符串，函数执行成功后会被赋值为 JSON 格式字符串 |
| config | 参数类型为const JsonSerializeConfig &，可选项，默认使用 JsonSerializeConfig 类的默认构造配置；加 const 修饰表示函数内部不会修改该配置对象，加引用 & 避免配置对象拷贝 |
- 步骤 4：通过返回的 JsonResult 判断结果：
- 成功：ret.isSuccess () → true，读取 dst_str 获取 JSON 字符串；
- 失败：ret.isSuccess () → false，通过 ret.err_msg 查看错误信息。
2. 反序列化（JSON 字符串 → Json::Value）
- 步骤 1：准备待解析的 JSON 字符串（宽松模式支持注释、末尾逗号）；
- 步骤 2：（可选）创建 JsonUnSerializeConfig 配置对象，自定义解析规则（默认宽松模式）；
- 宽松模式：config.setRelaxedMode ()（兼容注释、末尾逗号）
- 严格模式：config.setStrictMode ()（遵循 JSON 官方标准）
- 步骤 3：调用
JsonUtils::UnSerialize(src_str, val, config)，参数详细解析：
| 参数名 | 详细说明 |
|---|---|
| src_str | 参数类型为const std::string &，必填项，代表待解析的 JSON 格式字符串；加 const 修饰表示函数内部不会修改该字符串，加引用 & 避免长字符串拷贝，提升性能；若传入空字符串，会直接返回无效参数错误 |
| val | 参数类型为Json::Value &，必填项，代表接收反序列化结果的输出 JSON 数据对象；加引用 & 是为了直接修改外部传入的 Json::Value 变量，无需返回大对象，节省内存；调用前可初始化为空的 Json::Value，函数执行成功后会被赋值为解析后的 JSON 数据结构 |
| config | 参数类型为const JsonUnSerializeConfig &，可选项，默认使用 JsonUnSerializeConfig 类的默认构造配置；加 const 修饰表示函数内部不会修改该配置对象，加引用 & 避免配置对象拷贝 |
- 步骤 4：通过返回的 JsonResult 判断结果：
- 成功：ret.isSuccess () → true，从 val 中读取解析后的数据；
- 失败：ret.isSuccess () → false，通过 ret.err_msg 查看错误信息。
3. 文件级 JSON 操作
3.1 序列化到文件（Json::Value → 本地文件）
调用JsonUtils::SerializeToFile(val, file_path, config)，参数详细解析：
| 参数名 | 详细说明 |
|---|---|
| val | 参数类型为const Json::Value &，必填项，待序列化的 Json::Value 对象；特性同内存级序列化的 val 参数，禁止传入空的 Json::Value |
| file_path | 参数类型为const std::string &，必填项，文件保存路径；支持相对路径（如 "./test.json"）和绝对路径（如 "/home/user/test.json"）；若路径对应的目录不存在，或程序无文件写入权限，会返回文件操作失败错误；若目标文件已存在，会直接覆盖原有内容，无额外提示 |
| config | 参数类型为const JsonSerializeConfig &，可选项，序列化配置（同内存级序列化） |
3.2 从文件反序列化（本地文件 → Json::Value）
调用JsonUtils::UnSerializeFromFile(file_path, val, config)，参数详细解析：
| 参数名 | 详细说明 |
|---|---|
| file_path | 参数类型为const std::string &，必填项，待读取的 JSON 文件路径；支持相对路径和绝对路径；若文件不存在、路径错误，或程序无文件读取权限，会返回文件操作失败错误 |
| val | 参数类型为Json::Value &，必填项，接收结果的 Json::Value 对象；特性同内存级反序列化的 val 参数，函数执行成功后会被赋值为文件解析后的 JSON 数据 |
| config | 参数类型为const JsonUnSerializeConfig &，可选项，反序列化配置（同内存级反序列化） |
四、关键配置说明
1. 序列化配置（JsonSerializeConfig）
所有参数均为公有成员，支持直接赋值修改，也可通过便捷方法批量设置
| 配置项 | 类型 | 默认值 | 详细作用说明 |
|---|---|---|---|
| indentation | std::string | " " | 设置 JSON 字符串的缩进字符，紧凑模式下需设为空字符串（""），格式化模式可设为空格、制表符等 |
| line_length | int | 0 | 设置 JSON 字符串单行最大长度，0 代表无长度限制 |
| line_separator | std::string | "\n" | 设置 JSON 字符串的换行符，Windows 系统可设为 "\r\n"，Linux/Mac 系统使用默认值即可 |
| emit_utf8 | bool | true | 控制是否输出 UTF-8 原生字符，开启后中文不会被转义为 \uXXXX 格式，关闭则会转义，业务场景建议保持开启 |
| numeric_precision | int | 2 | 设置浮点数序列化后的保留小数位数，可根据业务需求自定义（如 1、3、0 等） |
| drop_null_placeholders | bool | true | 控制是否自动删除值为 null 的字段，开启后可减少 JSON 字符串体积，关闭则保留 null 字段 |
| compact_mode | bool | false | 标记是否启用紧凑模式，一般无需直接修改，通过便捷方法切换即可 |
便捷方法说明
- setCompactMode ()：一键切换为紧凑模式，自动将 indentation 设为 ""、line_length 设为 0、line_separator 设为""
- setFormatMode (int indent_spaces=2)：一键切换为格式化模式，自动根据传入的缩进空格数设置 indentation，line_length 设为 80，line_separator 设为 "\n"
2. 反序列化配置（JsonUnSerializeConfig）
所有参数均为公有成员，支持直接赋值修改，也可通过便捷方法批量设置
| 配置项 | 类型 | 默认值 | 详细作用说明 |
|---|---|---|---|
| strict_mode | bool | false | 控制是否启用严格解析模式，开启后严格遵循 JSON 官方标准，不兼容注释、末尾逗号等非标准格式；关闭则为宽松模式，兼容单行注释、多行注释、末尾逗号等格式 |
| comment_style | std::string | "All" | 设置宽松模式下支持的注释类型，仅在 strict_mode 为 false 时生效；可选值为 "All"（支持所有注释）、"Line"（仅支持单行注释）、"None"（不支持注释） |
| allow_trailing_comma | bool | true | 控制是否允许 JSON 字符串末尾存在逗号，仅在 strict_mode 为 false 时生效 |
便捷方法说明
- setRelaxedMode ()：一键切换为宽松模式，自动将 strict_mode 设为 false、comment_style 设为 "All"、allow_trailing_comma 设为 true
- setStrictMode ()：一键切换为严格模式，自动将 strict_mode 设为 true、comment_style 设为 "None"、allow_trailing_comma 设为 false
五、错误处理规范
所有接口返回 JsonResult 类型，该类型包含两个核心公有字段及一个便捷判断方法：
1. 核心字段
| 字段名 | 类型 | 枚举值 / 说明 |
|---|---|---|
| code | JsonErrorCode 枚举 | kSuccess（0）：操作成功kInvalidParam（1）：传入参数无效（如空的 Json::Value、空的 JSON 字符串、无效的文件路径等）kSerializeFailed（2）：序列化操作失败（如 Jsoncpp 内部序列化出错）kUnSerializeFailed（3）：反序列化操作失败（如 JSON 字符串格式错误、注释不兼容等）kNullPointer（4）：内部创建 StreamWriter/CharReader 对象时返回空指针，一般为 Jsoncpp 库异常kConfigError（5）：配置参数非法（一般极少出现，除非手动设置了无效的配置值） |
| err_msg | std::string | 错误描述字符串，内容为具体的错误原因，可直接打印用于问题定位 |
2. 便捷方法
- isSuccess ()：返回 bool 类型，当 code 为 kSuccess（0）时返回 true，其余情况返回 false；用于快速判断操作是否成功，无需手动判断枚举值
3. 使用规范
调用接口后必须优先通过 isSuccess () 方法判断操作是否成功，失败时禁止使用输出参数（如 dst_str、val）的内容；失败场景下可通过 err_msg 字段直接定位问题根源，也可通过 code 字段区分错误类型，便于业务侧针对性处理不同异常场景（如文件权限错误、参数错误、格式错误等）。
六、补充注意事项
- 内存安全：所有 Jsoncpp 核心操作对象（StreamWriter、CharReader）均由 std::unique_ptr 智能指针管理，无需手动释放内存，杜绝内存泄漏风险；
- 编码规范：emit_utf8 参数默认开启，需确保业务侧传入 / 读取的字符串及文件均为 UTF-8 编码，避免中文乱码；
- 空值处理：序列化时 drop_null_placeholders 默认开启，若业务场景需保留 null 字段需手动将该参数设为 false；
- 模式适配：生产环境建议使用紧凑模式（减少数据传输 / 存储体积），调试环境建议使用格式化模式（便于人工阅读排查问题）；
- 文件权限：文件级操作需确保程序对目标路径具备对应的读写权限，否则会返回文件操作失败错误；
- 异常捕获：接口内部已捕获 std::exception 及未知异常（...），避免因 JSON 解析 / 序列化异常导致程序崩溃，异常信息会存入 err_msg 字段。