JSON 参考
此页面暂无所选语言的译文,当前显示同版本的英文文档。
std.json 提供 JSON 编码与解码。通用同步 json.encode 对值进行只读编码,json.decode 将 JSON 文本解析为独立持有内容的动态值;两者返回 Result。stringify、parse 和 try_parse 作为兼容名称保留。这些接口在 0.0.20 中继续提供。当前仍使用旧 JSON 默认实现,不使用 yyjson。
导入与接口
“导入与接口”章节import json from "std.json"| 接口 | 返回 | 含义 |
|---|---|---|
json.encode(&value:any) |
str! |
只读编码,返回新的紧凑 JSON 文本 |
json.decode(text:str) |
KuValue! |
严格解析,返回独立持有内容的动态值 |
json.stringify(&value:any) |
str! |
encode 的兼容名称 |
json.parse(text:str) |
KuValue! |
decode 的兼容名称 |
json.try_parse(text:str) |
KuValue! |
decode 的兼容名称 |
! 表示返回 Result。用 ? 传播错误,或用 try/catch 处理;通用同步编码接口不消费或修改输入;下文 native Task 字面量子集有单独的所有权限制。
编码与读取
“编码与读取”章节以下是完整基础示例;更多情况见examples/json.ku。
import json from "std.json"
fn main(): null! { value = { name: "Ku", count: 7 } text = json.encode(value)? println(text)
decoded = json.decode(text)? println(decoded["name"]?.as_str()?) println(decoded["count"]?.as_int()? + 1) return ok(null)}对象键稳定排序,预期输出为:
{"count":7,"name":"Ku"}Ku8解析返回的 KuValue 不能直接参与整数算术。先调用 .as_int()? 或 .as_str()?;类型不匹配会返回错误。缺少对象键也会返回错误,不自动提供默认值。
读取动态值
“读取动态值”章节| 操作 | 返回 | 失败条件 |
|---|---|---|
value["key"] 后接 ? |
owned 的 KuValue 字段 |
缺键或 receiver 类型不匹配 |
value.as_int() |
int! |
原值不是整数时返回 value/type_mismatch,不把字符串转整数 |
value.as_str() |
str! |
原值不是字符串时返回 value/type_mismatch |
value.take("key") |
KuValue! |
消费对象取出子树;可能缺键或类型不支持 |
缺键没有隐式默认值,数值和字符串也不隐式互转。这些方法与带类型对象字段及 get_or 不同。
数据与边界
“数据与边界”章节支持字符串、布尔、整数、有限浮点、null、嵌套数组、字符串键对象及可表示的 struct。函数、Task、资源句柄、Result、enum 与循环引用不能编码。
| 规则 | 当前实现 |
|---|---|
| JSON 语法 | 严格解析;拒绝注释、尾逗号、额外尾部内容与非法 Unicode |
| 输入 / 输出 | 各最多 1,000,000 字节 |
| 深度预算 | 从根深度 0 计;depth > 32 拒绝,33 层空容器可接受,34 层拒绝 |
| 整数 | signed 64-bit;越界报错,不自动转 float |
| 浮点 | 有限 binary64;不保留原始数字拼写、float 标签或负零符号 |
| Unicode | 支持中文、emoji、转义及内嵌 NUL |
| 重复对象键 | 解析保留最后一个值 |
| 键顺序 | 编码按 UTF-8 字节序稳定排序 |
浮点 1.0 可编码为 1;如果整数形式超出 int64,编码补 .0 使解码仍按浮点处理,例如 1e20 输出 100000000000000000000.0,可再次解码。有限 binary64 不承诺保留原始数字拼写、float 标签或负零符号。
错误
“错误”章节可恢复错误的 domain 是 json,常见 code 为 parse_error、stringify_error、out_of_memory。解析消息中的 byte N 是从 0 开始的 UTF-8 字节位置。非法输入可以在错误与排查页面找到最小处理示例。
后端支持
“后端支持”章节解释器、默认打包 runner 和同步 native C 支持上面的通用接口。native Task 只支持下文编码子集,不支持通用解析/解码;LLVM 不提供此库。默认 runner 的 import 仍依赖原始源码位置。
完整行为见JSON 语法合同。
Native Task 中的标量 JSON 对象
“Native Task 中的标量 JSON 对象”章节保存为 task-json.ku,使用 ku build --backend c --profile release task-json.ku -o task-json 编译:
import json from "std.json"
async fn main(): null! { text = json.encode({message: "中😀", count: 2, ready: true, missing: null})? println(text) return ok(null)}预期输出为 {"count":2,"message":"中😀","missing":null,"ready":true}。
native Task 的 json.encode / json.stringify 只接受一个对象字面量,最多 64 个不同键,值仅限 int、bool、null、str。字段表达式从左到右求值,再按确定顺序输出键。构造字面量时 owned 字符串仍按通常规则 move;后续还要使用时需显式 clone。
动态对象变量、数组、嵌套对象与浮点不在这条降低路径内。重复字面量键在编译时拒绝,与通用 JSON 解析保留最后一个重复键不同。Result 错误仍需 ? 或 try/catch。此子集不替换 JSON 默认实现,也不表示 async 中支持任意 JSON 操作。