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 重命名是唯一带迁移窗口的变更：旧名字在 0.22.x 中仍然能解析，但会打印弃用警告，未来版本将移除这些别名。其余两项不做兼容，升级后直接不生效。文档的建议是：只执行触及你项目实际用到了的那部分步骤，不必盲目全部照做。

Step 1：重命名常驻 Worker

以下五个“always-running”（随引擎常驻）Worker 在 0.22.x 中去掉了iii-前缀。需要在所有引用处重命名，包括config.yaml条目、iii worker add命令、trigger 类型引用等：

config.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 注册函数 API

Rust 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 Worker；
• Node、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-config（Step 3）
• 把 Rust 代码中的new_async_with_bad_request替换为new_async（Step 4）

升级完成后的验收标准

完成上述步骤后，项目在 0.22.x 上应当满足以下结果（可直接作为升级 PR 的验收条件）：

1. 引擎启动时没有任何弃用警告——五个常驻 Worker 全部使用不带前缀的新名称；
2. config.yaml中每个 Worker 只出现一次，不存在旧/新名称对；
3. 引擎可以在不携带已移除标志的情况下正常启动（脚本、Dockerfile、CI 中已无--use-default-config）；
4. Rust Worker 能够针对现行的函数注册 API 编译通过，不再引用new_async_with_bad_request。

延伸阅读

• 升级文档原文：docs/0-21-0/upgrading/from-0-21-x.mdx
• 无配置启动行为：docs/0-21-0/using-iii/engine.mdx
• Rust SDK 注册函数实现：sdk/packages/rust/iii/src/iii.rs
• Rust 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