Jsoncpp

JsonUtils 工具类使用说明一、工具概述本工具基于 Jsoncpp 1.8.0 封装支持 C11 标准提供 JSON 序列化 / 反序列化核心能力内存级Json::Value ↔ JSON 字符串支持紧凑 / 格式化、宽松 / 严格模式文件级Json::Value ↔ 本地 JSON 文件直接读写无需手动处理文件流健壮性完善的参数校验、异常捕获、精细化错误码反馈避免内存泄漏 / 程序崩溃二、前置准备步骤1. 环境依赖编译器需支持 C11 及以上g 5.0/MSVC 2015库依赖已集成 Jsoncpp 1.8.0编译时需链接-ljsoncppLinux/ 引入库文件Windows2. 代码集成将本文件保存为 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::Valueval.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::Valuefile_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所有参数均为公有成员支持直接赋值修改也可通过便捷方法批量设置配置项类型默认值详细作用说明indentationstd::string 设置 JSON 字符串的缩进字符紧凑模式下需设为空字符串格式化模式可设为空格、制表符等line_lengthint0设置 JSON 字符串单行最大长度0 代表无长度限制line_separatorstd::string\n设置 JSON 字符串的换行符Windows 系统可设为 \r\nLinux/Mac 系统使用默认值即可emit_utf8booltrue控制是否输出 UTF-8 原生字符开启后中文不会被转义为 \uXXXX 格式关闭则会转义业务场景建议保持开启numeric_precisionint2设置浮点数序列化后的保留小数位数可根据业务需求自定义如 1、3、0 等drop_null_placeholdersbooltrue控制是否自动删除值为 null 的字段开启后可减少 JSON 字符串体积关闭则保留 null 字段compact_modeboolfalse标记是否启用紧凑模式一般无需直接修改通过便捷方法切换即可便捷方法说明setCompactMode ()一键切换为紧凑模式自动将 indentation 设为 、line_length 设为 0、line_separator 设为setFormatMode (int indent_spaces2)一键切换为格式化模式自动根据传入的缩进空格数设置 indentationline_length 设为 80line_separator 设为 \n2. 反序列化配置JsonUnSerializeConfig所有参数均为公有成员支持直接赋值修改也可通过便捷方法批量设置配置项类型默认值详细作用说明strict_modeboolfalse控制是否启用严格解析模式开启后严格遵循 JSON 官方标准不兼容注释、末尾逗号等非标准格式关闭则为宽松模式兼容单行注释、多行注释、末尾逗号等格式comment_stylestd::stringAll设置宽松模式下支持的注释类型仅在 strict_mode 为 false 时生效可选值为 All支持所有注释、Line仅支持单行注释、None不支持注释allow_trailing_commabooltrue控制是否允许 JSON 字符串末尾存在逗号仅在 strict_mode 为 false 时生效便捷方法说明setRelaxedMode ()一键切换为宽松模式自动将 strict_mode 设为 false、comment_style 设为 All、allow_trailing_comma 设为 truesetStrictMode ()一键切换为严格模式自动将 strict_mode 设为 true、comment_style 设为 None、allow_trailing_comma 设为 false五、错误处理规范所有接口返回 JsonResult 类型该类型包含两个核心公有字段及一个便捷判断方法1. 核心字段字段名类型枚举值 / 说明codeJsonErrorCode 枚举kSuccess0操作成功kInvalidParam1传入参数无效如空的 Json::Value、空的 JSON 字符串、无效的文件路径等kSerializeFailed2序列化操作失败如 Jsoncpp 内部序列化出错kUnSerializeFailed3反序列化操作失败如 JSON 字符串格式错误、注释不兼容等kNullPointer4内部创建 StreamWriter/CharReader 对象时返回空指针一般为 Jsoncpp 库异常kConfigError5配置参数非法一般极少出现除非手动设置了无效的配置值err_msgstd::string错误描述字符串内容为具体的错误原因可直接打印用于问题定位2. 便捷方法isSuccess ()返回 bool 类型当 code 为 kSuccess0时返回 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 字段。