Firefly v1.0.5

合并日期：2026-08-07

v1.0.5 为传统 Java、Servlet、Guice 和命令行 Worker 提供独立的 firefly-remote-adapter。业务服务可以继续使用 Firefly Gateway 的长连接、心跳、重连、幂等结果存储和优雅关闭能力，而不需要引入 Spring。

本版本完整保留 Spring Boot Starter 接入方式。Remote Adapter 是新增的框架无关入口，不替代 Starter，也不会把调度定义的所有权移入业务进程。

构件发布状态

v1.0.5 实现已经通过 Firefly PR #26 合并到 master，但当前尚无 v1.0.5 源码 tag 或 GitHub Release。使用前请在 Central Portal 确认 firefly-bom、firefly-remote-adapter 和 Starter 的 1.0.5 构件已经完成发布与索引。

非 Spring Java Remote Adapter

新增 Maven Central 构件：

io.github.fishered:firefly-remote-adapter:1.0.5

Adapter 负责业务服务侧的 Executor 连接与生命周期：

• 读取 firefly.executor.* 配置或对应的 FIREFLY_EXECUTOR_* 环境变量。
• 连接一个或多个 Gateway，完成 Integration Key 鉴权、心跳和断线重连。
• 等待 Gateway 返回 REGISTERED 后才报告启动成功。
• 上报当前实例提供的 Handler 能力并接收真实任务派发。
• 复用 Netty Executor 的幂等结果存储、TLS 和优雅关闭行为。

稳定的 Handler 入口

固定业务方法使用框架无关的 @FireflyHandler，不依赖 Spring 注解：

import com.firefly.domain.ExecutionContext;
import com.firefly.integration.remote.FireflyHandler;
import com.firefly.integration.remote.RemoteExecutorAdapter;
import com.firefly.integration.remote.RemoteHandlerProvider;

final class BillingHandlers {
    @FireflyHandler
    void billing(ExecutionContext context) {
        // run business code
    }
}

RemoteExecutorAdapter.run(
        RemoteHandlerProvider.annotated(new BillingHandlers())
);

Adapter 自动生成 包名.类名#方法名 入口，例如：

com.example.BillingHandlers#billing

• 注解不允许手写 Handler 名称，减少命名重复和配置漂移。
• 只检查明确传入的业务对象，不扫描全局 classpath。
• 方法必须返回 void，参数为空或只有一个 ExecutionContext。
• 同一个类中被注解的重载方法会产生相同入口，并在连接 Gateway 前失败。
• 低层字符串 .bind(name, handler) 继续保留给动态或遗留集成。

Executor 与调度所有权

Remote Adapter 使用“Executor 必须已存在”的注册策略：

1. 在 Admin 中提前创建协议为 TCP 的固定 Executor。
2. 业务服务使用相同的 firefly.executor.name 启动 Adapter。
3. Adapter 只注册运行实例和 Handler 能力。
4. Job、Cron、路由、重试和启停继续由 Admin UI/API 管理。

未知 Executor 会被 Gateway 拒绝，即使 Gateway 对旧客户端仍允许自动创建，也不会由 Adapter 补建控制面定义。旧 Netty 客户端默认行为保持兼容。

最小环境变量配置：

FIREFLY_EXECUTOR_NAME=billing-executor
FIREFLY_EXECUTOR_GATEWAY_ADDRESSES=firefly-1:9700,firefly-2:9700
FIREFLY_EXECUTOR_INTEGRATION_KEY=replace-with-integration-key

Firefly BOM

新增 io.github.fishered:firefly-bom:1.0.5，在 Maven 项目中只固定一次 Firefly 版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.fishered</groupId>
            <artifactId>firefly-bom</artifactId>
            <version>1.0.5</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

之后根据服务类型选择一个依赖，无需再次声明版本。Spring Boot 服务使用：

<dependency>
    <groupId>io.github.fishered</groupId>
    <artifactId>firefly-spring-boot-starter</artifactId>
</dependency>

非 Spring Java 服务使用：

<dependency>
    <groupId>io.github.fishered</groupId>
    <artifactId>firefly-remote-adapter</artifactId>
</dependency>

BOM 管理 scheduler-core、plugin-api、netty-protocol、netty、executor-netty、Remote Adapter、Spring Boot Autoconfigure 和 Starter 的一致版本。它不会动态选择网络上的最新版。

Spring Boot 兼容性

• 原有 firefly-spring-boot-starter 接入方式和自动配置行为保持不变。
• @FireflyJob、任务同步、Gateway 注册、健康检查和 Spring 生命周期继续按原方式工作。
• Spring Boot 3.3.5、3.4.12、3.5.8 和 4.0.0 的隔离 Maven 消费测试全部通过。
• 没有数据库 Schema 迁移要求。

明确延期的范围

v1.0.5 只交付非 Spring Java Adapter。Python、Go、通用 HTTP Handler 和语言无关 Agent 不在本版本范围内；后续 Agent 将作为统一协议边界，具体语言 SDK 只封装配置、协议和本地 Handler 调用。

验证

• Remote Adapter 固定 Executor 注册、真实派发、重连和关闭测试通过。
• 未知 Executor、空或重复 Handler、非法注解签名在预期阶段失败。
• TLS 配置键与 Spring Starter 对齐。
• BOM 的坐标、pom packaging 和全部受管模块版本通过生成 POM 校验。
• 全模块单元测试、真实数据库测试和四条 Spring Boot 兼容矩阵在 CI 中通过。

完整接入步骤见快速开始和集成方式。