Firefly v1.0.3

发布日期：2026-08-02

v1.0.3 聚焦运行时状态所有权和输入边界。本版本没有引入大型 Web 框架、ORM，也没有改变 Netty 的传输定位；它把取消、超时、关键写请求、后台关闭和协议消息中的隐式规则收紧为可以测试的入口与失败行为。

构件发布状态

v1.0.3 源码 tag 和 Maven Central 构件均已发布。历史构件可在 Central Portal 查看；新项目应使用当前版本 1.0.6。

迁移范围

本版本明确不处理 MySQL 初始化数据库迁移的中途失败恢复。全新数据库初始化仍按现有流程执行；生产升级请继续遵循 DBA 的迁移窗口和备份策略。

主要变更

执行与 Outbox 生命周期

• 增加 ExecutionLifecycleService 和 JdbcExecutionLifecycleStore，为取消与超时提供统一生命周期入口。
• JDBC 取消和超时路径在各自事务中同时更新 execution、target 和 dispatch outbox；Admin 取消不再依次调用 Execution 与 Job 两个 Repository。
• 增加 JobCatalog、SchedulingStore、DispatchOutboxStore 和 ExecutionRetryStore 四个显式能力接口，JdbcJobRepository 声明其完整能力。
• 为兼容现有调用方，JobRepository facade 仍然保留；多数未实现的 Outbox 能力现在抛出 UnsupportedOperationException，但接口迁移尚未完全结束。

Admin 请求与服务配置

• 批量取消、批量重新入队和任务启用/禁用使用 Jackson request record，数组元素不再依靠逗号拆分，包含逗号的 ID 可以保持完整。
• Admin 写请求和服务端布尔配置只接受 true 或 false；treu 等拼写错误会让请求或启动失败。
• 增加 OptionSpec/OptionSchema 基础设施，并首先覆盖 JWT 核心命名空间的名称校验。插件配置和 JWT client 扩展仍保留开放空间。
• 其他兼容 Admin 路由仍可使用现有 Map 读取方式；本版本没有把所有请求一次性改成 record。

后台关闭与 Netty 协议

• ManagedWorker 统一执行 shutdownNow()、最多等待 5 秒、记录超时告警和执行所有权释放回调的顺序。
• 节点协调器在关闭开始时阻止新的 reconcile 进入；租约释放和节点离线标记在等待阶段结束后执行，包括等待超时的情况。
• Netty 增加 RegisterExecutorFrame、AckJobFrame、ReportResultFrame 和 NettyExecutorFrameMapper，Gateway 在进入对应业务分支前校验必需字段。
• NettyExecutorMessage envelope 和现有 Gateway Handler 仍保留兼容职责；command handler 拆分和协议 upcaster 不在本版本内。

Outbox 快照

• 新快照在现有 Map payload 外增加带 schemaVersion: 1 的 JSON envelope，并继续读取历史 v0 Map 编码。
• enabled、retryOnFailure 和 retryOnTimeout 等布尔字段缺失或非法时会明确失败，不再默认成 false。
• 本版本版本化的是外层 envelope；内层 payload 仍是 Base64 编码的既有 Map 格式，并非完整的 JSON JobDefinition schema。

升级检查

1. 历史项目可升级到 1.0.3；新项目应直接使用当前版本 1.0.6。
2. 在预生产验证 Admin 批量取消、批量重新入队、包含逗号的 ID，以及错误布尔值返回 4xx。
3. 观察节点关闭日志；正常情况应在 Worker 结束等待后释放租约，若出现 5 秒超时告警，应排查未响应中断的任务。
4. 检查自定义 Netty 客户端仍提供协议版本、实例和会话字段，并满足 Register、ACK、Result 帧的必填字段约束。
5. MySQL 初始化迁移恢复不在本版本范围内，升级前按现有 DBA 流程执行并保留回滚备份。

非目标与已知边界

• 不承诺 exactly-once；业务副作用仍需业务唯一键或事务幂等。
• JobRepository 兼容 facade、Admin 通用 Map reader 和集中式 Netty Gateway Handler 仍然存在，本版本先建立可迁移的类型边界。
• ManagedWorker 提供限时等待而非无限阻塞；等待超时后仍执行释放回调，因此超时告警必须作为运维信号处理。
• 不改变 schema 初始化流程；MySQL 中途失败恢复需后续单独设计和验证。

完整源码请查看 Firefly v1.0.3 Tag。