08 JSON数据处理

作者：沈园园

一、JSON 介绍

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，易于人类阅读和编写，同时也易于机器解析和生成。它基于 JavaScript 编程语言的一个子集，但独立于语言，广泛用于不同编程环境中。

1.1 JSON 的基本结构

1.1.1 对象

由花括号 {} 包围，包含键值对。键是字符串，值可以是字符串、数字、布尔值、数组、对象或 null。需要注意的是JSON对象是无序的，即通过json.encode序列化成json字符串之后，里面的顺序内容是无序的，标准规定键值对的顺序无意义，JSON设计初衷是数据交换格式，顺序无关性简化了跨平台解析

{
"name": "Alice",
"age": 30,
"isStudent": false
}

1.1.2 数组

由方括号 [] 包围，包含一个有序的值列表。值可以是任何类型的数据，包括对象和其他数组。需要注意的是JSON数组是有序的，即通过json.encode序列化成json字符串，内容和序列化之前的顺序一致

[
"apple",
"banana",
"cherry"
]

1.2 JSON 的优点

简洁性：结构简单，易于理解和使用。

可移植性：语言无关，几乎所有的编程语言都支持 JSON 解析和生成。

灵活性：适用于各种数据结构的表示。

1.3 常用场景

Web 应用：用于客户端与服务器之间的数据交换。

配置文件：用于应用程序的配置设置。

数据存储：用于存储简单的数据结构。

综上所述，JSON 因其简单和灵活的特性，已经成为现代编程中数据交换的标准格式之一。

二、演示功能概述

1、main.lua：主程序入口；

2、json_app.lua：json 序列化与反序列化功能模块；

三、准备硬件环境

1、Air780EPM核心板一块

2、TYPE-C USB数据线一根

3、Air780EPM核心板和数据线的硬件接线方式为

Air780EPM核心板通过TYPE-C USB口连接TYPE-C USB 数据线，数据线的另外一端连接电脑的USB口；
核心板正面的 ON/OFF 拨动开关拨到ON一端；

4.1 软件环境

在开始实践本示例之前，先筹备一下软件环境：

1、烧录工具：Luatools 下载调试工具

2、本demo开发测试时使用的固件为LuatOS-SoC_V2028_Air780EPM，本demo对固件版本没有什么特殊要求，所以你如果要测试本demo时，可以直接使用最新版本的内核固件Air780EPM固件，Air780EHM固件；如果发现最新版本的内核固件测试有问题，可以使用我们开发本demo时使用的内核固件版本来对比测试；

3、脚本文件：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EPM/demo/json

4、lib脚本文件：使用Luatools烧录时，勾选添加默认lib 选项，使用默认lib脚本文件

准备好软件环境之后，接下来查看如何烧录项目文件到Air780EPM核心板，将本篇文章中演示使用的项目文件烧录到780EPM核心板中。

4.2 API 介绍

json 库：https://docs.openluat.com/osapi/core/json/

五、程序结构

json/
│── main.lua
│── json_app.lua
│── readme.md

5.1 文件说明

main.lua：主程序入口文件。
json_app.lua：json 序列化与反序列化功能模块。

六、代码详解

6.1 main.lua

主程序文件 main.lua 是整个项目的入口点。它负责初始化系统环境。

6.2 json_app.lua

json 序列化与反序列化功能模块。

6.2.1 将 Lua 对象转为 JSON 字符串

