文档中心
cjson库
更新时间：2025/07/05
在Gitcode上查看源码

Lua本身没有JSON相关的库，因此openUBMC Lua SDK中引入了JSON相关功能库，用于处理JSON数据，根据业务需求提供简单易用的Lua API来解析生成、操作和序列化JSON数据。

NOTE

由于Lua中字典表是无序的，JSON库提供了专门的有序表操作API，支持Lua中有序获取表中的数据。

两套 API 不支持混用。

不支持顺序保持的 API ​

接口功能描述
encode(table)将 Lua 的 table 转换成JSON字符串
decode(string)将JSON字符串转换成 Lua 的 table
encode_empty_table_as_object(boolean)encode 时，默认将空 table 当成对象而不是空数组
dump(table, string)将 lua 数据无格式 dump 到文件接口
dump_pretty(table, string)将 lua 数据 dump 到文件接口，输出内容包括空格、换行

支持顺序保持的 API ​

接口功能描述
json_object_ordered_encode(json_object)将JSON对象转换成JSON字符串
json_object_ordered_encode_pretty(json_object)将JSON对象转换成美化后的JSON字符串
json_object_ordered_decode(string)将JSON字符串转换成JSON对象
json_object_get_keys(json_object)获取JSON对象有序的 keys
json_object_is_equal(json_object, json_object)判断两个JSON对象是否相同
json_object_to_table(json_object)将类型为 object 或 array 的JSON对象转为lua中的table，不保证顺序
json_object_from_table(table)将 lua 中的 table 转换成 json_object，不保证顺序
json_object_copy(json_object)对JSON对象进行深拷贝，返回新的JSON对象
json_object_is_object(json_object)判断JSON对象的类型是否为 object 对象
json_object_is_array(json_object)判断 json_array 的类型是否为 array 对象
json_object_new_object()初始化一个 json_object，类型为 object 对象
json_object_new_array()初始化一个 json_object，类型为 array 对象
json_object_dump(json_object, string)提供 Json 对象无格式 dump 到文件接口
json_object_dump_pretty(json_object, string)提供 Json 对象 dump 到文件接口，输出内容包括空格、换行
to_raw(json_object, boolean)将 full userdata类型的JSON对象转为 lightuserdata类型，变更持有类型以减少 Lua 表的大小
new_from_raw(userdata)和 to_raw 配套使用，将 to_raw 返回的 lightuserdata 类型转为JSON对象对象

加载方式 ​

lua
local json = require 'cjson'

接口详细说明 ​

cjson.encode ​

描述

  • 将 Lua 的 table 转换成JSON字符串

参数

参数类型描述是否必选
tabletable待转换的 table必选

返回

  • 转换后的JSON字符串

异常

  • 若转换失败，则抛异常

示例

lua
local data = json.encode({ConfigData = {NTP = {Node = {Value = 'IPv6', Import = true}}}})

cjson.decode ​

描述

  • 将JSON字符串转换成 Lua 的 table

参数

参数类型描述是否必选
stringstring待转换的 string必选

返回

  • 转换后的 table

异常

  • 若转换失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.decode(json_s)

cjson.encode_empty_table_as_object ​

描述

  • encode 时，默认将空 table 当成对象而不是空数组

参数

参数类型描述是否必选
booleanboolean是否开启必选

返回

  • 转换后的JSON字符串

异常

  • 无

示例

lua
local data1 = json.encode({})
lu.assertEquals(data1, '[]')
json.encode_empty_table_as_object(true)
local data2 = json.encode({})
lu.assertEquals(data2, '{}')

cjson.dump ​

描述

  • 将 lua 数据无格式 dump 到文件接口

参数

参数类型描述是否必选
tabletablelua 数据必选
stringstring文件路径必选

返回

  • 若成功写入文件则返回 1，否则抛异常

异常

  • 若打开文件失败，则抛异常
  • 若数据转换失败，则抛异常
  • 若转换后的数据写入文件失败，则抛异常

示例

lua
local dump_file = '/test.json'
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.decode(json_s)
lu.assertEquals(json.dump(obj, dump_file), 1)

cjson.dump_pretty ​

描述

  • 将 lua 数据 dump 到文件接口，输出内容包括空格、换行

参数

参数类型描述是否必选
tabletablelua 数据必选
stringstring文件路径必选

返回

  • 若成功写入文件则返回 1，否则抛异常

异常

  • 若打开文件失败，则抛异常
  • 若数据转换失败，则抛异常
  • 若转换后的数据写入文件失败，则抛异常

示例

lua
local dump_file = '/test.json'
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.decode(json_s)
lu.assertEquals(json.dump_pretty(obj, dump_file), 1)

