iii SDK 从 0.19.x 升级到 0.20.xNode / Python / Rust 三语言导入体系重构完整迁移指南【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii0.20.0 是 iii SDK 的一次单步破坏性重构共享类型被抽入新的iii-dev/helpers包、三语言命名完成对齐、可观测性并入 helpers其余根导出全部归入子模块。本文基于仓库中的官方升级文档完整继承 9 个迁移步骤含全部命令与前后对照代码并结合sdk/packages/下的实际源码布局与 0.20.0 changelog帮助你在 Node / TypeScript、Python、Rust 上把 Worker 代码一次性迁移到 0.20.x 的可编译状态。升级总览一次干净断裂clean break0.20.0 的关键设计原则是不保留旧路径所有旧根导入路径被直接删除而不是保留为 deprecated 别名。也就是说你的应用在完成全部步骤之前无法编译——错误信息找不到的模块/符号本身就是你的迁移清单。官方文档同时明确了两个无需迁移的向后兼容例外EnqueueResult所有语言和TriggerActionVoidPython继续从根 SDK 导出作为TriggerAction的伴生类型独立的iii-observability包仍以 deprecated shim 形式继续发布可按自己的节奏迁移对应下文 Step 5。每一步变更的动机可参考 0.20.0 changelog仓库中 docs/changelog/0-20-0/ 目录下的各篇条目分别对应本次重构的五个切面organize-sdk-imports导入组织、extract-helpers-libhelpers 抽包、observability-into-helpers可观测性迁入、cross-language-parity跨语言对齐与submodule-clean-break子模块干净断裂。Step 1添加新包在安装新版 SDK 的同时安装 helpers 包Node / TypeScriptnpm install iii-sdk^0.20 iii-dev/helpersPythonpip install iii-sdk0.20 iii-helpersRustcargo add iii-sdk0.20 iii-helpers使用可观测性的项目可以暂时保留iii-observabilitydeprecated shim或直接在 Step 5 中完成迁移。从源码结构看helpers 包与 SDK 主包在仓库中是并列的一等成员Node 侧位于 sdk/packages/node/helpers其src目录按四个共享域组织——http/、queue/、stream/、worker-connection-manager/外加独立的observability/目录Rust 侧对应 sdk/packages/rust/helpersPython 侧为 sdk/packages/python 中的iii_helpers。这与文档描述的四个 helpers 子模块 observability一一对应。Step 2重命名客户端句柄将 Node 的ISdk和 Rust 的III统一重命名为IIIClientPython 原本就叫IIIClient无需改动。同一轮改动中Rust 的遥测配置WorkerTelemetryMeta也要改名为TelemetryOptions。Node / TypeScript// Before import type { ISdk } from iii-sdk // After import type { IIIClient } from iii-sdkPython# No change. Python already used IIIClient.Rust// Before let sdk: III /* ... */; use iii_sdk::WorkerTelemetryMeta; // After let sdk: IIIClient /* ... */; use iii_sdk::TelemetryOptions;这一步正是 changelog 中cross-language parity的直接体现三种语言从此共享同一个客户端类型名阅读跨语言示例时不再需要记忆两套别名。Step 3更新 HTTP 请求/响应类型缓冲式buffered的ApiRequest/ApiResponse类型改名为HttpRequest/HttpResponse并与HttpAuthConfig、HttpInvocationConfig一起迁入 helpers 的http子模块。Node / TypeScript// Before import { ApiRequest, ApiResponse } from iii-sdk // After import { HttpRequest, HttpResponse } from iii-dev/helpers/httpPython# Before from iii import ApiRequest, ApiResponse # After from iii_helpers.http import HttpRequest, HttpResponseRust// Before use iii_sdk::{ApiRequest, ApiResponse}; // After use iii_helpers::http::{HttpRequest, HttpResponse};注意只有缓冲式Api*类型发生了迁移和改名流式streaming的StreamRequest/StreamResponse类型留在根 SDK 中不要改动。仓库源码印证了这些类型的实际内容。在 sdk/packages/node/helpers/src/http/index.ts 中可以看到HttpMethod限定为GET | POST | PUT | PATCH | DELETE源码注释明确指出它与引擎builtin_triggers的方法枚举不同后者还覆盖 HEAD/OPTIONSHttpAuthConfig是三种鉴权方式的联合类型{ type: hmac; secret_key }、{ type: bearer; token_key }、{ type: api_key; header; value_key }HttpInvocationConfig用于调用 HTTP 型函数Lambda、Cloudflare Workers 等字段包括url必填、method默认POST、timeout_ms、headers、authHttpRequestTBody携带path_params、query_params、body、headers、method以及原始请求体的流式读取器request_body。这些字段说明在迁移时非常实用如果你的旧代码在构造或断言 HTTP 载荷时依赖ApiRequest的具体结构可以直接对照上述定义逐项检查。Step 4将共享类型迁入 iii-dev/helpers共享类型被归入四个 helpers 子模块三语言导入路径如下GroupNodePythonRusthttpiii-dev/helpers/httpiii_helpers.httpiii_helpers::httpqueueiii-dev/helpers/queueiii_helpers.queueiii_helpers::queuestreamiii-dev/helpers/streamiii_helpers.streamiii_helpers::streamworker-connection-manageriii-dev/helpers/worker-connection-manageriii_helpers.worker_connection_manageriii_helpers::worker_connection_manager其中UpdateOp、UpdateOpError、MergePath、UpdateSet、UpdateMerge现在位于stream子模块MergePath是命名导出。Rust 侧有细微差异UpdateSet和UpdateMerge不是独立类型而是UpdateOp::Set与UpdateOp::Merge两个变体。Node / TypeScript// Before import { HttpAuthConfig } from iii-sdk // After import { HttpAuthConfig } from iii-dev/helpers/httpPython# Before from iii import HttpInvocationConfig, AuthInput # After from iii_helpers.http import HttpInvocationConfig from iii_helpers.worker_connection_manager import AuthInputRust// Before use iii_sdk::{HttpAuthConfig, StreamTriggerConfig}; // After use iii_helpers::http::HttpAuthConfig; use iii_helpers::stream::StreamTriggerConfig;例外提醒EnqueueResult是queue子模块中的特例。它的规范位置是iii-dev/helpers/queueiii_helpers.queue/iii_helpers::queue但它同时从根 SDKiii-sdk/iii/iii_sdk重新导出作为TriggerAction.Enqueue的伴生类型——因此不要迁移EnqueueResult的导入。关于流式类型的归属可以对照 sdk/packages/node/helpers/src/stream/index.ts 确认实际包含的符号StreamAuthInput/StreamAuthResult、StreamJoinLeaveEvent、StreamGetInput/StreamSetInput/StreamDeleteInput/StreamListInput等输入输出结构都在该模块中迁移流式相关代码时可直接以此为核对清单。完整的每个子模块迁移了哪些符号列表见各语言的 Helpers 参考文档NodePythonRustStep 5更新可观测性导入把可观测性相关导入移到 helpers 的observability子模块。Node / TypeScript// Before import { Logger, initOtel, withSpan } from iii-dev/observability // After import { Logger, initOtel, withSpan } from iii-dev/helpers/observabilityPython# Before from iii_observability import Logger, init_otel, with_span # After from iii_helpers.observability import Logger, init_otel, with_spanRust// Before use iii_observability::{Logger, init_otel, with_span}; // After use iii_helpers::observability::{Logger, init_otel, with_span};这是 9 个步骤中唯一可以延后的一步因为独立的iii-observability包仍以 deprecated shim 形式发布。一个细节需要特别注意仅 Node 内部使用的入口iii-dev/observability/internal直接迁到了iii-dev/helpers/observability/internal没有 shim用到它的项目必须立刻改。从源码结构看observability在 helpers 中是功能相当完整的独立目录sdk/packages/node/helpers/src/observability/ 包含logger.ts、http-instrumentation.ts以及telemetry-system/子目录connection.ts、exporters.ts、span-exporter.ts、metrics-exporter.ts、log-exporter.ts等与 Node SDK 中已废弃的独立包形成对应。Step 6更新错误类型与处理IIIInvocationError改名为InvocationErrorNode 位于iii-sdk/errorsPython 位于iii.errorsRust 的IIIError改名为Erroriii_sdk::errors::Error。旧名从根导出中删除没有 deprecated 别名。Node / TypeScript// Before import { IIIInvocationError } from iii-sdk // After import { InvocationError } from iii-sdk/errorsPython# Before from iii import IIIInvocationError # After from iii.errors import InvocationErrorRust// Before use iii_sdk::IIIError; // After use iii_sdk::errors::Error;Python 的IIIForbiddenError和IIITimeoutError被直接删除改为判断err.code与 Node 和 Rust 的行为对齐# Before try: ... except IIIForbiddenError: ... # After except InvocationError as err: if err.code FORBIDDEN: ...这一改动消除了 Python 独有、其他语言没有的细分异常子类让三语言的错误处理模式统一为单一错误类型 code 判别。Step 7采用 engine / protocol / internal / utils 子模块路径这四个分组的根导出被移除且无别名。Rust 侧的IIIConnectionState迁入iii_sdk::runtime。Node / TypeScript// Before import { RegisterTriggerInput, EngineFunctions } from iii-sdk // After import { RegisterTriggerInput } from iii-sdk/protocol import { EngineFunctions } from iii-sdk/enginePython# Before from iii import TriggerRequest, extract_request_format # After from iii.protocol import TriggerRequest from iii.utils import extract_request_formatRust// Before use iii_sdk::{TriggerRequest, EngineFunctions}; // After use iii_sdk::protocol::TriggerRequest; use iii_sdk::engine::EngineFunctions;这一批分组的完整映射见 changelog submodule-clean-break.mdx分组NodePythonRustengineiii-sdk/engineiii.engineiii_sdk::engineprotocoliii-sdk/protocoliii.protocoliii_sdk::protocolinternaliii-sdk/internaliii.internaln/autilsn/aiii.utilsn/a迁移符号包括engine 组的EngineFunctions、EngineTriggers、RemoteFunctionHandlerprotocol 组的MessageType、各Register*Message/Register*Input类型、TriggerRequest以及 Rust 独有的FunctionMessage和ErrorBodyinternal 组的InternalHttpRequestPython utils 组的extract_request_format、extract_response_format、python_type_to_format。changelog 明确说明会尊重语言差异——某语言不存在的符号不会凭空添加。TriggerActionVoidPython同样被归入iii.trigger但它保留在包根的导出中作为TriggerActionEnqueue的伴生类型从iii和iii.trigger两处都可访问无需迁移。Step 8采用 errors / channel / trigger / runtime 子模块这四个分组的旧根路径在 0.20.0 中同样被移除每种类型都需从其子模块导入。Node / TypeScript// Before import { ChannelReader, FunctionRef } from iii-sdk // After import { ChannelReader } from iii-sdk/channel import type { FunctionRef } from iii-sdk/runtimePython# Before from iii import ChannelReader, FunctionRef # After from iii.channel import ChannelReader from iii.runtime import FunctionRefRust// Before use iii_sdk::{ChannelReader, FunctionRef}; // After use iii_sdk::channel::ChannelReader; use iii_sdk::runtime::FunctionRef;结合 Step 7可以推断出 0.20.0 的根 SDK 表面收敛策略顶层只保留 Worker/运行时 API如IIIClient、TriggerAction及其伴生类型协议、引擎、内部工具等低层符号全部退居到清晰可导航的子模块路径之后——这也是 changelog 中给出的动机。Step 9替换被彻底移除的 API少数 API 不是搬家而是直接删除需要用等价写法替换RustUpdateBuilder→ 直接构造UpdateOp::Set/UpdateOp::Merge值RustFieldPath→ 保留下来的MergePath就是 merge/append 的路径参数RustValue重新导出被移除 → 直接依赖serde_jsonNodeTriggerActionType别名被移除 → 直接使用TriggerAction值。Node / TypeScript// Before import { TriggerActionType } from iii-sdk // After // Use the TriggerAction value directly; the TriggerActionType alias is gone.Python# No change.Rust// Before use iii_sdk::{UpdateBuilder, FieldPath, Value}; // After use iii_helpers::stream::{MergePath, UpdateOp}; use serde_json::Value;迁移清单按以下清单逐项核对与官方文档完全一致添加iii-dev/helpers并把iii-sdk升到 0.20.x重命名ISdk/III→IIIClient将缓冲式Api*→Http*改从iii-dev/helpers/http导入将共享类型移入 helpers 各子模块迁移可观测性导入可延后重命名III*Error→InvocationError/Error采用engine/protocol/internal/utils路径采用errors/channel/trigger/runtime路径替换被移除的 Rust/Node API迁移完成后的状态完成全部步骤后你的 Worker 以iii-sdk0.20.x 构建共享类型来自iii-dev/helpers三语言命名一致导入全部走子模块路径。此时唯一还会发出废弃信号的是尚未执行 Step 5 时保留的iii-observabilityshim。建议的实操顺序先在 CI 或本地直接升版本编译让找不到的符号错误把 Step 2–9 的全部命中点暴露出来再用 docs/0-21-0/reference/ 下的 Node SDK 参考、Python SDK 参考、Rust SDK 参考 核对每个符号的新归属最后对照本文清单做收尾确认。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
