Skip to main content

KeyValue：本地配置持久化

KeyValue 是 AScript 提供的轻量级数据存储工具。它将数据以 JSON 格式持久化到本地磁盘，并支持字典风格的语法糖。内置线程锁（Lock）机制，确保在多线程环境下读写配置不会产生冲突或数据损坏。

1. 导入模块​

# 导入配置存储类
from ascript.windows.system import KeyValue

2. 核心语法与操作​

📥 保存配置 save()​

将指定的键值对存入配置文件。

代码块：

# 传统方法保存
KeyValue.save("username", "AScript_User")

# 语法糖保存 (推荐)
KeyValue["task_count"] = 10

📤 读取配置 get()​

从配置文件中检索数据。

代码块：

# 传统方法读取 (支持默认值)
val = KeyValue.get("username", "Guest")

# 语法糖读取
val = KeyValue["task_count"]

❌ 删除配置 remove()​

从存储中移除特定的键。

代码块：

# 传统方法删除
KeyValue.remove("temp_token")

# 语法糖删除
del KeyValue["temp_token"]

3. 存储机制详解​

📂 文件定位​

KeyValue 会自动寻找最合适的存储位置：

  1. 优先： 当前脚本运行的根目录下的 config.json。
  2. 回退： 若根目录无写入权限（如在 C 盘系统目录），则自动切换至用户家目录下的 .app_data/config.json。

🔒 线程安全​

该类使用了 Python 的 threading.Lock 装饰写入过程。这意味着即使你的脚本中开启了多个子线程同时执行 save 操作，数据也会排队写入，避免了文件被同时改写导致的 JSONDecodeError。

💡 案例演示​

from ascript.windows.system import KeyValue

# 1. 存储复杂对象（支持 列表、字典 等 JSON 标准类型）
KeyValue["settings"] = {
    "speed": 0.5,
    "retry_times": 3,
    "modes": ["fast", "safe"]
}

# 2. 实战：记录脚本运行次数
run_times = KeyValue.get("run_times", 0)
run_times += 1
KeyValue["run_times"] = run_times

print(f"脚本已累计运行 {run_times} 次")

# 3. 检查某个配置是否存在
if KeyValue["settings"]:
    print(f"当前速度设置为: {KeyValue['settings']['speed']}")

4. 技术规范​

  • 存储格式：标准 UTF-8 编码的 JSON。
  • 并发处理：阻塞式线程锁。
  • 默认路径：当前工作目录 (CWD)。
性能建议

由于 KeyValue 每次执行 save 都会触发物理磁盘写入（_commit），因此在处理极高频率（如每秒数百次）的数据更新时，建议先在内存变量中处理，最后再统一保存。