cjson.json_object_ordered_encode ​

描述

  • 将JSON对象转换成JSON字符串

参数

参数类型描述是否必选
json_objectfull userdata待转换的 json_object必选

返回

  • JSON字符串

异常

  • 若转换失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.json_object_ordered_decode(json_s)
lu.assertEquals(json.json_object_ordered_encode(obj), json_s)

cjson.json_object_ordered_encode_pretty ​

描述

  • 将JSON对象转换成美化后的JSON字符串

参数

参数类型描述是否必选
json_objectfull userdata待转换的 json_object必选

返回

  • JSON字符串

异常

  • 若转换失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.json_object_ordered_decode(json_s)
local pretty_s = json.json_object_ordered_encode_pretty(obj)

cjson.json_object_ordered_decode ​

描述

  • 将JSON字符串转换成JSON对象

参数

参数类型描述是否必选
stringstringJSON 字符串必选

返回

  • JSON对象

异常

  • 若转换失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130}}'
local obj = json.json_object_ordered_decode(json_s)

cjson.json_object_get_keys ​

描述

  • 获取JSON对象有序的键值

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选

返回

  • 键值数组

异常

  • 若获取键值失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130},'..
                '"Thomas":{"height":180, "weight":145},'..
                '"David":{"height":165, "weight":120}}'
local obj = json.json_object_ordered_decode(json_s)
local expected_keys = {'James', 'Thomas', 'David'}
local keys = json.json_object_get_keys(obj)
for i, k in ipairs(keys) do
    lu.assertEquals(k, expected_keys[i])
end

cjson.json_object_is_equal ​

描述

  • 判断两个JSON对象是否相同

参数

参数类型描述是否必选
json_object_1full userdata待匹配json_object 1必选
json_object_2full userdata待匹配json_object 2必选

返回

  • 判断结果，类型为boolean

异常

  • 若获取JSON引用失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130},'..
                '"Thomas":{"height":180, "weight":145},'..
                '"David":{"height":165, "weight":120}}'
local obj1 = json.json_object_ordered_decode(json_s)
local obj2 = json.json_object_copy(obj1)
lu.assertIsTrue(json.json_object_is_equal(obj1, obj2))
obj1.James.height = 170.2
lu.assertIsFalse(json.json_object_is_equal(obj1, obj2))

cjson.json_object_to_table ​

描述

  • 将JSON对象转为Lua中的表对象，不保证顺序

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选

返回

  • 转换得到的Lua表

异常

  • 若获取JSON引用失败，则抛异常
  • 若转换失败，则抛异常

示例

lua
local json_s = '{"David":{"height":165, "weight":120, "friends":["James", "Thomas"]}}'
local obj = json.json_object_ordered_decode(json_s)
local friends = json.json_object_to_table(obj.David.friends)
local expected_friends = {'James', 'David'}
lu.assertEquals(friends, expected_friends)

cjson.json_object_copy ​

描述

  • 对JSON对象进行深拷贝，返回新的JSON对象

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选

返回

  • 深拷贝得到的新的JSON对象

异常

  • 若获取JSON引用失败，则抛异常
  • 若拷贝失败，则抛异常

示例

lua
local json_s = '{"James":{"height":170, "weight":130},'..
                '"Thomas":{"height":180, "weight":145},'..
                '"David":{"height":165, "weight":120}}'
local obj1 = json.json_object_ordered_decode(json_s)
local obj2 = json.json_object_copy(obj1)
lu.assertIsTrue(json.json_object_is_equal(obj1, obj2))
obj1.James.height = 170.2
lu.assertIsFalse(json.json_object_is_equal(obj1, obj2))

lu.assertEquals(json.json_object_copy(obj1.James.weight), obj1.James.weight)

cjson.json_object_is_object ​

描述

  • 判断JSON对象的类型是否为JSON对象

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选

返回

  • 判断结果，类型为boolean

异常

  • 若获取JSON引用失败，则抛异常

示例

lua
local json_s = '{"David":{"height":165, "weight":120, "friends":["James", "Thomas"]}}'
local obj = json.json_object_ordered_decode(json_s)
lu.assertIsTrue(json.json_object_is_object(obj.David))
lu.assertIsFalse(json.json_object_is_object(obj.David.height))

cjson.json_object_is_array ​

描述

  • 判断JSON对象的类型是否为数组类型

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选

返回

  • 判断结果，类型为boolean

异常

  • 若获取JSON引用失败，则抛异常

示例

