persistence — 键值存储
插件私有、按 group 与 key 隔离的持久化键值存储。
self.persistence 提供按 group 与 key 隔离的键值存储，可用于保存插件的配置或状态。数据以 JSON 序列化的形式持久化保留。
值是任何可 JSON 序列化的类型（字符串、数字、布尔、列表、字典等）。数据作用域限定为插件本身，以 group + key 为键；不同插件之间的数据相互隔离。
方法
| 方法 | 说明 |
|---|---|
get(group, key, callback=None) | 读取指定键的值 |
set(group, key, value, callback=None) | 写入键值对 |
delete(group, key, callback=None) | 删除指定键 |
list_groups(callback=None) | 列出所有存储组 |
list_keys(group, callback=None) | 列出指定组中的所有键 |
clear(group, callback=None) | 清空指定组的所有键值对 |
get(group, key, callback=None)
读取指定键的值。
self.persistence.get(
"my_plugin", "counter", lambda **cb: print(cb.get("value", 0))
)参数：
group(str) — 存储组名key(str) — 键名
回调数据：{"value": 值}
set(group, key, value, callback=None)
写入键值对。
self.persistence.set("my_plugin", "counter", 42)参数：
group(str) — 存储组名key(str) — 键名value(Any) — 值，支持字符串、数字、布尔、列表、字典等 JSON 可序列化类型
delete(group, key, callback=None)
删除指定键。
self.persistence.delete("my_plugin", "counter")参数：
group(str) — 存储组名key(str) — 键名
list_groups(callback=None)
列出所有存储组。
self.persistence.list_groups(lambda **cb: print(cb.get("groups", [])))回调数据：{"groups": ["group1", "group2"]}
list_keys(group, callback=None)
列出指定组中的所有键。
self.persistence.list_keys(
"my_plugin", lambda **cb: print(cb.get("keys", []))
)参数：
group(str) — 存储组名
回调数据：{"keys": ["key1", "key2"]}
clear(group, callback=None)
清空指定组的所有键值对。
self.persistence.clear("my_plugin")参数：
group(str) — 存储组名
使用示例
下面示例通过 group 与 key 存储并读取一份插件配置。
def on_loaded(**cb):
config = cb.get("value", {})
print("已加载配置:", config)
def save_config(config):
self.persistence.set("my_plugin", "config", config)
def load_config():
self.persistence.get("my_plugin", "config", on_loaded)
# 保存配置
save_config({"theme": "dark", "count": 3})
# 读取配置
load_config()存储隔离
每个插件应使用唯一的 group（建议直接使用插件 ID），确保不同插件的数据互不干扰：
# 推荐：使用插件 ID 作为分组
self.persistence.get("my-plugin-id", "key")
# 避免：使用过于通用的分组
self.persistence.get("shared", "key")在插件被卸载后，其 group 下的数据会被清理，因此不要跨插件共享键值存储。