跳到主要内容

LiteDB 数据持久化 API 文档

LiteDB 是一个轻量级的 NoSQL 数据库，专为 EasyBot 插件提供高性能的数据持久化解决方案。每个插件拥有独立的数据库文件（插件ID.ldb），支持 JSON 格式数据存储、事务、索引和查询等功能。

命名空间概述​

declare namespace litedb {
    // 提供完整的键值对存储和数据库管理功能
}

核心概念​

  • 集合 (Collection): 类似于关系数据库中的表，用于组织相关数据
  • 键值对 (Key-Value): 基本存储单元，键为字符串，值可以是任意 JSON 序列化的数据
  • 独立数据库: 每个插件拥有独立的 .ldb 文件，确保数据隔离

基础操作函数​

GetDbPath()​

功能描述: 获取当前插件的数据库文件路径。

语法:

function GetDbPath(): string

参数: 无

返回值: string - 数据库文件的完整路径

使用示例:

const dbPath = litedb.GetDbPath();
logger.info(`数据库文件位置: ${dbPath}`);
// 输出: 数据库文件位置: /path/to/plugins/your-plugin-id.ldb

注意事项:

  • 路径由系统自动生成，基于插件ID
  • 文件会在首次使用时自动创建

Set()​

功能描述: 在指定集合中设置键值对，支持任意 JSON 序列化的数据类型。

语法:

function Set(collection: string, key: string, value: any): boolean

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • value (any): 要存储的值（支持对象、数组、基本类型等）

返回值: boolean - 操作是否成功

使用示例:

// 存储基本类型
litedb.Set("settings", "server_name", "我的服务器");
litedb.Set("settings", "max_players", 100);
litedb.Set("settings", "enabled", true);

// 存储复杂对象
const playerData = {
    name: "Steve",
    level: 25,
    inventory: ["diamond_sword", "iron_armor"],
    stats: { hp: 100, mp: 50 }
};
litedb.Set("players", "steve_uuid", playerData);

// 存储数组
const serverList = ["server1", "server2", "server3"];
litedb.Set("config", "servers", serverList);

注意事项:

  • 如果键已存在，会覆盖原有值
  • 值必须是可 JSON 序列化的数据
  • 集合不存在时会自动创建

Get()​

功能描述: 从指定集合中获取键对应的值。

语法:

function Get(collection: string, key: string): any

参数:

  • collection (string): 集合名称
  • key (string): 键名

返回值: any - 存储的值，如果不存在则返回 null

使用示例:

const serverName = litedb.Get("settings", "server_name");
const playerData = litedb.Get("players", "steve_uuid");

if (playerData) {
    logger.info(`玩家 ${playerData.name} 等级: ${playerData.level}`);
} else {
    logger.info("玩家数据不存在");
}

注意事项:

  • 返回的是原始存储的数据类型
  • 不存在的键返回 null，需要进行空值检查

GetValue()​

功能描述: 获取键值对，如果不存在则返回指定的默认值。

语法:

function GetValue(collection: string, key: string, defaultValue?: any): any

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • defaultValue (any, 可选): 默认值

返回值: any - 存储的值或默认值

使用示例:

const maxPlayers = litedb.GetValue("settings", "max_players", 20);
const welcomeMessage = litedb.GetValue("config", "welcome_msg", "欢迎来到服务器！");

// 复杂默认值
const defaultConfig = { theme: "dark", language: "zh-CN" };
const userConfig = litedb.GetValue("user", "ui_config", defaultConfig);

注意事项:

  • 推荐使用此方法而不是 Get() 来避免空值处理
  • 默认值不会自动存储到数据库中

类型安全的获取函数​

GetString()​

功能描述: 获取字符串类型的值，确保类型安全。

语法:

function GetString(collection: string, key: string, defaultValue?: string): string

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • defaultValue (string, 可选): 默认字符串值

返回值: string - 字符串值

使用示例:

const serverName = litedb.GetString("settings", "server_name", "默认服务器");
const playerName = litedb.GetString("players", "current_player", "未知玩家");

GetNumber()​

功能描述: 获取数字类型的值，确保类型安全。

语法:

function GetNumber(collection: string, key: string, defaultValue?: number): number

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • defaultValue (number, 可选): 默认数字值

返回值: number - 数字值

使用示例:

const maxPlayers = litedb.GetNumber("settings", "max_players", 20);
const playerLevel = litedb.GetNumber("players", "steve_level", 1);
const serverPort = litedb.GetNumber("config", "port", 25565);

