Easy4Form API 版本说明

版本概述

Easy4Form 支持两个 API 版本：

版本	状态	Cumulus 接口	推荐使用
v1	已废弃	旧版接口	❌ 不推荐
v2	当前版本	新版接口	✅ 推荐

为什么推荐使用没有版本号的 API

1. 兼容性保证

// ✅ 推荐：使用代理层（自动处理版本兼容性）
import cn.enderrealm.easy4form.api.Easy4FormAPI;

// ❌ 不推荐：直接使用版本特定的类
import cn.enderrealm.easy4form.api.v1.Easy4FormAPI;
import cn.enderrealm.easy4form.api.v2.Easy4FormAPI;

原因：

• 代理层会根据配置自动路由到正确的版本
• 如果 v2 实现出现问题，会自动回退到 v1
• 业务代码无需修改即可支持新版本

2. 版本切换透明

使用代理层时，只需修改配置文件即可切换版本：

# config.yml
api-version: "v2"  # 修改这里即可切换版本

业务代码无需任何修改。

3. 未来兼容性

如果未来发布 v3、v4 等新版本：

• 使用代理层的代码无需修改
• 直接使用 v1/v2 的代码可能需要更新导入路径

版本差异详解

v1 vs v2 主要区别

特性	v1	v2
Cumulus 接口	旧版	新版
表单关闭响应	null	-1
性能	一般	更好
新功能支持	无	有

响应处理差异

// v1 表单关闭时返回 null
response -> {
    if (response == null) {
        // 表单被关闭
    }
}

// v2 表单关闭时返回 -1
response -> {
    if (response == -1) {
        // 表单被关闭
    }
}

// 使用代理层时，统一使用 null 表示关闭（自动转换）
response -> {
    if (response == null) {
        // 表单被关闭（无论 v1 还是 v2）
    }
}

配置说明

config.yml 配置项

# API 版本设置
# 可选值: "v1", "v2"
# 推荐使用 "v2" 以获得更好的性能和新功能
api-version: "v2"

# 是否启用版本迁移警告
# 当使用旧版本时会在控制台显示警告
migration-warnings: true

版本路由机制

VersionManager 的路由逻辑：

1. 读取配置文件中的 api-version
2. 尝试调用对应版本的实现
3. 如果失败，自动回退到 v1
4. 记录警告日志

// VersionManager 核心路由代码
try {
    String fullClassName = "cn.enderrealm.easy4form.api." + currentApiVersion + ".Easy4FormAPI";
    Class<?> targetClass = Class.forName(fullClassName);
    Method method = targetClass.getMethod(methodName, paramTypes);
    return method.invoke(null, args);
} catch (Exception e) {
    // 回退到 v1
    String fallbackClassName = "cn.enderrealm.easy4form.api.v1.Easy4FormAPI";
    // ...
}

迁移指南

从 v1 迁移到 v2

步骤 1：更新导入

// 旧代码（v1 直接导入）
import cn.enderrealm.easy4form.api.v1.Easy4FormAPI;
import cn.enderrealm.easy4form.api.v1.SimpleFormBuilder;

// 新代码（使用代理层）
import cn.enderrealm.easy4form.api.Easy4FormAPI;
import cn.enderrealm.easy4form.api.SimpleFormBuilder;

步骤 2：更新配置

# 旧配置
api-version: "v1"

# 新配置
api-version: "v2"

步骤 3：测试响应处理

// 旧代码（v1 响应处理）
response -> {
    if (response == null) {
        // 表单关闭
    } else {
        // 正常响应
    }
}

// 新代码（使用代理层，无需修改）
response -> {
    if (response == null) {
        // 表单关闭（代理层自动处理 v2 的 -1 -> null 转换）
    } else {
        // 正常响应
    }
}

最佳实践

1. 始终使用代理层

// ✅ 正确
import cn.enderrealm.easy4form.api.Easy4FormAPI;

// ❌ 错误
import cn.enderrealm.easy4form.api.v2.Easy4FormAPI;

2. 配置文件使用推荐版本

# ✅ 推荐
api-version: "v2"

# ❌ 不推荐
api-version: "v1"

3. 统一响应处理

// ✅ 正确：使用代理层的统一响应处理
response -> {
    if (response == null) {
        // 表单关闭
    } else {
        // 正常响应
    }
}

// ❌ 错误：直接处理 v2 的 -1
response -> {
    if (response == -1) {
        // 表单关闭
    } else {
        // 正常响应
    }
}

常见问题

Q: 为什么不推荐直接使用 v1/v2？

A: 直接使用版本特定的类会导致：

1. 版本切换时需要修改代码
2. 无法享受自动兼容性处理
3. 未来升级困难

Q: 如果 v2 有 bug 怎么办？

A: 使用代理层时，只需将配置改为 api-version: "v1" 即可回退，业务代码无需修改。

Q: 如何确定当前使用的版本？

A: 查看服务器启动日志，VersionManager 会打印当前使用的版本：

[Easy4Form] Version Manager loaded - Current API version: v2

Q: 可以同时使用 v1 和 v2 吗？

A: 不推荐。应该统一使用代理层，让 VersionManager 处理版本路由。