iii 0.22.x 升级指南：Worker 重命名、配置重复校验、`--use-default-config` 移除与 Rust SDK 注册函数 API 变更

iii 0.22.x 升级指南Worker 重命名、配置重复校验、--use-default-config移除与 Rust SDK 注册函数 API 变更【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文基于 iii 官方升级文档0.21.x 到 0.22.x逐条讲解本次升级的三类变更——五个常驻 Worker 的iii-前缀重命名带弃用迁移窗口、config.yaml中旧名/新名同时出现的启动级报错、以及引擎 CLI 标志与 Rust SDK 构造函数的两处干净移除——并给出每一步的操作步骤、前后对照代码和可复制到项目中的迁移清单帮助你把现有 iii 项目平滑升到 0.22.x 且无弃用警告。原始升级文档见 docs/0-21-0/upgrading/from-0-21-x.mdx本篇在文档骨架之上补充了当前仓库中的源码与测试佐证。0.22.x 变更总览0.22.x 的破坏性变更共三处性质不同迁移策略也不同变更类型影响面五个常驻 Worker 去掉iii-前缀弃用 迁移窗口config.yaml、iii worker add命令、trigger 类型引用移除--use-default-config引擎标志干净移除clean break脚本、Dockerfile、CI 配置移除 Rust SDK 的RegisterFunction::new_async_with_bad_request干净移除clean break调用过该构造函数的 Rust Worker其中 Worker 重命名是唯一带迁移窗口的变更旧名字在 0.22.x 中仍然能解析但会打印弃用警告未来版本将移除这些别名。其余两项不做兼容升级后直接不生效。文档的建议是只执行触及你项目实际用到了的那部分步骤不必盲目全部照做。Step 1重命名常驻 Worker以下五个“always-running”随引擎常驻Worker 在 0.22.x 中去掉了iii-前缀。需要在所有引用处重命名包括config.yaml条目、iii worker add命令、trigger 类型引用等旧名称新名称iii-httphttpiii-croncroniii-queuequeueiii-statestateiii-pubsubpubsubconfig.yaml中的写法示例workers: - name: http - name: queue弃用窗口期的具体行为旧的带前缀名称在 0.22.x 中仍能解析所以升级后项目依然能正常启动不会因为没改名字而立刻挂掉但iii worker add对旧名称会打印弃用警告deprecation warning且未来版本会彻底移除这些别名文档建议现在就重命名以消除警告避免后续版本再来一轮改动。需要注意的边界本次只有上表五个 Worker 去掉了前缀其余仍带iii-前缀的 Worker 暂时保留前缀但文档同时提示它们中的大多数将在未来版本中移除后续升级时还需留意。Step 2清理 config.yaml 中的重复 Worker 条目这是本次升级中唯一从“警告”升级为“启动失败”的行为0.22.x 的引擎会拒绝同时列出废弃旧名与其新替换名的config.yaml启动直接失败抛出Duplicate worker configurations错误且报错信息中会点名冲突的那一对例如同时出现iii-http和http。处理方式很简单删除或重命名冲突条目保证config.yaml中每个 Worker 只保留一个条目。警告每个 Worker 必须恰好保留一个条目。同时列出iii-http和http或任何其他旧/新名称对是一个硬性的启动错误hard startup error会直接阻止引擎启动。请删除已弃用deprecated的那个条目。这一步的实操建议升级前先用文本搜索扫一遍config.yaml检查是否同时存在iii-http|iii-cron|iii-queue|iii-state|iii-pubsub与新名称中的重复对如果有只保留新名称。Step 3移除--use-default-config引擎标志--use-default-config引擎标志在 0.22.x 中被移除。取而代之的新行为是不带config.yaml直接运行iii时引擎会自动创建一个带空workers:列表的配置文件且按环境区分交互方式交互式终端会先提示确认然后写入文件非交互环境CI、容器等不再询问直接写入文件。因此需要做的迁移动作是把--use-default-config从所有脚本、Dockerfile 和 CI 配置中删掉。# Before iii --use-default-config # After iii project init . iii同时文档给出的建议是对于全新的 iii 项目推荐用iii project init来初始化而不是依赖无配置自动创建的机制。关于无配置启动的当前行为细节可参考 Engine 文档。当前仓库中的源码可以印证该标志确实已被移除且是通过测试锁定的engine/src/main.rs#L521-L528 中的单元测试use_default_config_is_no_longer_a_flag直接解析[iii, --use-default-config]并断言该参数不再被接受engine/tests/cli_args.rs#L42-L56 中的集成测试test_use_default_config_flag_is_rejected真实执行带--use-default-config的二进制断言 stderr 中出现unexpected argument或提及该标志确认 CLI 在运行期也会拒绝它。这意味着如果你在 CI 里写死了该标志升级后不会静默失效而是会收到明确的参数解析报错便于快速定位。Step 4更新 Rust 注册函数 APIRust SDK 移除了RegisterFunction::new_async_with_bad_request构造函数。异步 handler 现在统一通过RegisterFunction::new_async注册输入反序列化deserialization失败不再经由调用方自定义的 mapper 转发而是统一以Error::Serde形式向上传递。// Before let reg RegisterFunction::new_async_with_bad_request(handler, |e| my_error(e)); // After let reg RegisterFunction::new_async(handler);当前仓库中的 Rust SDK 源码印证了这一形态sdk/packages/rust/iii/src/iii.rs#L830 定义了RegisterFunction::new_async是注册异步函数的现行入口sdk/packages/rust/iii/src/error.rs#L45 中的Error::Serde(err.to_string())构造路径以及 sdk/packages/rust/iii/src/helpers.rs#L43-L103 中各 helper 内部“先RegisterFunction::new_async注册、失败时map_err为Error::Serde”的写法都对应文档所述“反序列化失败统一以Error::Serde暴露”的新约定。适用面说明本步骤只影响调用过被移除构造函数的 Rust WorkerNode、Python、Browser、Go Worker 在此步骤无需任何改动文档也指出该 handler 在 Rust SDK 中只存在了很短的时间实际项目中正在使用它的代码大概率很少。如果你的 Rust Worker 没有引用new_async_with_bad_request这一步可以直接跳过。迁移清单对照原文档给出的清单升级 0.22.x 时逐项勾选在config.yaml、iii worker add命令与 trigger 类型中把五个常驻 Worker 重命名为不带前缀的新名称Step 1从config.yaml中移除任何“旧名/新名”重复的 Worker 条目Step 2从脚本、Dockerfile 和 CI 中删除--use-default-configStep 3把 Rust 代码中的new_async_with_bad_request替换为new_asyncStep 4升级完成后的验收标准完成上述步骤后项目在 0.22.x 上应当满足以下结果可直接作为升级 PR 的验收条件引擎启动时没有任何弃用警告——五个常驻 Worker 全部使用不带前缀的新名称config.yaml中每个 Worker 只出现一次不存在旧/新名称对引擎可以在不携带已移除标志的情况下正常启动脚本、Dockerfile、CI 中已无--use-default-configRust Worker 能够针对现行的函数注册 API 编译通过不再引用new_async_with_bad_request。延伸阅读升级文档原文docs/0-21-0/upgrading/from-0-21-x.mdx无配置启动行为docs/0-21-0/using-iii/engine.mdxRust SDK 注册函数实现sdk/packages/rust/iii/src/iii.rsRust SDK 错误类型定义sdk/packages/rust/iii/src/error.rs引擎 CLI 参数解析与移除测试engine/src/main.rs、engine/tests/cli_args.rs适用前提本文所有行为描述以当前仓库中 0.21.x 版本文档及其对应源码为准适用于从 0.21.x 升级到 0.22.x 的项目其中 Worker 重命名处于弃用迁移窗口期旧名称的别名在未来版本移除前保持可解析若你直接从更早版本升级请同时查阅对应版本区间的升级文档。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考