GetBoolean()​

功能描述: 获取布尔类型的值，确保类型安全。

语法:

function GetBoolean(collection: string, key: string, defaultValue?: boolean): boolean

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • defaultValue (boolean, 可选): 默认布尔值

返回值: boolean - 布尔值

使用示例:

const isEnabled = litedb.GetBoolean("settings", "plugin_enabled", true);
const debugMode = litedb.GetBoolean("config", "debug", false);
const allowPvp = litedb.GetBoolean("server", "pvp_enabled", true);

GetDateTime()​

功能描述: 获取日期时间类型的值。

语法:

function GetDateTime(collection: string, key: string): Date

参数:

  • collection (string): 集合名称
  • key (string): 键名

返回值: Date - 日期时间对象，如果不存在则返回当前时间

使用示例:

const lastLogin = litedb.GetDateTime("players", "steve_last_login");
const serverStartTime = litedb.GetDateTime("server", "start_time");

logger.info(`上次登录时间: ${lastLogin.toLocaleString()}`);

注意事项:

  • 如果键不存在，返回当前时间而不是 null
  • 存储时会自动序列化为 ISO 字符串格式

数据管理函数​

Delete()​

功能描述: 删除指定的键值对。

语法:

function Delete(collection: string, key: string): boolean

参数:

  • collection (string): 集合名称
  • key (string): 要删除的键名

返回值: boolean - 删除是否成功

使用示例:

// 删除玩家数据
const deleted = litedb.Delete("players", "steve_uuid");
if (deleted) {
    logger.info("玩家数据已删除");
} else {
    logger.info("删除失败或键不存在");
}

// 删除配置项
litedb.Delete("settings", "old_config_key");

Exists()​

功能描述: 检查指定的键是否存在。

语法:

function Exists(collection: string, key: string): boolean

参数:

  • collection (string): 集合名称
  • key (string): 要检查的键名

返回值: boolean - 键是否存在

使用示例:

if (litedb.Exists("players", "steve_uuid")) {
    logger.info("玩家数据存在");
    const playerData = litedb.Get("players", "steve_uuid");
    // 处理玩家数据...
} else {
    logger.info("玩家数据不存在，创建新数据");
    // 创建新玩家数据...
}

GetKeys()​

功能描述: 获取指定集合中的所有键名。

语法:

function GetKeys(collection: string): string[]

参数:

  • collection (string): 集合名称

返回值: string[] - 键名数组

使用示例:

const playerKeys = litedb.GetKeys("players");
logger.info(`共有 ${playerKeys.length} 个玩家数据`);

playerKeys.forEach(key => {
    const playerData = litedb.Get("players", key);
    logger.info(`玩家: ${playerData.name}`);
});

Count()​

功能描述: 获取指定集合中键值对的数量。

语法:

function Count(collection: string): number

参数:

  • collection (string): 集合名称

返回值: number - 键值对数量

使用示例:

const playerCount = litedb.Count("players");
const settingsCount = litedb.Count("settings");

logger.info(`玩家数据: ${playerCount} 条`);
logger.info(`设置项: ${settingsCount} 条`);

Clear()​

功能描述: 清空指定集合中的所有数据。

语法:

function Clear(collection: string): boolean

参数:

  • collection (string): 要清空的集合名称

返回值: boolean - 操作是否成功

使用示例:

// 清空临时数据
const cleared = litedb.Clear("temp_data");
if (cleared) {
    logger.info("临时数据已清空");
}

// 重置玩家数据（谨慎使用）
if (confirm("确定要清空所有玩家数据吗？")) {
    litedb.Clear("players");
}

注意事项:

  • 此操作不可逆，请谨慎使用
  • 集合本身不会被删除，只是清空内容

高级操作函数​

Increment()​

功能描述: 对数字类型的值进行原子递增操作。

语法:

function Increment(collection: string, key: string, increment?: number): number

参数:

  • collection (string): 集合名称
  • key (string): 键名
  • increment (number, 可选): 增量，默认为 1

返回值: number - 递增后的值

使用示例:

// 增加玩家经验值
const newExp = litedb.Increment("players", "steve_exp", 100);
logger.info(`玩家新经验值: ${newExp}`);

// 增加访问计数
const visitCount = litedb.Increment("stats", "page_visits");
logger.info(`页面访问次数: ${visitCount}`);

