capri: 为Khepri（BEAM的现代分布式数据库）提供的类型安全、原子性Gleam绑定

# capri · v0.2.0 来源：https://capri.hexdocs.pm/ 为 Khepri 提供类型安全、原子化的 Gleam 绑定。 完整 API 参考请参阅生成的模块文档。本 README 侧重于核心概念和安全模型。 ## 入门 使用 `capri.init/2` 初始化 Khepri 并创建一个 `StoreHandle`。您将使用此句柄来访问和操作您的 Khepri 存储/集群。 ```gleam import capri import gleam/erlang/atom let assert Ok(store) = capri.init(atom.create("my_app"), "./data") ``` ## 仓库（Repositories） 仓库代表了传统领域驱动设计中定义的术语持久化层。 > 此模块不使用 Active Record 模式，因为 Gleam 中不存在对象，因此无法创建“活动的”记录。 ### 用法 使用 `capri.repository/3` 定义一个仓库，然后使用 `capri.bind/3` 为给定的存储打开或创建它： ```gleam import capri import capri/path import capri/types import gleam/dynamic/decode import gleam/option.{Some} let assert Ok(users) = capri.repository( "users", 1, types.Decoder(user_decoder), ) let users_path = path.from_key(types.String("users")) let assert Ok(users_prefix) = capri.bind(store, users_path, users) let user_path = capri.child(users_prefix, types.String("user-123")) let assert Ok(Nil) = capri.put(store, user_path, user) let assert Ok(Some(stored_user)) = capri.get(store, user_path) ``` 绑定操作会验证仓库的标识和版本是否与前缀处存储的元数据匹配。生成的带类型前缀和子路径携带了用于解码和验证记录的仓库能力。 ## 迁移（Migrations） 迁移是原子、版本化且可逆的数据与模式转换。 每个迁移都包含其目标版本的解码器，因此模式会同步更改。每一步必须将仓库版本号恰好增加一。 > 虽然可以创建不安全（不可逆）的迁移，但强烈建议避免这样做。 ```gleam import capri import capri/types let assert Ok(users_v1) = capri.repository( "users", 1, types.Decoder(user_v1_decoder), ) let assert Ok(users_v2) = capri.add_migration( users_v1, 2, types.Decoder(user_v2_decoder), fn(entry) { let types.Entry(key, user_v1) = entry Ok(types.Entry(key, migrate_user_to_v2(user_v1))) }, fn(entry) { let types.Entry(key, user_v2) = entry Ok(types.Entry(key, restore_user_v1(user_v2))) }, ) let assert Ok(Nil) = capri.migrate_to_current(store, users_path, users_v2) ``` ## 投影（Projections） 投影是由 Khepri 在本地 ETS 表中维护的类型化派生视图。它们是临时缓存，而非权威的仓库状态。 ### 集合投影（Set projections） 默认的投影类型。使用 `projection.get/2` 从集合投影中获取单个值： ```gleam import capri/projection import gleam/erlang/atom import gleam/option.{Some} let assert Ok(by_email) = users |> projection.new(fn(user) { user.email }) |> projection.named(atom.create("users_by_email")) let assert Ok(Nil) = projection.register(store, users_prefix, by_email) let assert Ok(Some(user)) = projection.get(by_email, "[email protected]") ``` ### 包投影（Bag projections） 使用 `projection.many/1` 创建允许多个记录共享一个键的包投影。使用 `projection.all/2` 查询值。 ```gleam import capri/projection import gleam/erlang/atom let assert Ok(by_team) = users |> projection.new(fn(user) { user.team_id }) |> projection.many |> projection.named(atom.create("users_by_team")) let assert Ok(Nil) = projection.register(store, users_prefix, by_team) let assert Ok(team_members) = projection.all(by_team, team_id) ``` ## 集群（Clustering） 要加入集群，请使用 `capri.reset_and_join_cluster/2`。 > `capri.reset_and_join_cluster/2` 和 `capri.reset_local_member/1` 会清除本地数据。 ## 命名（Naming） Khepri 的发音与 Capri 相似。Capri 是一种裤子，因此 Capri 是 Khepri 的“裤子”。 ## 版权（Copyright） Capri：为 Khepri 提供类型安全、原子化的 Gleam 绑定。版权所有 (C) 2026 Software Freedom Conservancy 等。 本程序是自由软件：您可以根据自由软件基金会发布的 GNU Affero 通用公共许可证（许可证第 3 版，或（由您选择）任何更高版本）的条款重新分发和/或修改它。 本程序的分发是希望它会有用，但没有任何担保；甚至不保证其适销性或适用于特定目的。有关 GNU Affero 通用公共许可证的更多详细信息，请参阅。 您应该已经收到一份 GNU Affero 通用公共许可证随此程序一起提供。如果没有，请参见 https://www.gnu.org/licenses/。