-- 序列化成功示例：
-- 示例一：Lua string 转为 JSON string；
local data = "test"
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("string_string_test1","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("string_string_test1","序列化成功：", json_str)
end

-- 示例二：Lua number 转为 JSON string；
local data = 123456789
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("number_string_test1","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("number_string_test1","序列化成功：", json_str)
end

-- 示例三：Lua boolean 转为 JSON string；
local data = true
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("boolean_string_test1","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("boolean_string_test1","序列化成功：", json_str)
end

-- 示例四：Lua table 转为 JSON string；
local data = {abc = 123, def = "123", ttt = true}
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("table_string_test1","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    -- 由于 Lua 表在遍历时键的顺序是不确定的（尤其是字符串键）
    -- 而 JSON 对象本身也是无序的
    -- 因此序列化后的 JSON 字符串中键的顺序可能与 Lua 源码中的书写顺序不同，属于正常情况
    log.info("table_string_test1","序列化成功：", json_str)
end

-- 示例五：Lua nil 转为 JSON string；
local data = nil
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("nil_string_test1","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    -- 注意：此时返回值是一个空字符串 ""
    log.info("nil_string_test1","序列化成功：", json_str)
end


-- 序列化失败示例：
-- Lua table 中包含 function；
local data = {abc = 123, def = "123", ttt = true, err = function() end}
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("table_string_test2","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("table_string_test2","序列化成功：", json_str)
end


-- 指定浮点数示例：
-- 指定保留三位小数，不足时补零，超出时四舍五入；
local data = {abc = 1234.56789}
local json_str, err_msg = json.encode(data, "3f")
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("table_string_test3","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("table_string_test3","序列化成功：", json_str)
end

6.2.2 将 JSON 字符串转为 Lua 对象

-- 反序列化成功示例：
-- 示例一：JSON string 转为 Lua string
local str = '"test"'
-- local str = "\"test\""
local obj, result, err = json.decode(str)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("string_string_test1","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua string
    log.info("string_string_test1","反序列化成功：", obj)
end

-- 示例二：JSON string 转为 Lua number；
local str = "123456789"
local obj, result, err = json.decode(str)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("string_number_test1","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua number
    log.info("string_number_test1","反序列化成功：", obj)
end

-- 示例三：JSON string 转为 Lua boolean；
local str = "true"
local obj, result, err = json.decode(str)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("string_boolean_test1","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua boolean
    log.info("string_boolean_test1","反序列化成功：", obj)
end

-- 示例四：JSON string 转为 Lua table；
local str = "{\"abc\":1234545}"
local obj, result, err = json.decode(str)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("string_table_test1.2","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua table
    -- 注意：此时 obj 是一个 Lua table
    -- 若直接打印 obj，会输出 table: 01C9A490 类似的内存地址
    log.info("string_table_test1.2","反序列化成功：", obj)
    -- 需要添加具体的字段名称，才能正确输出
    log.info("string_table_test1.2","反序列化成功：", obj.abc)
end


-- 反序列化失败示例：
-- JSON string 不是合法的 JSON 格式；
local str = "{\"def\":}"
local obj, result, err = json.decode(str)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("string_table_test2","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua table
    log.info("string_table_test2","反序列化成功：", obj)
end

6.2.3 empty table（空表）转换为 JSON 时的说明

-- empty table（空表） 转换为 JSON 时的说明：
-- 原生 Lua 中的 table 是数组（sequence）和哈希表（map）的统一数据结构；
-- 空表 {} 在转换为 JSON 时存在歧义：无法确定应输出为空数组 [] 还是空对象 {}；
-- 由于 Lua 中只有包含连续正整数索引（从 1 开始）的表才被视为数组，而空表不满足这一条件；
-- 因此 JSON 库默认将其序列化为 {}（空对象）；
local data = {abc = {}}
local json_str, err_msg = json.encode(data)
if json_str == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("table_string_test3","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("table_string_test3","序列化成功：", json_str)
end

6.2.4 字符串中包含控制字符（如 \r\n）的 JSON 序列化与反序列化说明

-- 字符串中包含控制字符（如 \r\n）的 JSON 序列化与反序列化说明：
-- 在 Lua 中，字符串可以包含任意字符，包括回车（\r）、换行（\n）等控制字符；
-- 当使用 json.encode() 对包含此类字符的字符串进行序列化时；
-- JSON 库会自动将其转义为标准的 JSON 字符串字面量形式（例如 \r 转为 "\r"，\n 转为 "\n"）；
-- 以确保生成的 JSON 符合规范且可安全传输；
-- 反序列化时（json.decode()），这些转义序列会被正确还原为原始的控制字符；
-- 因此解码后的字符串与原始字符串在内容上完全一致（逐字节相等）；
-- 需要注意的是：日志输出函数（如 log.info）在打印包含 \r\n 的字符串时；
-- 会实际执行回车换行操作，导致日志在终端上分行显示；
-- 这可能造成“输出格式混乱”或“多出缩进/空格”的视觉错觉（例如 true 前有一个空格长度）；
-- 但这只是日志显示效果，并非字符串内容本身发生变化；
-- 实际比较（tmp3.str == tmp）结果为 true，证明序列化与反序列化过程是无损且正确的；
local tmp = "ABC\r\nDEF\r\n"
local tmp2, err_msg = json.encode({str=tmp})
if tmp2 == nil then
    -- 序列化失败时, 会返回 nil 值, 并通过 err_msg 参数返回错误信息
    log.info("json","序列化失败：", err_msg)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 序列化成功时, 会返回 JSON 字符串
    log.info("json","序列化成功：", tmp2)
end
local tmp3, result, err = json.decode(tmp2)
if result == false then
    -- 反序列化失败时, 会返回 nil 值, 并通过 err 参数返回错误信息
    log.info("json","反序列化失败：", err)
    -- 执行错误处理逻辑，如使用默认值、重试或中止操作
else
    -- 反序列化成功时, 会返回 Lua table
    -- 注意：此时 tmp3 是一个 Lua table
    -- 直接打印 tmp3 显示的是内存地址，需要添加对应字段
    -- true前存在一个空格长度，这是日志输出格式导致的，与字符串内容本身无实际差异
    log.info("json","反序列化成功：", tmp3.str, tmp3.str == tmp)
end

6.2.5 json.null 的语义与比较行为说明

-- json.null 的语义与比较行为说明：
-- 在标准 JSON 中，null 是一个合法的字面量，表示“空值”或“无值”；
-- 然而，Lua 语言本身没有 null 类型，只有 nil 用于表示未定义或空值；
-- 为在 Lua 中准确表示 JSON 的 null，json 库提供了一个特殊占位符：json.null；
-- json.null 通常是一个轻量级的 userdata 或 table，具体实现依赖库版本；
-- 当使用 json.encode() 序列化包含 json.null 的字段时，该字段会被正确转换为 JSON 中的 null；
-- 反之，json.decode() 在解析 JSON 中的 null 时，会将其还原为 json.null，而非 Lua 的 nil；
-- 这是因为：若将 JSON 的 null 直接转为 nil，会导致 table 中对应键被删除；
-- 从而丢失原始 JSON 的结构信息；
-- 因此，json.decode('{"abc":null}').abc 的结果是 json.null，而不是 nil；
-- 由于 json.null 是一个具体的值（非 nil），它与 nil 比较结果为 false；
-- 只有与 json.null 自身比较时，结果才为 true；
-- 开发者应始终使用 == json.null 来判断某个字段是否为 JSON 的 null；
-- 而不要用 == nil，否则逻辑将出错；
log.info("json.null", json.encode({name=json.null}))
-- 日志输出：{"name":null}
log.info("json.null", json.decode("{\"abc\":null}").abc == json.null)
-- 日志输出：true
log.info("json.null", json.decode("{\"abc\":null}").abc == nil)
-- 日志输出：false

七、运行结果展示

出现类似于下面的日志，就表示运行成功：

[00000001.009] I/user.string_string_test1 序列化成功： "test"
[00000001.009] I/user.number_string_test1 序列化成功： 123456789
[00000001.010] I/user.boolean_string_test1 序列化成功： true
[00000001.010] I/user.table_string_test1 序列化成功： {"abc":123,"ttt":true,"def":"123"}
[00000001.010] I/user.nil_string_test1 序列化成功：
[00000001.011] I/user.table_string_test2 序列化失败： Cannot serialise function: type not supported
[00000001.011] I/user.table_string_test3 序列化成功： {"abc":1234.568}
[00000001.011] I/user.string_string_test1 反序列化成功： test
[00000001.011] I/user.string_number_test1 反序列化成功： 123456789
[00000001.011] I/user.string_boolean_test1 反序列化成功： true
[00000001.011] I/user.string_table_test1.2 反序列化成功： table: 01FE5010
[00000001.011] I/user.string_table_test1.2 反序列化成功： 1234545
[00000001.011] I/user.string_table_test2 反序列化失败： Expected value but found T_OBJ_END at character 8
[00000001.012] I/user.table_string_test3 序列化成功： {"abc":{}}
[00000001.012] I/user.json 序列化成功： {"str":"ABC\r\nDEF\r\n"}
[00000001.012] I/user.json 反序列化成功： ABC
DEF
 true
[00000001.012] I/user.json.null {"name":null}
[00000001.012] I/user.json.null true
[00000001.012] I/user.json.null false

八、总结

通过本文学习，你可以学习到 json 序列化与反序列化功能。