// 减少库存（负增量）
const remaining = litedb.Increment("inventory", "diamond_count", -1);
logger.info(`剩余钻石: ${remaining}`);

注意事项:

  • 如果键不存在，会从 0 开始计算
  • 支持负数增量实现递减
  • 操作是原子性的，适用于计数器场景

集合管理函数​

GetCollections()​

功能描述: 获取数据库中所有集合的名称。

语法:

function GetCollections(): string[]

参数: 无

返回值: string[] - 集合名称数组

使用示例:

const collections = litedb.GetCollections();
logger.info("数据库中的集合:");
collections.forEach(name => {
    const count = litedb.Count(name);
    logger.info(`- ${name}: ${count} 条记录`);
});

DropCollection()​

功能描述: 删除指定的集合及其所有数据。

语法:

function DropCollection(collection: string): boolean

参数:

  • collection (string): 要删除的集合名称

返回值: boolean - 操作是否成功

使用示例:

// 删除临时集合
const dropped = litedb.DropCollection("temp_cache");
if (dropped) {
    logger.info("临时缓存集合已删除");
}

注意事项:

  • 此操作会永久删除集合及其所有数据
  • 删除不存在的集合会返回 false

RenameCollection()​

功能描述: 重命名集合。

语法:

function RenameCollection(oldName: string, newName: string): boolean

参数:

  • oldName (string): 原集合名称
  • newName (string): 新集合名称

返回值: boolean - 操作是否成功

使用示例:

// 重命名集合
const renamed = litedb.RenameCollection("old_players", "players");
if (renamed) {
    logger.info("集合重命名成功");
}

注意事项:

  • 新名称不能与现有集合冲突
  • 原集合必须存在

数据库维护函数​

Backup()​

功能描述: 备份数据库到指定路径。

语法:

function Backup(backupPath: string): boolean

参数:

  • backupPath (string): 备份文件的完整路径

返回值: boolean - 备份是否成功

使用示例:

const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const backupPath = `./backups/plugin-backup-${timestamp}.ldb`;

const success = litedb.Backup(backupPath);
if (success) {
    logger.info(`数据库已备份到: ${backupPath}`);
} else {
    logger.error("备份失败");
}

注意事项:

  • 确保备份路径的目录存在
  • 建议定期进行数据备份

Shrink()​

功能描述: 压缩数据库文件，回收已删除数据占用的空间。

语法:

function Shrink(): boolean

参数: 无

返回值: boolean - 压缩是否成功

使用示例:

const beforeSize = litedb.GetFileSize();
const shrunk = litedb.Shrink();

if (shrunk) {
    const afterSize = litedb.GetFileSize();
    const saved = beforeSize - afterSize;
    logger.info(`数据库压缩完成，节省空间: ${saved} 字节`);
}

注意事项:

  • 在大量删除操作后建议执行压缩
  • 压缩过程中数据库可能暂时不可用

GetFileSize()​

功能描述: 获取数据库文件的大小（以字节为单位）。

语法:

function GetFileSize(): number

参数: 无

返回值: number - 文件大小（字节）

使用示例:

const sizeBytes = litedb.GetFileSize();
const sizeMB = (sizeBytes / 1024 / 1024).toFixed(2);
logger.info(`数据库文件大小: ${sizeMB} MB`);

// 监控数据库大小
if (sizeBytes > 100 * 1024 * 1024) { // 100MB
    console.warn("数据库文件过大，建议清理或压缩");
}

数据导入导出函数​

ExportToJson()​

功能描述: 将指定集合的所有数据导出为 JSON 字符串。

语法:

function ExportToJson(collection: string): string

参数:

  • collection (string): 要导出的集合名称

返回值: string - JSON 格式的数据字符串

使用示例:

// 导出玩家数据
const playersJson = litedb.ExportToJson("players");
logger.info("玩家数据JSON:", playersJson);

// 保存到文件
const fs = require('fs');
fs.writeFileSync('./exports/players.json', playersJson);

ImportFromJson()​

功能描述: 从 JSON 字符串导入数据到指定集合。

语法:

function ImportFromJson(collection: string, json: string): number

参数:

  • collection (string): 目标集合名称
  • json (string): JSON 格式的数据字符串

返回值: number - 成功导入的键值对数量

使用示例:

// 从文件导入数据
const fs = require('fs');
const jsonData = fs.readFileSync('./imports/players.json', 'utf8');

const imported = litedb.ImportFromJson("players", jsonData);
logger.info(`成功导入 ${imported} 条玩家数据`);

