键值对存储(fskv)
一、配置信息存储-键值对存储(fskv)概述
fskv 是 LuatOS 系统中的一个库,用于提供键值对(Key-Value)数据库功能。它允许开发者以键值对的形式存储和检索数据,这些数据会被持久化在 Flash 存储器上,确保在设备断电后数据不会丢失。fskv 库旨在替代旧的 fdb 库,并兼容 fdb 的函数,同时使用 fdb 的 Flash 空间。
- 持久化存储:数据存储在 Flash 上,确保设备断电后数据不会丢失。
- 功能丰富:提供了初始化、设置、获取、删除、清空等丰富的 API 接口。
- 性能稳定:读写速度恒定,不受脏数据影响。
- 数据长度限制: key 长度最大 63 字节,value 长度最大 4096 字节。
二、准备硬件环境
参考:硬件环境清单第二章节内容,准备以及组装好硬件环境。
三、软件环境
“凡事预则立,不预则废。”在详细阐述本功能示例之前,我们需先精心筹备好以下软件环境。
1. Luatools工具;
2. 内核固件文件(底层core固件文件):LuatOS-SoC_V2002_Air780EP;参考项目使用的内核固件;
3. luatos需要的脚本和资源文件
脚本和资源文件点击此处查看与下载
lib脚本文件:使用Luatools烧录时,勾选 添加默认lib 选项,使用默认lib脚本文件;
准备好软件环境之后,接下来查看如何烧录项目文件到Air780EP核心板,将本篇文章中演示使用的项目文件烧录到Air780EP核心板中。
四、配置信息存储-键值对存储(fskv)基本用法
4.1 本教程实现的功能定义:
- fskv 库在 Air780EP-LuatOS 系统中提供了一种高效、灵活且持久的键值对存储解决方案。此次 demo 帮助开发者可以快速的熟悉运用 API 接口进行数据存储和管理。
4.2 文章内容引用
- Air780EP 开发板软硬件资料 : Air780EP 产品手册
- 以上接口函数不做详细介绍,可通过此链接查看具体介绍:fskv - kv 数据库
4.3 API 接口详解
4.3.1 fskv.init()
解说:
此函数用于初始化 fskv 数据库。在调用其他 fskv 函数之前,通常需要先调用此函数进行初始化。初始化成功后,会返回一个布尔值 true,表示数据库已成功初始化;如果初始化失败,则返回 false。
举例:
if fskv.init() then
log.info("fskv", "数据库初始化成功")
else
log.info("fskv", "数据库初始化失败")
end
-- 关于清空fdb库
-- 下载工具是没有提供直接清除fdb数据的途径的, 但有办法解决
-- 写一个main.lua, 执行 fskv.kvdb_init 后 执行 fskv.clear() 即可全清fdb数据.
总结:
fskv.init()是 fskv 库的基础函数,用于确保数据库在使用前处于可用状态。
4.3.2 fskv.set(key, value)
解说:
此函数用于设置一对键值对数据。其中,key 为字符串类型,表示键的名称;value 可以为字符串、数值、table、布尔值等类型,表示与键相关联的值。设置成功后,会返回一个布尔值 true;如果设置失败,则返回 false。
举例:
-- 设置数据, 字符串,数值,table,布尔值,均可
-- 但不可以是nil, function, userdata, task
log.info("fskv", fskv.set("wendal", "goodgoodstudy"))
log.info("fskv", fskv.set("upgrade", true))
log.info("fskv", fskv.set("timer", 1))
log.info("fskv", fskv.set("bigd", {name="wendal",age=123}))
总结:
fskv.set()允许开发者以键值对的形式存储数据,支持多种数据类型,非常灵活。
4.3.3 fskv.sett(key, skey, value)
解说:
此函数用于在 table 内设置键值对数据。其中,key 为字符串类型,表示 table 的名称;skey 也为字符串类型,表示 table 内嵌套的键的名称;value 为与 skey 相关联的值,支持多种数据类型。设置成功后,会返回一个布尔值 true(在某些版本中可能返回 nil 表示成功,具体需参考文档);如果设置失败,则返回 false 或 nil(取决于具体实现)。
举例:
-- 本API在2023.7.26新增,注意与set函数区别
-- 设置数据, 字符串,数值,table,布尔值,均可
-- 但不可以是function, userdata, task
log.info("fskv", fskv.sett("mytable", "wendal", "goodgoodstudy"))
log.info("fskv", fskv.sett("mytable", "upgrade", true))
log.info("fskv", fskv.sett("mytable", "timer", 1))
log.info("fskv", fskv.sett("mytable", "bigd", {name="wendal",age=123}))
-- 下列语句将打印出4个元素的table
log.info("fskv", fskv.get("mytable"), json.encode(fskv.get("mytable")))
-- 注意: 如果key不存在, 或者原本的值不是table类型,将会完全覆盖
-- 例如下列写法,最终获取到的是table,而非第一行的字符串
log.info("fskv", fskv.set("mykv", "123"))
log.info("fskv", fskv.sett("mykv", "age", "123")) -- 保存的将是 {age:"123"}
-- 如果设置的数据填nil, 代表删除对应的key
log.info("fskv", fskv.sett("mykv", "name", "wendal"))
log.info("fskv", fskv.sett("mykv", "name")) -- 相当于删除
--
总结:
fskv.sett()提供了在 table 内嵌套设置键值对的功能,使得数据结构更加复杂和灵活。
4.3.4 fskv.get(key, skey)
解说:
此函数用于根据键获取对应的数据。如果提供了 skey,则获取 table 内嵌套的键值对。成功获取到数据后,会返回该数据;如果数据不存在或获取失败,则返回 nil。
举例:
if fskv.init() then
log.info("fskv", fskv.get("wendal"))
end
-- 若需要"默认值", 对应非bool布尔值, 可以这样写
local v = fskv.get("wendal") or "123"
总结:
fskv.get()允许开发者根据键名获取存储的数据,支持直接获取和嵌套获取两种方式。
4.3.5 fskv.del(key)
解说:
此函数用于根据键删除数据。成功删除后,会返回一个布尔值 true;如果删除失败(如键不存在),则返回 false。
举例:
log.info("fskv", fskv.del("wendal"))-- 删除键值对
总结:
fskv.del()提供了删除指定键值对的功能,有助于管理存储空间和避免数据冗余。
4.3.6 fskv.clear()
解说:
此函数用于清空整个 kv 数据库。成功清空后,会返回一个布尔值 true;如果清空失败(如数据库无法访问),则返回 false。
举例:
fskv.clear() -- 清空整个数据库
总结:
fskv.clear()是一个强大的函数,用于在需要时重置或清空整个数据库。
4.3.7 fskv.iter()
解说:
此函数用于返回 kv 数据库的迭代器指针。成功获取迭代器后,可以使用该迭代器遍历所有键值对。返回值为迭代器指针;如果获取失败,则返回 nil。
举例:
-- 清空
local iter = fskv.iter()
if iter then
while 1 do
local k = fskv.next(iter)
if not k then
break
end
log.info("fskv", k, "value", fskv.kv_get(k))
end
end
总结:
fskv.iter()和 fskv.next()一起使用,可以方便地遍历整个数据库中的所有键值对。
4.3.8 fskv.next(iter)
解说(基于 fskv.iter()的上下文):
此函数用于获取迭代器的下一个键。成功获取后,会返回字符串类型的键名;如果迭代器已遍历完所有键值对或获取失败,则返回 nil。
举例:
-- 清空
local iter = fskv.iter()
if iter then
while 1 do
local k = fskv.next(iter)
if not k then
break
end
log.info("fskv", k, "value", fskv.get(k))
end
end
总结:
fskv.next()是遍历数据库时使用的辅助函数,与 fskv.iter()配合使用可以方便地获取每个键值对的键名。
4.3.9 fskv.status()
解说:
此函数用于获取 kv 数据库的状态信息。返回值为三个整数的元组:已使用的空间(单位字节)、总可用空间(单位字节)以及总 kv 键值对数量。这些信息有助于开发者了解数据库的当前状态和使用情况。
举例:
local used, total,kv_count = fskv.status()
log.info("fskv", "kv", used,total,kv_count)
总结:
fskv.status()提供了数据库状态信息的查询功能,有助于开发者进行数据库管理和优化。
五、配置信息存储-键值对存储(fskv)整体演示
5.1 成果演示与深度解析:视频 + 图文全面展示
5.1.1 成果运行精彩呈现
5.1.2 完整实例深度剖析
-- LuaTools需要PROJECT和VERSION这两个信息
PROJECT = "fskvdemo"
VERSION = "1.0.0"
-- sys库是标配
_G.sys = require("sys")
sys.taskInit(function()
sys.wait(1000) -- 免得日志刷没了, 生产环境不需要
-- 检查一下当前固件是否支持fskv
if not fskv then
while true do
log.info("fskv", "this demo need fskv")
sys.wait(1000)
end
end
-- 初始化kv数据库
fskv.init()
log.info("fskv", "init complete")
-- 先放入一堆值
local bootime = fskv.get("boottime")
if bootime == nil or type(bootime) ~= "number" then
bootime = 0
else
bootime = bootime + 1
end
fskv.set("boottime", bootime)
fskv.set("my_bool", true)
fskv.set("my_int", 123)
fskv.set("my_number", 1.23)
fskv.set("my_str", "luatos")
fskv.set("my_table", {name="wendal",age=18})
fskv.set("my_str_int", "123")
fskv.set("1", "123") -- 单字节key
--fskv.set("my_nil", nil) -- 会提示失败,不支持空值
log.info("fskv", "boottime", type(fskv.get("boottime")), fskv.get("boottime"))
log.info("fskv", "my_bool", type(fskv.get("my_bool")), fskv.get("my_bool"))
log.info("fskv", "my_int", type(fskv.get("my_int")), fskv.get("my_int"))
log.info("fskv", "my_number", type(fskv.get("my_number")), fskv.get("my_number"))
log.info("fskv", "my_str", type(fskv.get("my_str")), fskv.get("my_str"))
log.info("fskv", "my_table", type(fskv.get("my_table")), json.encode(fskv.get("my_table")))
log.info("fskv", "my_str_int", type(fskv.get("my_str_int")), fskv.get("my_str_int"))
log.info("fskv", "1 byte key", type(fskv.get("1")), json.encode(fskv.get("1")))
-- 删除测试
fskv.del("my_bool")
local t = fskv.get("my_bool")
log.info("fskv", "my_bool", type(t), t)
-- 查询kv数据库状态
-- local used, total,kv_count = fskv.stat()
-- log.info("fdb", "kv", used,total,kv_count)
-- fskv.clr()
-- local used, total,kv_count = fskv.stat()
-- log.info("fdb", "kv", used,total,kv_count)
-- 压力测试
-- local start = mcu.ticks()
-- local count = 1000
-- for i=1,count do
-- -- sys.wait(10)
-- -- count = count - 1
-- -- fskv.set("BENT1", "--" .. os.date() .. "--")
-- -- fskv.set("BENT2", "--" .. os.date() .. "--")
-- -- fskv.set("BENT3", "--" .. os.date() .. "--")
-- -- fskv.set("BENT4", "--" .. os.date() .. "--")
-- fskv.get("my_bool")
-- end
-- log.info("fskv", mcu.ticks() - start)
if fskv.sett then
-- 设置数据, 字符串,数值,table,布尔值,均可
-- 但不可以是nil, function, userdata, task
log.info("fskv", fskv.sett("mytable", "wendal", "goodgoodstudy"))
log.info("fskv", fskv.sett("mytable", "upgrade", true))
log.info("fskv", fskv.sett("mytable", "timer", 1))
log.info("fskv", fskv.sett("mytable", "bigd", {name="wendal",age=123}))
-- 下列语句将打印出4个元素的table
log.info("fskv", fskv.get("mytable"), json.encode(fskv.get("mytable")))
-- 注意: 如果key不存在, 或者原本的值不是table类型,将会完全覆盖
-- 例如下列写法,最终获取到的是table,而非第一行的字符串
log.info("fskv", fskv.set("mykv", "123"))
log.info("fskv", fskv.sett("mykv", "age", "123")) -- 保存的将是 {age:"123"}
-- 删除测试
log.info("fskv", fskv.set("mytable", {age=18, name="wendal"}))
log.info("fskv", fskv.sett("mytable", "name", nil))
log.info("fskv", fskv.get("mytable"), json.encode(fskv.get("mytable")))
end
end)
-- 用户代码已结束---------------------------------------------
-- 结尾总是这一句
sys.run()
-- sys.run()之后后面不要加任何语句!!!!!
六、总结
Air780EP-LuatOS 中的 fskv 库提供了一套完整的键值对(Key-Value)存储接口,允许开发者以灵活且持久的方式存储和检索数据。这些接口函数包括初始化数据库(fskv.init()
)、设置键值对(fskv.set()
和 fskv.sett()
)、获取键值对(fskv.get()
)、删除键值对(fskv.del()
)、清空数据库(fskv.clear()
)、遍历数据库(fskv.iter()
和 fskv.next()
)以及查询数据库状态(fskv.status()
)。
这些函数共同构成了一个功能强大的键值对存储系统,支持多种数据类型,包括字符串、数值、布尔值和 table 等。通过使用这些函数,开发者可以方便地管理存储在 Flash 存储器上的数据,实现数据的持久化和高效访问。
七、常见问题
- 数据写入失败:可能是由于 Flash 存储器写入次数超限、存储空间不足或数据库初始化失败等原因导致的。开发者应检查相关错误码或日志信息,以确定具体原因并采取相应的解决措施。
- 数据读取失败:可能是由于键不存在、数据库损坏或读取过程中发生异常等原因导致的。开发者应确保在读取数据前,数据库已正确初始化,并且键名正确无误。
- 性能问题:虽然 fskv 库提供了高效的键值对存储功能,但在处理大量数据时,仍可能出现性能瓶颈。开发者应根据实际应用场景,合理设计数据结构,并优化数据访问策略,以提高系统的整体性能。
- 数据一致性:在多线程或并发环境下,可能会出现数据一致性问题。开发者应确保在访问数据库时,采取适当的同步机制或锁策略,以保证数据的一致性和完整性。
八、扩展
- 复合键与多级索引:在 fskv 库的基础上,可以引入复合键(由多个字段组成的键)和多级索引,以支持更复杂的数据查询和检索操作。这有助于提升数据访问的灵活性和效率。
- 有序集合与排序:通过扩展 fskv 库,可以实现对键值对进行排序的功能,从而支持有序集合的存储和检索。这有助于在需要按特定顺序处理数据时提高性能。
- 数据压缩与去重:为了节省存储空间和提高数据访问速度,可以引入数据压缩算法和去重机制。这些技术可以在数据写入时自动应用,并在读取时自动解压和恢复原始数据。
给读者的话
本篇文章由
永仔
开发;本篇文章描述的内容,如果有错误、细节缺失、细节不清晰或者其他任何问题,总之就是无法解决您遇到的问题;
请登录合宙技术交流论坛,点击文档找错赢奖金-Air780EP-LuatOS-软件指南-基础服务-键值对存储(fskv);
用截图标注+文字描述的方式跟帖回复,记录清楚您发现的问题;
我们会迅速核实并且修改文档;
同时也会为您累计找错积分,您还可能赢取月度找错奖金!