掌握FSKV：从KV数据库基础操作到高级应用

FSKV不仅继承了传统键值数据库的高效性，还在可靠性与扩展性上进行了优化。无论是用于缓存、会话管理还是配置中心，其基础的KV操作都是开发人员必须掌握的技能。本文将从最基础的put/get操作讲起，逐步深入至事务处理、过期策略与并发控制，构建完整的FSKV操作知识体系。

一、概述

fskv 核心库是操作 LuatOS 系统中的键值对（Key-Value）数据库的库，旨在替代旧的 fdb 库，并兼容 fdb 的函数，同时使用 fdb 的 Flash 空间。其作用是在 Flash 存储器中持久化存储键值对数据，允许开发者以键值对的形式存储和检索数据，并且这些数据会被持久化存储在 Flash 存储器上，确保设备断电后数据不会丢失。适用于物联网设备的配置信息、传感器数据等场景应用。

核心特点：

持久化存储：数据写入 Flash，断电后不丢失；

功能丰富：提供 fskv.init()（初始化）、fskv.set(key, value)（存储数据）、fskv.get(key)（读取数据）、fskv.del(key)（删除数据）等 API；

稳定高效：读写速度恒定，不受 “脏数据” 影响，最高 10 万次均衡擦写；

优化数据长度限制：如 value 最大 4096 字节，key 最大 63 字节。

fskv 核心库原理是在模组片上 flash 单独开辟了一个总可用空间是 64K 的小区域，跑了个小文件系统，单独操作，实现类似于微型数据库的功能，只支持操作芯片自身的 flash 文件系统，不支持操作通过 lf 核心库或者 sfud 核心库挂载的文件系统。

简单说，fskv 核心库就是一个 “嵌入式设备里的小数据库”，专门用来安全、稳定地存放配置或业务数据，断电也不会丢,

和其他掉电数据不丢失的存储区域 otp,imei,sn 有一定区别：

fskv,可以在 luatools 烧录程序时进行清除，轻量快速，适合零散配置，频繁读写效率高，比如存储串口波特率、服务器 IP 等用户的应用数据；

otp,一次性写入不可篡改，安全性高，适合固定关键数据,比如存储射频校准数据、密钥等

imei,国际移动设备识别码，每个设备全球唯一，永久只读不可修改，是设备入网的 “身份证”,用于蜂窝模组入网、合规认证等需求

sn,设备序列号，内部唯一，默认只读，可快速关联生产 / 售后信息，方便设备管理,常用于设备售后报修、生产追溯等

注：10 万次均衡擦写是指 Flash 存储的单个单元最多能承受 10 万次 “擦除 - 写入” 循环，再通过均衡擦写技术将数据分散到所有单元，避免个别单元提前损坏，从而延长整体设备寿命，

从原理上来说，依靠均衡擦写技术，设备能持续的稳定使用。

二、核心示例

1、核心示例是指：使用本库文件提供的核心 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

三、常量详解

核心库常量，顾名思义是由 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；

如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；

fskv 核心库，没有常量。

四、函数详解

4.1 fskv.init()
功能

初始化 kv 数据库

注意事项

暂无

参数

无

返回值

local result= fskv.init()

有一个返回值 result

result

示例

4.2 fskv.set(key, value)
功能

设置一对 kv 数据

注意事项

value 参数不能设为 nil、 function、 userdata、task 类型；

参数

key

value

返回值

local result= fskv.set(key, value)

有一个返回值 result

result

示例

4.3 fskv.sett(key, skey, value)
功能

设置 table 内的键值对数据

注意事项

value 参数不能设为 function、 userdata、task 类型；

value 设置为 nil,是删除 skey

参数

key

skey

value

返回值

local result= fskv.sett(key, skey, value)

有一个返回值 result

result

示例

4.4 fskv.get(key, skey)
功能

根据 key 获取对应的数据

注意事项

暂无

参数

key

skey

返回值

不带 skey 参数的写法

local v= fskv.get(key)

有一个返回值 v

v

带 skey 参数的写法

local v= fskv.get(key, skey)

有一个返回值 v

v

示例

4.5 fskv.del(key)
功能

根据 key 删除数据

注意事项

如果是 set()接口设置的 KV 数据，是删除一对 KV 数据;

如果是 sett()接口设置的 table 内的键值对数据,是删除 key 和对应的 table,如需删除 table 内的 skey 和 value,可以使用 sett(key,skey,nil)

参数

key

返回值

local result= fskv.del(key)

有一个返回值 result

result

示例

4.6 fskv.clear()
功能

清空整个 kv 数据库

注意事项

暂无

参数

无

返回值

local result= fskv.clear()

有一个返回值 result

result

示例

4.7 fskv.iter()
功能

kv 数据库迭代器

注意事项

该接口作用是创建一个 “迭代器指针”（可以理解为 “遍历的起始游标”）。

再通过 fskv.next(iter) 配合这个指针，就能逐个获取 KV 数据库中的键（当返回 nil 时，表示遍历完所有键）。

这样你就可以通过 “迭代器 + next 方法” 的组合，遍历整个 KV 数据库的所有键值对（拿到键后，再通过 fskv.get 等方法取对应值），而不需要关心 KV 数据库内部是如何存储的。

禁止一边遍历一边做其他动作，比如一边遍历一边删除，建议是先记录待删除的键，遍历结束后统一删除，确保遍历的完整性和确定性。

参数

无

返回值

local iter = fskv.iter()

有一个返回值 iter

iter

示例

4.8 fskv.next(iter)
功能

根据 kv 迭代器指针获取下一个 key

注意事项

禁止一边遍历一边做其他动作，比如一边遍历一边删除，建议是先记录待删除的键，遍历结束后统一删除，确保遍历的完整性和确定性。

参数

iter

返回值

local k = fskv.next(iter)

有一个返回值 k

k

示例

4.9 fskv.status()

功能

获取 kv 数据库状态

注意事项

暂无

参数

无

返回值

local used, total,kv_count = fskv.status()

有三个返回值 used, total,kv_count

used

total

kv_count

示例

五、关于KV键值对数量

FSKV一共64K，16个块，每块大小4K。

初始化时会分配2个块用于小型数据，所以大型数据最多只能存储14对，每对KV数据占据一个块。

小型数据（Value ≤ 255 字节）

当 Value 长度 ≤ 255 字节 时，所有 KV 对会复用初始分配的 8192 字节空间，极限最多存储812对，此时V值只有1字节。

大型数据（Value ≥ 256 字节）

当 Value 长度 ≥ 256 字节 时，每次写入都会触发新块分配（4096字节），每对KV数据占据一个块，所以大型数据最多存储14对。

参考数据表：

六、模组支持说明

支持 LuatOS 开发的所有模组都支持 fskv 核心库。

今天的内容就分享到这里了~