// 从API导入数据
const apiData = JSON.stringify({
    "player1": { name: "Steve", level: 10 },
    "player2": { name: "Alex", level: 15 }
});
litedb.ImportFromJson("new_players", apiData);

注意事项:

  • JSON 格式必须是键值对对象
  • 导入会覆盖现有的同名键

查询和批量操作函数​

Query()​

功能描述: 使用 JSONPath 查询语法查找满足条件的键值对。

语法:

function Query(collection: string, query: string): string[]

参数:

  • collection (string): 要查询的集合名称
  • query (string): JSONPath 查询表达式

返回值: string[] - 匹配的键名数组

使用示例:

// 查找等级大于10的玩家
const highLevelPlayers = litedb.Query("players", "$.value.level > 10");
logger.info("高等级玩家:", highLevelPlayers);

// 查找特定物品的玩家
const diamondOwners = litedb.Query("players", "$.value.inventory[*] == 'diamond'");

// 查找在线玩家
const onlinePlayers = litedb.Query("players", "$.value.online == true");

// 复杂查询：查找等级在10-20之间的玩家
const midLevelPlayers = litedb.Query("players", "$.value.level >= 10 && $.value.level <= 20");

注意事项:

  • 查询语法基于 JSONPath 标准
  • $.value 表示存储的值对象
  • 支持比较运算符：>, <, >=, <=, ==, !=
  • 支持逻辑运算符：&&, ||

BatchSet()​

功能描述: 批量设置多个键值对，提高大量数据写入的性能。

语法:

function BatchSet(collection: string, data: Record<string, any>): number

参数:

  • collection (string): 目标集合名称
  • data (Record<string, any>): 键值对字典

返回值: number - 成功设置的键值对数量

使用示例:

// 批量设置玩家数据
const playersData = {
    "steve_uuid": { name: "Steve", level: 25, online: true },
    "alex_uuid": { name: "Alex", level: 30, online: false },
    "bob_uuid": { name: "Bob", level: 15, online: true }
};

const setCount = litedb.BatchSet("players", playersData);
logger.info(`批量设置了 ${setCount} 个玩家数据`);

// 批量设置配置项
const configs = {
    "max_players": 100,
    "server_name": "我的服务器",
    "pvp_enabled": true,
    "difficulty": "normal"
};
litedb.BatchSet("settings", configs);

注意事项:

  • 比单个 Set() 调用性能更好
  • 操作是原子性的，要么全部成功要么全部失败

BatchGet()​

功能描述: 批量获取多个键的值。

语法:

function BatchGet(collection: string, keys: string[]): Record<string, any>

参数:

  • collection (string): 源集合名称
  • keys (string[]): 要获取的键名数组

返回值: Record<string, any> - 键值对字典

使用示例:

// 批量获取玩家数据
const playerKeys = ["steve_uuid", "alex_uuid", "bob_uuid"];
const playersData = litedb.BatchGet("players", playerKeys);

Object.entries(playersData).forEach(([key, data]) => {
    if (data) {
        logger.info(`${key}: ${data.name} (等级 ${data.level})`);
    } else {
        logger.info(`${key}: 数据不存在`);
    }
});

// 批量获取设置项
const settingKeys = ["max_players", "server_name", "pvp_enabled"];
const settings = litedb.BatchGet("settings", settingKeys);

注意事项:

  • 不存在的键在结果中对应 null 值
  • 比多次调用 Get() 性能更好

BatchDelete()​

功能描述: 批量删除多个键值对。

语法:

function BatchDelete(collection: string, keys: string[]): number

参数:

  • collection (string): 目标集合名称
  • keys (string[]): 要删除的键名数组

返回值: number - 成功删除的键值对数量

使用示例:

// 批量删除离线玩家数据
const offlinePlayerKeys = ["old_player1", "old_player2", "old_player3"];
const deletedCount = litedb.BatchDelete("players", offlinePlayerKeys);
logger.info(`删除了 ${deletedCount} 个离线玩家数据`);

// 清理临时数据
const tempKeys = litedb.GetKeys("temp_data");
if (tempKeys.length > 0) {
    const cleaned = litedb.BatchDelete("temp_data", tempKeys);
    logger.info(`清理了 ${cleaned} 条临时数据`);
}

LiteDB 为 EasyBot 插件提供了强大而灵活的数据持久化解决方案，通过合理使用这些 API，可以构建高效、可靠的数据管理系统。

Copyright © 2024-2025 易栈