Caskara - 数据库引擎

Caskara - 数据库引擎

一个允许进行类似MongoDB数据库管理的API。

图书馆

Caskara:面向 Hytale 模组的数据引擎

Caskara 是专为 Hytale 模组生态系统构建的数据引擎。它结合了 SQLite 的可靠性与 JSON 风格数据结构的灵活性,为模组开发者提供了一种快速且实用的方式来存储和管理持久化数据。

Caskara 不依赖外部服务或复杂的配置,而是在模组本地运行。这使得集成变得简单,同时即使在服务器处理大量游戏事件或玩家数据时也能保持稳定的性能。

BETA 版本: Caskara 目前处于 Beta 阶段。虽然它已经过广泛测试,但仍可能包含未发现的缺陷或不一致之处。请报告你发现的任何问题。

📖 阅读完整 API 文档


📦 架构概览

Caskara 使用独特的 Shell & Core 架构来管理数据。每个数据库文件都是一个“Shell”,而该 shell 内的每种实体类型都是一个“Core”。

流程(简化版)

Plugin Code → Caskara API → Shell Controller
↓
┌───────────────┐
│   Shells      │
│ global.db     │
│ players.db    │
└──────┬────────┘
↓
┌───────────────┐
│    Cores      │
│ Quests        │
│ Factions      │
│ PlayerStats   │
└───────────────┘

Internal:
LRU Cache ↔ JSON Serializer ↔ AES-128 Encryption ↔ SQLite Storage

🏁 新手指南:基础 CRUD

使用 Caskara 管理数据有意设计得十分简单。你无需编写 SQL 或定义 schema。

1. 为你的数据建模

任何带有默认构造函数的 Java 类都可以成为 Caskara 实体。你可以选择性地使用注解来动态配置它:

import com.cookie.caskara.annotations.*;

@CaskaraEntity(shell = "quests") // Store in quests.db instead of global.db
@Index("title")                  // Create an index for faster title lookups
@TTL(minutes = 60)               // Quests expire after 60 minutes by default
public class Quest {
    @Id
    public String questId;       // @Id marks the primary key

    public String title;
    public boolean completed;
}

2. 基础操作

// Save (Create or Update)
Quest q = new Quest("Fire Dragon", false);
Caskara.save(q);

// Load (Read)
Quest loaded = Caskara.load("Fire Dragon", Quest.class);

// List All
List<Quest> allQuests = Caskara.list(Quest.class);

// Delete (Discard)
Caskara.delete("Fire Dragon", Quest.class);

🛡️ 高级功能

ACID 事务

确保多个操作要么全部成功,要么全部失败。非常适合经济转账场景。

Caskara.transaction(tx -> {
    Wallet p1 = tx.load("uuid1", Wallet.class);
    Wallet p2 = tx.load("uuid2", Wallet.class);

    p1.balance -= 100;
    p2.balance += 100;

    tx.save(p1);
    tx.save(p2); // If this throws an exception, p1's balance is ROLLED BACK automatically!
});

钩子与校验

在数据被处理之前或之后自动执行逻辑。

var core = Caskara.core(Player.class);

// Stop bad data from being saved
core.addValidator(p -> p.level > 0);

// Log activity automatically
core.onAfterSave((id, p) -> Logger.info("Player " + p.name + " was saved."));

对象生命周期:TTL 与软删除

// This record will be physically deleted after 30 minutes by a background worker
Caskara.save(tempBuff, Duration.ofMinutes(30));

// Non-destructive delete. The data stays in DB but is ignored by Queries/Loads.
Caskara.softDelete("mod-123", ModData.class);
Caskara.restore("mod-123", ModData.class); // Bring it back!

🔐 安全性:透明加密

使用 AES-128(见下方说明)保护敏感数据(例如 Discord token 或私钥)。Caskara 会在 I/O 期间自动处理加密和解密。

// Call this once during initialization
Caskara.encrypt(SecretConfig.class, "your-super-secret-key");

// From now on, SecretConfig data is stored as encrypted blobs in SQLite
Caskara.save(new SecretConfig("token", "xyz-123"));

// Rotate encryption key seamlessly across all saved data without data loss
Caskara.rotateKey(SecretConfig.class, "your-super-secret-key", "new-stronger-key");

⚙️ 技术细节

JSON 查询引擎

Caskara 使用 SQLite 的 json_extract 来在无固定 schema 的情况下查询数据。当你调用 createIndex() 时,Caskara 会为 JSON 属性生成一个计算 SQL 索引。

Caskara.createIndex(Player.class, "stats.level");

// Caskara runs this internally for O(1) lookups:
// CREATE INDEX idx_player_level ON elements(json_extract(json, '$.stats.level'))

