fskv - kv数据库,掉电不丢数据

以下为关键点梳理

在软件领域，fskv 通常指的是一个键值对（Key-Value）数据库库，尤其在 LuatOS 系统中应用广泛。以下是关于 fskv 的详细介绍：

含义

fskv 是一个用于存储键值对数据的库，允许开发者以键值对的形式存储和检索数据，并且这些数据会被持久化在 Flash 存储器上，确保设备断电后数据不会丢失。

优势

持久化存储：数据存储在 Flash 上，设备断电后数据依然保留。
功能丰富：提供初始化、设置、获取、删除、清空等丰富的 API 接口。
性能稳定：读写速度恒定，不受脏数据影响。
数据长度限制合理：key 长度最大 63 字节，value 长度最大 4096 字节。

使用场景

fskv 适用于需要在嵌入式设备上进行数据存储和管理的场景，比如物联网设备中的配置信息存储、传感器数据记录等。

基本用法

初始化：在使用 fskv 库之前，需要先调用 fskv.init() 函数进行初始化(每次开机都需要执行一次fskv.init(),只需要执行一次，但重复执行也不会破坏已有数据。)
设置数据：使用 fskv.set(key, value) 函数设置键值对数据。
获取数据：通过 fskv.get(key) 函数根据键获取对应的数据。
删除数据：调用 fskv.del(key) 函数根据键删除数据。
清空数据库：使用 fskv.clear() 函数清空整个键值对数据库。

注意事项

key 和 value 的数据类型有一定的限制，key 必须是字符串类型，value 可以是字符串、数值、table、布尔值等，但不可以是 nil、function、userdata、task 等。
在设置 table 内的键值对数据时，需要注意如果 key 不存在或者原本的值不是 table 类型，将会完全覆盖。

以下为详细说明

示例

fskv.init()
fskv.set("wendal", 1234)
log.info("fskv", "wendal", fskv.get("wendal"))

fskv.init()

初始化kv数据库

参数

无

返回值

返回值类型	解释
boolean	成功返回true,否则返回false

例子

if fskv.init() then
    log.info("fskv", "kv数据库初始化成功")
end

fskv.set(key, value)

设置一对kv数据

参数

传入值类型	解释
string	key的名称,必填,不能空字符串
string	用户数据,必填,不能nil, 支持字符串/数值/table/布尔值, 数据长度最大4095字节

返回值

返回值类型	解释
boolean	成功返回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.sett(key, skey, value)

设置table内的键值对数据

参数

传入值类型	解释
string	key的名称,必填,不能空字符串
string	table的key名称, 必填, 不能是空字符串
string	用户数据,必填,支持字符串/数值/table/布尔值, 数据长度最大4095字节

返回值

返回值类型	解释
boolean	成功返回true,否则返回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.get(key, skey)

根据key获取对应的数据

参数

传入值类型	解释
string	key的名称,必填,不能空字符串
string	可选的次级key,仅当原始值为table时有效,相当于 fskv.get(key)[skey]

返回值

返回值类型	解释
any	存在则返回数据,否则返回nil

例子

if fskv.init() then
    log.info("fskv", fskv.get("wendal"))
end

-- 若需要"默认值", 对应非bool布尔值, 可以这样写
local v = fskv.get("wendal") or "123"

fskv.del(key)

根据key删除数据

参数

传入值类型	解释
string	key的名称,必填,不能空字符串

返回值

返回值类型	解释
bool	成功返回true,否则返回false

例子

log.info("fskv", fskv.del("wendal"))

fskv.clear()

清空整个kv数据库

参数

无

返回值

返回值类型	解释
bool	成功返回true,否则返回false

例子

-- 清空
fskv.clear()

fskv.iter()

kv数据库迭代器

参数

无

返回值

返回值类型	解释
userdata	成功返回迭代器指针,否则返回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.next(iter)

kv迭代器获取下一个key

参数

传入值类型	解释
userdata	fskv.iter()返回的指针

返回值

返回值类型	解释
string	成功返回字符串key值, 否则返回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.status()

获取kv数据库状态

参数

无

返回值

返回值类型	解释
int	已使用的空间,单位字节
int	总可用空间, 单位字节
int	总kv键值对数量, 单位个

例子

local used, total,kv_count = fskv.status()
log.info("fskv", "kv", used,total,kv_count)