lua
local json_s = '{"David":{"height":165, "weight":120, "friends":["James", "Thomas"]}}'
local obj = json.json_object_ordered_decode(json_s)
lu.assertIsTrue(json.json_object_is_array(obj.David.friends))

cjson.json_object_new_object ​

描述

  • 初始化一个JSON空对象

参数

  • 无

返回

  • json_object, 类型为JSON对象

异常

  • 若创建失败，则抛异常

示例

lua
local obj = json.json_object_new_object()
lu.assertIsTrue(json.json_object_is_object(obj))

cjson.json_object_new_array ​

描述

  • 初始化一个JSON数组

参数

  • 无

返回

  • json_object, 类型为数组对象

异常

  • 若创建数组对象失败，则抛异常

示例

lua
local obj = json.json_object_new_array()
lu.assertIsTrue(json.json_object_is_array(obj))

cjson.json_object_dump ​

描述

  • 转储JSON对到文件接口，不带格式

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选
stringstring文件路径必选

返回

  • 若成功写入文件则返回 1，否则抛异常

异常

  • 若增加引用计数失败，则抛异常
  • 若打开文件失败，则抛异常
  • 若数据转换失败，则抛异常
  • 若转换后的数据写入文件失败，则抛异常

示例

lua
local json_s = '{"David":{"height":165, "weight":120, "friends":["James", "Thomas"]}}'
local obj = json.json_object_ordered_decode(json_s)
lu.assertErrorMsgContains('dump error: open file / failed', function()
    json.json_object_dump(obj, '/')
end)
lu.assertErrorMsgContains('dump error: check realpath', function()
    json.json_object_dump(obj, dump_path)
end)
lu.assertEquals(json.json_object_dump(obj, dump_file), 1)

cjson.json_object_dump_pretty ​

描述

  • 转储JSON对到文件接口，并格式化

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选
stringstring文件路径必选

返回

  • 若成功写入文件则返回 1，否则抛异常

异常

  • 若增加引用计数失败，则抛异常
  • 若打开文件失败，则抛异常
  • 若数据转换失败，则抛异常
  • 若转换后的数据写入文件失败，则抛异常

示例

lua
local json_s = '{"David":{"height":165, "weight":120, "friends":["James", "Thomas"]}}'
local obj = json.json_object_ordered_decode(json_s)
lu.assertEquals(json.json_object_dump(obj, dump_file), 1)
lu.assertEquals(readfile(dump_file), json_s)
lu.assertEquals(json.json_object_dump_pretty(obj, dump_file), 1)
lu.assertEquals(readfile(dump_file), json.json_object_ordered_encode_pretty(obj))

cjson.to_raw ​

描述

  • 将JSON对象从Lua表转换将lightuserdata类型，即内存完全在C中，Lua虚拟机仅持有指针，且不会执行垃圾回收。

参数

参数类型描述是否必选
json_objectfull userdatajson_object必选
booleanboolean是否需要添加引用计数可选

返回

  • 转换后的lightuserdata指针

异常

  • 若获取JSON引用失败，则抛异常

示例

lua
obj = json.to_raw(obj, true)

cjson.new_from_raw ​

描述

  • 和cjson.to_raw配套使用，将返回的lightuserdata指针转为JSON对象，即内存拷贝至Lua虚拟机中。

参数

参数类型描述是否必选
userdatalightuserdata待转换的 lightuserdata 类型数据可选

返回

  • 转换后的JSON对象

异常

  • 无

示例

lua
obj = json.new_from_raw(obj)

JSON对象操作指导 ​

NOTE

JSON对象默认是完整的Lua对象，所有权在Lua中，由Lua虚拟机来管理内存。

读取 ​

lua
-- 读取json_object的key对应的值，存到variable中
local <variable> = <json_object>.<key>
  • 如果key不存在于json_object中，返回nil；
  • 如果key存在于json_object中，但是值是null，则返回cjson.null。

添加 ​

lua
-- 向variable指向的json_object中添加一个键值对，键为key，值为value
<variable>.<key> = <value>
-- 值可以是json_object
<variable>.<key> = cjson.json_object_new_object()

修改 ​

lua
-- 修改variable指向的json_object中的key值为value
<variable>.<key> = <value>
-- 修改variable指向的json_object中的key值为null
<variable>.<key> = cjson.null

删除 ​

lua
-- 修改variable指向的json_object中键为key的键值对
<variable>.<key> = nil

遍历 ​

lua
for k, v in pairs(obj) do
    print(k, v)

获取长度 ​

lua
local len = #<json_object>
上一篇mc.utils_core
下一篇worker_core
版权所有 © 2025 openUBMC 保留一切权利粤A2-20044005号-293
隐私政策|法律声明|关于cookies