DominionAPI 开发指南

这份文档解决什么问题

这是一份面向 Paper、Spigot 和 Folia 插件开发者的 DominionAPI 使用指南。它帮助你在不读取 Dominion 数据库、不依赖 Dominion 内部缓存和 NMS 实现的前提下，为 Dominion 开发附属插件或其他集成。

本文档按当前 Dominion/api 模块的公开源码编写，API 构建版本为 4.9.3。发布版本升级后，请同时对照 JavaDoc 检查签名和行为。

DominionAPI 的使用可以分成三层：

查询层：通过 DominionAPI 获取领地、玩家、成员、组和 flag 数据；
操作层：通过 DominionProvider、GroupProvider 和 MemberProvider 等 Provider 修改数据；
联动层：监听 Dominion 事件，响应进入/离开领地、数据变更和自定义 flag 注册。

读取时可以把 DTO 当作当前缓存状态的只读视图。虽然部分 DTO 暴露了 set... 方法，但附属不应直接调用它们修改持久化数据；写入应交给 Provider，以便 Dominion 执行权限、边界、经济、数据库和事件处理。

DominionAPI.getInstance() 和各 Provider 的单例只应在 Dominion 已经启用后获取；通常在 onEnable() 中初始化。
API 依赖建议使用 compileOnly，运行时由服务器中的 Dominion 插件提供。
Provider 操作返回 CompletableFuture，不要在主线程或 Folia 区域线程调用 get()、join() 等阻塞等待。
Provider 的 operator 参数决定操作身份。传入玩家会执行对应权限检查；传入控制台可以绕过玩家权限，但仍会执行数据合法性检查。
可能不存在的领地、玩家、成员或组通常返回 null；批量查询返回列表，失败的异步写入通常以 null 或 false 表示。
自定义 flag 的注册、展示和持久化不等于实现游戏行为。实际行为仍需由附属监听 Bukkit/Paper 事件并调用权限检查。