json

字符串 token

json_escape 是不依赖 DOM、Buffer 和完整 Writer 的底层能力。xrtJsonQuoteWrite 严格校验 UTF-8，并把包含首尾双引号的 JSON 字符串 token 分段写入同步回调。可独立选择斜杠、HTML 字节和非 ASCII 转义；失败时返回 xrt.json 错误及 UTF-8 字节位置。

完整 JSON/XLON Writer 与 Logger JSONL 共用这一实现，不再分别维护字符串转义规则。

json 提供严格 JSON 校验、事件访问、xvalue DOM 转换、增量写出和文件读写。程序内部长期持有的数据继续使用 xvalue；JSON 是文件、HTTP 和其他外部边界上的标准交换格式。

裁剪与依赖

只需要验证或访问事件时选择 XRT_MODULE_JSON_READ，只需要生成响应正文时选择 XRT_MODULE_JSON_WRITE。完整模块不会成为 HTTP 协议层的强制依赖；HTTP 调用方可以直接发送已有 JSON 字节，也可以按需使用这里的构建器。

稳定契约

• 默认只接受 RFC 8259 JSON。注释和尾随逗号必须逐项显式开启。
• 所有文本都使用显式长度，可包含末尾无零字节的输入；JSON 字符串值也可包含解码后的 U+0000。
• 文本必须是合法 UTF-8，\uXXXX 使用 UTF-16 代理对规则转换为 UTF-8。
• xrtJsonParse("null") 返回 xrtValueNull()；失败返回 C NULL，两者没有歧义。
• 整数字面量优先保存为 int64，非负且超过 INT64_MAX 时保存为 uint64。超出 uint64 或低于 int64 范围默认失败，也可显式按 double 有损接收。
• 读取和写出均有深度、字节与项目预算；默认预算有限，不信任输入不会无限消耗资源。
• xrtJsonValid 对合法输入不分配动态内存。xrtJsonVisit 不构造 DOM，但含转义字符串会使用可复用的临时缓冲。
• 事件中的名称、字符串和数字视图只借用到回调返回，调用方保存时必须复制。
• sink 回调必须在返回前消费字节。事件和 sink 回调新设置的错误会原样传播；未设置错误的失败会由 JSON 层补充稳定错误。
• 增量写入器不可重入。任一写入失败后进入失败终态，只能释放。
• 文件写出先完整序列化，再原子替换目标；序列化失败不会损坏已有文件。
• 模块不带隐式锁。不同解析器或写入器可并行使用，同一写入器需要由调用方串行访问。

默认预算

这些值是默认上限，不是格式能力上限。服务端应按接口实际需要进一步收紧。

读取配置

配置必须先由 Init 初始化。Reserved 必须保持零。重复键默认拒绝；KEEP 保留首值并完整校验后续值，REPLACE 保留末值。兼容标志只放宽指定语法，不开启单引号、十六进制、NaN 或其他非标准字面量。

DOM 读取

Parse 使用默认严格配置。Read 用于重复键策略、兼容语法和资源预算。返回的 xvalue 由调用方使用 xrtValueRelease 释放；单例 null 同样允许释放。

标准 JSON 类型映射为 XVALUE_NULL、XVALUE_BOOL、XVALUE_INT、XVALUE_UINT、XVALUE_FLOAT、XVALUE_STRING、XVALUE_ARRAY 和 XVALUE_OBJECT。JSON 不表达 bytes、time、set、int-map、handle 或自定义类型。

事件访问

事件结构提供 token 起点、父容器定位和解析值：

对象成员通过 HasName 和已解码 Name 定位，数组成员通过 Index 定位。Raw 只在有符号整数、无符号整数和浮点事件中保存原始数字 token。容器开始和结束分别产生事件，根深度为零。

STOP 是正常提前完成，返回 XJSON_VISIT_STOPPED，不会伪装为错误。FAIL 应先设置业务错误；未设置时 JSON 层建立 XJSON_ERROR_STATE。

写出配置

ESCAPE_HTML 转义 <、>、&，适合嵌入 HTML 的受控场景；它不能替代完整的 HTML 上下文转义。ESCAPE_NON_ASCII 使用 \uXXXX，补充平面字符输出代理对。CONTAINER_COMPAT 把 set 写成数组、int-map 写成字符串键对象，因此属于显式有损兼容。Set 按 Value 的首次插入顺序稳定写出，IntMap 按整数键升序稳定写出；这些顺序只保证编码结果可重复，不赋予集合顺序语义，也不改变 JSON 对象成员无序的协议语义。

非有限浮点默认失败，也可写成 null 或字符串。非 JSON xvalue 默认失败，也可写成 null；SKIP 只在遍历 DOM 对象成员或序列项时跳过值，根值和直接写入的单值不能跳过。

Indent 范围为 0 到 16，只在 PRETTY 时生效。配置必须由 Init 初始化，Reserved 必须保持零。

DOM 写出

Stringify 是常用入口，返回零结尾文本并通过 pSize 返回不含末尾零的字节数，结果由 xrtFree 释放。失败不修改 pSize。

Write 直接把若干字节块同步提交给 sink，不保留完整结果，适合 HTTP 正文、文件抽象或哈希管线。此前已经提交的块无法撤回，因此 sink 模式只保证内部状态正确，不提供事务性输出。

增量写入器

内存写入器保存结果；sink 写入器边生成边提交。两者共享以下状态化操作：

对象中必须按 Name -> Value 交替写入；数组中直接写值。End 结束最近容器。一个写入器只接受一个根值，所有容器结束后调用 Finish 封闭结果。Value 可以在任意值位置写入现有 xvalue 子树，并检测循环引用。

Take 只适用于已经 Finish 的内存写入器，只能成功一次，返回值由 xrtFree 释放。Free 释放写入器及尚未移交的结果。

文件

ReadFile 在读取阶段执行 MaxInputBytes，再按同一配置解析。文件打开、读取、临时文件或替换失败会建立 XJSON_ERROR_IO，底层文件错误保留在原因链中。

示例

解析、读取字段并重新输出：

不构造 DOM，直接生成固定形状的 HTTP JSON 正文：

完整可运行示例位于 examples/data/json/main.c。

JSON 与 XLON

JSON 保持标准、严格和可互操作。需要无损保存 bytes、time、set、int-map 等 XRT 扩展值时使用 XLON；不要通过非标准 JSON 字面量偷偷扩展 JSON 语义。两者共享底层文本、安全预算和错误设计，但保持独立裁剪入口与格式契约。