公开 API
编译依赖
<repositories><repository><id>jiuwu-releases</id><url>https://repo.crypticlib.com/repository/maven-public/</url></repository></repositories>
<dependency><groupId>emaki.jiuwu.craft</groupId><artifactId>emaki-storage-api</artifactId><version>1.0.6</version><scope>provided</scope></dependency>repositories { maven("https://repo.crypticlib.com/repository/maven-public/") }
dependencies { compileOnly("emaki.jiuwu.craft:emaki-storage-api:1.0.6") }仅编译依赖
runtime 已内嵌未 relocate 的 API 类。不要安装、bundle、shade 或 relocate API Jar；重复 ClassLoader 类型会破坏事件与 bridge。
门面
检查 EmakiStorageApi.status().usable()。唯一业务层为非 null 的 operations()；install、uninstall 与 Bridge 只属于 runtime。
全部异步方法
除 openGui 外，当前公开读写方法均带 Async 并返回 CompletableFuture<EmakiResult<...>>：
| 方法 | 语义 |
|---|---|
readSnapshotAsync(UUID) | 读取分离的 StorageSnapshot，未缓存时从文件 lane 加载。 |
depositAsync(UUID,ItemStack,long) | 向仓库增加，不从调用方库存扣物。 |
withdrawAsync(UUID,ItemStack,long) | 从仓库扣减并交付给在线 owner。 |
countOfAsync(UUID,ItemStack) | 返回真实数量，包括合法的 0。 |
countAllAsync(UUID,Collection<ItemStack>) | 一次统计多个模板，返回 Map<ItemStack,Long>。仓库里没有的模板映射为 0L 而不是缺键。对离线玩家可用。 |
applyBatchAsync(UUID,StorageBatchRequest) | 原子批量增减。allOrNothing 在 StorageBatchRequest 内声明，不是独立参数。载荷为 StorageBatchResult。操作数超出 behavior.batch_max_ops 时返回 INVALID_INPUT 与 batch_too_large，不执行任何操作。 |
reserveAsync(UUID,StorageBatchRequest,Duration) | 只挂住请求中的扣减侧，载荷是 ReservationHandle。请求里的存入操作被忽略：预留只锁库存，不预订容量。ttl 非正数被拒绝；预留跨重启存活，载入时超过 ttl 即释放。 |
commitAsync(ReservationHandle) | 提交预留，载荷为 StorageBatchResult。只有 handle 一个参数，没有 UUID。提交会重跑存入侧预检。 |
releaseAsync(ReservationHandle) | 释放预留，载荷为 Unit。只有 handle 一个参数。幂等：未知或已释放的 handle 返回 NOT_FOUND 而不是报错。 |
grantSlotsAsync(UUID,int) | 调整管理型 granted-slot 池。 |
setStackLimitAsync(UUID,long) | 设置玩家默认单槽上限；0 恢复配置继承。 |
setSlotStackLimitAsync(UUID,int,long) | 设置逻辑 entry 上限；0 恢复玩家默认继承。 |
这些 future 可从任意线程提交；runtime 会在文件 lane 或玩家 owner thread 完成实际工作，但 future callback 不保证位于 Bukkit owner thread。触碰玩家、库存或世界前必须重新调度。
openGui(Player) 是唯一同步操作，必须在 viewer/owner 的 entity-owner thread；错误线程返回 WRONG_THREAD，不会替调用方延迟打开。
StorageSnapshot 是不可变分离快照。StorageAmount 含 requested、applied、remaining() 与 complete()；容量不足可返回携带实际 applied 的 Partial。
事件边界
异步 API 在其实际 transaction path 中触发对应同步事件；不要因方法名相似就假定所有底层编辑都有事件。特别是 direct async withdraw 的当前实现路径应以 runtime transaction service 为准，事件页列出确切覆盖。
结果语义
无负载成功使用 EmakiResult<Unit>；可选负载使用 optionalValue()。FailureKind 只有 UNAVAILABLE、NOT_FOUND、INVALID_INPUT、REJECTED、CANCELLED、TARGET_OFFLINE、WRONG_THREAD、INTERNAL_ERROR。普通业务失败由结果表示，不依赖 future 异常。