Easy4Form 核心架构

模块结构

cn.enderrealm.easy4form/
├── Easy4form.java              # 插件主类
├── api/                        # API 代理层
│   ├── Easy4FormAPI.java       # 多版本 API 代理
│   ├── SimpleFormBuilder.java  # 简单表单构建器代理
│   ├── CustomFormBuilder.java  # 自定义表单构建器代理
│   ├── ModalFormBuilder.java   # 模态表单构建器代理
│   ├── PlayerUtils.java        # 玩家工具类代理
│   ├── v1/                     # API v1 实现（已废弃）
│   └── v2/                     # API v2 实现（推荐）
├── manager/
│   └── VersionManager.java     # 版本管理器
├── compatibility/
│   └── V2CompatibilityHandler.java  # v2 兼容性处理器
└── utils/
    └── DebugUtils.java         # 调试工具类

核心组件

1. 插件主类 (Easy4form.java)

插件入口点，负责：

• 初始化版本管理器
• 加载配置文件
• 检测 Floodgate 插件
• 管理插件生命周期

public final class Easy4form extends JavaPlugin {
    private static Easy4form instance;
    private VersionManager versionManager;

    @Override
    public void onEnable() {
        instance = this;
        saveDefaultConfig();
        DebugUtils.init(this);
        versionManager = new VersionManager(this);
        // 检测 Floodgate...
    }
}

2. 版本管理器 (VersionManager.java)

核心路由组件，负责：

• 根据配置选择 API 版本
• 使用反射动态路由方法调用
• 处理版本回退（fallback 到 v1）
• 管理 Builder 实例映射

关键机制：

// 通过反射调用版本特定的实现
String fullClassName = "cn.enderrealm.easy4form.api." + currentApiVersion + ".Easy4FormAPI";
Class<?> targetClass = Class.forName(fullClassName);
Method method = targetClass.getMethod(methodName, paramTypes);
return method.invoke(null, args);

3. API 代理层 (api/Easy4FormAPI.java)

统一的 API 入口，所有业务代码都应该通过此类调用：

• 提供静态方法供业务代码调用
• 内部通过 VersionManager 路由到具体版本
• 自动处理版本兼容性

4. 兼容性处理器 (V2CompatibilityHandler.java)

处理 v1 和 v2 之间的差异：

• v1：表单关闭时返回 null
• v2：表单关闭时返回 -1
• 兼容性处理器自动转换，确保业务代码无需关心版本差异

数据流

业务代码
    ↓
Easy4FormAPI (代理层)
    ↓
VersionManager (路由)
    ↓
v1/Easy4FormAPI 或 v2/Easy4FormAPI (具体实现)
    ↓
Builder 构建表单
    ↓
Floodgate API 发送表单
    ↓
基岩版玩家

设计模式

代理模式 (Proxy Pattern)

• api/Easy4FormAPI.java 是代理
• api/v1/Easy4FormAPI.java 和 api/v2/Easy4FormAPI.java 是实际实现
• 代理层隐藏了版本差异，对业务代码透明

Builder 模式

• 所有表单构建器都使用 Builder 模式
• 支持链式调用，代码更清晰
• 示例：builder.title("标题").content("内容").button("按钮").send(player)

反射路由

• VersionManager 使用反射动态调用版本特定的方法
• 支持运行时版本切换
• 自动回退到 v1（如果 v2 实现不存在）

配置项

# config.yml
api-version: "v1"           # API 版本：v1 或 v2
detection-mode: "floodgate" # 基岩版玩家检测模式
uuid-prefix: "00000000-0000" # UUID 前缀（uuid 模式使用）
debug: false                # 调试模式
migration-warnings: true    # 版本迁移警告