Core 2.0 Alpha 迁移
将服务获取和 target 迁移到 connection-resource API。
Core 2.0 alpha 使连接变得显式。旧服务获取 API 被移除,不保留兼容 alias。 本页描述从 Core 1.2 到当前 alpha 发布线的迁移。请同时查看所安装 alpha 版本的发布说明;新增变更可能先于发包出现在本页。
移除的 entry 是 create、safeCreate、select、safeSelect、createMulticast、safeCreateMulticast、selectMulticast 和 safeSelectMulticast。
关联的 CreateOptions、SelectOptions、multicast option type、RuntimeCreateTokenParam 和 default-target option type 也被移除。
使用 ConnectOptions、ConnectMulticastOptions 和每个 handle 的 ResourceOptions。
State 也直接使用 ConnectOptions;ConnectNexusStoreOptions 被移除。
Mock call record 保留其 object shape,不再有独立的 MockNexus*Call export。需要 annotation 时从 MockNexus["calls"] 推导 record type。
过时的 NexusTargetingError 和 provider-wait/default-target error code 被移除;连接获取现在报告具体 connection error。
普通 proxy lifecycle API 也被移除:Nexus.getProxyStatus、Nexus.subscribeProxyStatus、Nexus.inspectProxy、ProxyStatus、ProxyDebugSnapshot 以及 React 的 useProxyStatus。
保留 connect 返回的 Connection,用 onDisconnected 或 subscribeIdentity 观察它。
useStoreStatus 仍是 Nexus State handle 的 React lifecycle observer。
State 校验
State 的 validation.state 和 validation.actionResults 现在接受同步的 Standard Schema 验证器。现有 Zod 4 验证器仍受支持,Valibot 和 Zod Mini 使用同一入口。Nexus 不再将 Zod 作为生产依赖,使用 Zod 的应用应自行声明依赖。
校验保留原始快照和动作结果,不要依赖 schema 的默认值、强制转换或 transform 来规范化共享数据。不支持异步验证器。参阅 State 校验 Schema。
内部协议校验改用 Valibot,在分发前拒绝格式错误的消息字段。已有合法 wire 格式及旧 invocation packet 布局保持兼容。
替换服务获取
替换一次服务获取:
const service = await nexus.create(SettingsToken, { target });改为显式连接后再同步查询 catalog:
const connection = await nexus.connect({ target });
const service = connection.get(SettingsToken);Safe 形式分离两个失败边界:
const connected = await nexus.safeConnect({ target });
if (connected.isErr()) {
report(connected.error);
} else {
const service = connected.value.safeGet(SettingsToken);
if (service.isErr()) report(service.error);
else await service.value.read();
}get 和 safeGet 不拨号、不等待 provider、不创建远程业务对象。它们检查已经 ready 的 connection 的 provider catalog。
现有 Asyncified<T> type 仍是 lazy remote service value 的类型级映射。RemoteValue<T, M> 仍是带 connection provenance 的结构化 thenable;两者都不增加 cancellation 或 connection ownership。
被动连接获取
没有 target 的 connect({ where, timeout, signal }) 等待恰好一个已有的匹配 ready connection。
它绝不发现 provider,也不会从 Token、TokenSpace、endpoint 或适配器默认值推导 target。多个匹配是歧义;timeout 或 abort 只结束当前 caller 的等待。
where(contextMeta, connectionMeta) 是获取约束。它不会针对每个 RPC 重新评估,也不能替代授权 policy:
policy.canConnect授权逻辑连接建立。where选择符合应用约束的已获取 connection。policy.canCall授权每个服务或资源操作。
如果 peer 在初始 session 后发布服务,请在改变 peer 的应用 readiness marker 前发布 provider。
等待 marker 的 peer 可以在 where 中传入该 marker;仍应使用 get 或 safeGet 检查真实 catalog。
替换 Multicast API
使用 connectMulticast 获取固定连接快照:
const collection = await nexus.connectMulticast({
targets,
where: matchesWorker,
});
const resources = collection.get(TaskToken);
const results = await Promise.all(
resources.map(async ({ connection, result }) => ({
connection,
result: result.isErr()
? result
: await Nexus.safeCall(result.value.run(input)),
})),
);有显式 targets 时,每个 target 都必须获取。没有 targets 时,操作为当前匹配的 ready connection 建立快照,可以返回空 collection。
Collection 不会改变成员关系。每个 get item 保留 source connection 和自己的获取 Result;失败成员不会静默过滤。
移除的 createMulticast、safeCreateMulticast、selectMulticast 和 safeSelectMulticast API 没有直接兼容替代。
使用 (await nexus.connectMulticast(...)).get(Token) 和普通 Promise helper。
移除默认 target 和 provider wait
从以下位置移除 defaultTarget:
Token和TokenSpace定义- endpoint 配置和 decorator
- 适配器 helper options
- State token 和 State connection options
将精确的适配器 target 传给 connect 或 connectMulticast。
只有当应用需要独立于服务获取的一次启动拨号时,才使用 endpoint 显式的 connectTo startup list。
它不等待 provider,也不会让 ready() 等待拨号。
provider-level wait 配置没有替代。等待 connection 使用带正 timeout 和可选 signal 的被动 connect。
等待延迟服务时,在 peer ready marker 前发布它,然后获取 connection 并调用 get。
State 选项
connectNexusStore 和 safeConnectNexusStore 仍可用。它们的 options 遵循 ConnectOptions:精确 target、获取 where、正 timeout 和可选 signal。
它们不接受 Token 或 endpoint default target、provider wait setting,也不接受单独的 State targeting model。
State action call 保留自己的 Core resource-call timeout 行为。
State 仍在获取后观察选定 peer 的 identity:如果 where predicate 不再匹配,State handle 会变成 stale。
这是 State lifecycle 行为,不是共享 Connection 保留的 predicate,也不是应用于普通服务调用的授权检查。
Resource 和调用规则
RemoteValue<T, M> 是带只读 connection provenance 字段的结构化 thenable type。
声明方法调用或读取远程属性是 lazy 的;消费时才开始操作。需要 Result 时对一次调用使用 Nexus.safeCall。
使用业务方法,不要远程属性赋值。
迁移不会移除现有的 Asyncified<T> type mapping、实例 release/safeRelease method 或顶层 Expose/Endpoint decorator shorthand。
这些 API 保留可用;移除仅限旧获取族、default-target 配置和上文所述的 provider wait 配置。
Connection、service proxy、ref、回调和 State handle 都绑定 session。断开、reload、restart 或 session replacement 后,重新连接并取得新的 handle。
release 和 safeRelease 仍是远程引用的显式释放操作;不会关闭共享 connection 或调用应用清理。
Bootstrap 声明
在 bootstrap 开始前注册 @nexus.Expose 和 @nexus.Endpoint class。
延迟 decorator 应用现在会显式失败;ready() 后的实时服务注册使用 provide(...)。
一次提交内,或最终配置 provider 与 decorated class 之间的重复 provider ID,会在 service factory 运行前失败。
独立配置层仍保留 last-wins 行为。Factory 接收有效 endpoint metadata,包括 decorator 定义的 metadata。
safeReady() 在后续调用中返回相同启动失败;不会重试初始化。