A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - MetaTrader 5程序库

1.概述

MQL5 JSON 库是一个功能强大、特性丰富的库，专门用于在 MQL5 环境中解析、操作和序列化 JSON 数据。它提供了简单直观的文档对象模型 (DOM) API，旨在使 MQL5 中的 JSON 处理体验与 JavaScript 和 Python 等现代编程语言相媲美。

该库能够处理各种任务，从读取简单的 EA 配置到系统间复杂的实时数据交换。其主要功能和特点包括

• --- 解析和创建
• 从字符串或文件加载：可靠地将 JSON 文本解析为可操作的内存对象（JsonParse、JsonFromFile）。
• 从零开始构建：使用简洁的 API（如 JsonNewObject 和 JsonNewArray），以编程方式轻松创建新的 JSON 对象和数组。

• 灵活的解析器 可选择支持 JSON5 的一些非标准功能，如代码注释和尾部逗号，以增强与各种数据源的兼容性。

• --- 操作和访问

• 直观的 DOM 遍历：使用带有键（node["key"]）和索引（node[0]）的直观语法访问数据，就像使用 Python 字典或 JavaScript 对象一样。

• 安全的类型转换 提供一系列具有默认值的方法，如 AsInt(defaultValue) 和 AsString(defaultValue)，让你可以安全地从节点中提取所需类型的数据，而不必担心由于类型不匹配或路径不存在而导致程序崩溃。

• 动态修改：自由添加、更新或删除 JSON 对象中的键值对和数组中的元素（Set , Add , Remove）。

  --- 先进的查询和处理功能

• 强大的查询引擎：内置支持JSON Pointer（RFC 6901，用于直接路径访问）和JSONPath（用于复杂和模糊查询），可从深度嵌套的复杂结构中高效提取一个或多个数据节点，既可批量提取，也可精确提取。

• 低内存流解析：提供 JsonStreamParser，用于处理千兆字节级的巨大 JSON 文件。它以事件流的方式逐个令牌读取文件，无需将整个文件加载到内存中，从而实现了极高的内存效率。

• 实用功能：提供文档克隆（.Clone()）和深度合并（JsonMerge）等高级功能，大大简化了常见的复杂任务，如合并 "默认配置 "和 "用户配置"。

  --- 稳健性和安全性

• 自动内存管理：采用 RAII（资源获取即初始化）设计模式。JsonDocument 负责管理其所有节点的生命周期。开发人员无需手动新增/删除任何 JSON 元素，从根本上消除了内存泄漏的风险。

• 跨文档操作安全：在不同的 JsonDocument 实例之间分配节点时，库会自动执行安全的深度复制（Clone），防止悬挂指针和意外的数据损坏。
• 详细的错误报告：当解析失败时，JsonError 对象会提供详细信息，包括错误行号、列号和上下文，便于快速诊断问题。

2.核心概念与内存管理

[2.1 命名空间--整合项目的关键 [!!]最重要的提示：本库中的所有类（如 JsonDocument、JsonNode）和全局函数（如 JsonParse）都封装在一个名为 MQL5_Json 的命名空间中。

**如何正确使用：** - **在头文件（.mqh）中**：MQL5不 允许在 头文件 的 全局 范围内"使用 命名空间"。**因此，您必须使用完全限定的名称**。这 是多 文件项目中 唯一可靠的方法。错误： `JsonDocument doc;` 正确： `MQL5_Json::JsonDocument doc;` - **主程序文件 (.mq5)**中的 内部函数：为方便起见，您可以在函数内部使用`using namespace MQL5_Json;`，但为 确保示例的 通用性，本手册中的 所有代码都将使用 完全限定名称方法。**如果您遇到"'JsonNode'- 声明无 类型 "的编译错误，** ** 几乎总是因为您忘记在 类型和 函数中 添加"MQL5_Json:: "前缀****。

[!!] 2.2 内存管理模型 JsonDocument拥有 数据；JsonNode 只是一个视图。

[!!] 2.3 MQL5 中的对象传递 MQL5 要求所有作为函数参数传递 的类对象（包括 JsonNode）必须通过引用传递（使用 &）。错误： void myFunction(MQL5_Json::JsonNode node) 正确： void myFunction(MQL5_Json::JsonNode &node)