性能指标

Caskara 会追踪一切。访问 Stats 引擎来查看你的模组运行情况:

var stats = Caskara.stats();
System.out.println("Cache Hit Rate: " + stats.getCacheHitRate() * 100 + "%");
System.out.println("Avg Latency: " + stats.getAverageQueryTimeMs() + "ms");

💾 内置自动备份

Caskara 拥有强大的内置 自动备份系统,它使用原生 SQLite 原子备份 API 自动安全地备份你所有的数据库。它每 1 小时在后台静默运行。

  • 在游戏内使用 /caskara backup 触发一次即时全局备份。
  • 使用 /caskara autobackup <hours> 即时更改备份频率。

警告 — 请务必自行备份你的数据库文件! 尽管 Caskara 会安全地备份你的数据库,但你始终应该将 global/ 和 worlds/ 文件夹纳入你自己的操作系统级服务器备份中!硬盘损坏或误删文件夹将同时摧毁你的数据库和 Caskara 自动生成的 .bak 文件。请做好你自己的异地备份!


📊 技术对比

功能 Caskara 原生 SQLite MongoDB
NoSQL 灵活性 ✅(JSON) ❌(僵硬) ✅
ACID 事务 ✅ 内置 ✅ SQL ✅
透明加密 ✅ 一行代码 ❌ 复杂 ✅
内存缓存 ✅(动态 LRU) ❌ ✅
异步写入队列 ✅ 100k+ TPS ❌ 锁竞争严重 ✅
配置开销 零 高 高
自动索引 ✅ ❌ ✅

🛑 规模与限制:何时迁移?

Caskara 被设计为能够处理海量数据,前提是你的模组运行在单个 Hytale 服务器上。得益于其异步预写队列,Caskara 可以轻松吸收每秒 50,000 到 100,000 次异步写入而不会阻塞主游戏线程。然而,你必须了解它的架构限制:

在以下情况下不要使用 Caskara:

  • 你正在构建多服务器网络(BungeeCord/代理风格):SQLite 依赖物理文件锁(.db)。你无法在不同机器上运行的多个物理服务器之间共享单个 Caskara 数据库文件。通过网络驱动器这样做会导致数据损坏。迁移路径:如果你的模组发展为多服务器网络,你必须迁移到 MongoDB 或 MySQL 等集中式数据库。
  • 你需要大量关系型 Join:Caskara 是文档存储(NoSQL)。虽然它支持索引,但如果你的数据模型需要跨 10+ 张表进行复杂 join(例如高度关系型的 Web 应用结构),你应该使用原生 SQL 方案。
  • 你正在存储 BLOB:不要在 Caskara 中存储大型图片、视频或 schematic。对于大型二进制文件,请使用 Hytale 的原生资源系统或标准的平面文件存储。

🔄 遗留数据自动迁移与安全备份

为何做出此变更?

历史上,旧版本的 Caskara 默认使用名为 default.db 的单一数据库。如果多个模组在同一 Hytale 服务器上使用 Caskara 且没有自定义 Shell 配置,它们都会读写同一个文件。这导致了严重的冲突和命名空间冲突。

为解决此问题,版本 2.1.0 通过 Caskara.init("my_mod_id", folder) 引入了命名空间隔离。然而,如果你只是简单地重命名文件,要么会破坏其他模组,要么会丢失用户现有数据。

自动迁移的工作原理(类型提取)

Caskara 通过基于类型的数据提取来干净且安全地解决此问题:

  1. 当你使用唯一命名空间(例如 my_mod_id.db)初始化你的模组时,Caskara 会检测数据库目录中是否仍存在遗留的 default.db。
  2. 安全备份:在触碰任何数据之前,Caskara 会自动将原始遗留数据库文件复制到同一目录下的 default.db.migration.bak。
  3. 精准提取:Caskara 不会移动整个数据库(那样会窃取属于其他模组的数据),而是打开 default.db,仅提取与你的模组所注册实体类匹配的行(通过 type 列),并将它们移入你新的隔离的 my_mod_id.db 文件。
  4. 清理:成功复制后,它会从旧的 default.db 文件中删除那些特定的行。

结果: 你的模组获得其隔离数据库,其他遗留模组仍可从 default.db 读取自己的数据,并且你在磁盘上拥有一个安全备份文件(default.db.migration.bak),以备需要回滚时使用。

注意 — 哪些人会受影响? 此自动迁移仅针对之前保存在默认全局数据库(default.db)中的实体运行。如果你的实体通过 @CaskaraEntity(shell = "my_custom_shell") 配置为使用自定义数据库,它们已经被隔离,不会触发也不会受此迁移影响。

用 ❤️ 为 Hytale 社区打造。