Effect JSON-RPC id 序列化边界修复0与空字符串 id 的保真处理及null通知哨兵映射【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文围绕 EffectTypeScript 类型安全函数式运行时当前仓库为 v4 RC 开发分支中 unstable RPC 模块的一次 JSON-RPC 2.0 序列化补丁展开讲解id字段取值为0、这类「falsey 但合法」值时如何被正确保真以及null如何继续被映射到 Effect 内部的空字符串通知哨兵。读完本文你将理解 JSON-RPC 请求 id 在 RpcSerialization.ts 中的编解码路径、通知notification的判定机制以及如何用仓库中的回归测试验证这类边界行为。背景JSON-RPC 2.0 的 id 语义与 Effect RPC 的映射JSON-RPC 2.0 规范中请求对象的id字段用于关联请求与响应其合法取值包括String、Number 或 Null当请求对象不包含id字段时它被视为通知notification服务端不得返回响应。这意味着id: 0数字零是合法的请求标识即使它在 JavaScript 中属于 falsey 值id: 空字符串同样是合法的请求标识同样 falseyid: null虽然按规范「允许」但在 Effect 内部被特殊对待——映射为通知哨兵。在 Effect 的 RPC 协议层传输编码后的请求信封由RequestEncoded表示见 RpcMessage.tsexport interface RequestEncoded { readonly _tag: Request readonly id: string | number readonly tag: string readonly payload: unknown readonly headers: ReadonlyArray[string, string] readonly isNotification?: true readonly traceId?: string readonly spanId?: string readonly sampled?: boolean }id的类型是string | number而isNotification是可选的布尔标记。问题在于当id取值为0或时如果编解码逻辑使用「真值判断」truthy check如request.id || 就会把这些合法 id 误判为「缺省」从而破坏请求与响应的关联而null则需要始终折叠为内部哨兵。这正是本次补丁要处理的边界。修复内容变更集说了什么本次修复记录在.repos/effect-smol/.changeset/pre/fix-rpc-json-id-edges.md属于effect包的patch级变更原文如下Fix JSON-RPC serialization foridvalues that are falsey but valid, including0and, while still mappingnullto Effects internal notification sentinel.翻译为技术要点本次补丁保证三条语义同时成立id: 0在 JSON-RPC 编解码往返中保持为0不会被丢失或改写id: 在往返中保持为空字符串不会被当作「无 id」处理id: null仍然映射为 Effect 内部的通知哨兵即空字符串维持既有的通知协议兼容性。源码层面nullish 合并如何保住 falsey id修复的核心落在RpcSerialization.ts的decodeJsonRpcMessage函数RpcSerialization.ts。请求分支的关键代码是return { _tag: Request, id: request.id ?? , tag: request.method, payload: request.params ?? null, headers: request.headers ?? [], ...(Predicate.hasProperty(request, id) ? {} : { isNotification: true as const }), ... }这里的??是nullish 合并运算符它只在左侧为null或undefined时取右侧默认值因此request.id 0→id: 0原样保留request.id →id: 原样保留request.id null→id: 即内部通知哨兵。对比之下若使用||逻辑或0与都会被折叠成0这个合法 id 就会在解码瞬间丢失。可以推断此前的实现正是这类真值判断导致0与空字符串 id 无法保真本次补丁将其统一替换为 nullish 语义。通知的判定则独立于 id 值本身取决于请求对象上是否存在id属性而非其取值请求没有id属性 →isNotification: trueid 落到哨兵请求有id属性哪怕值是null→ 不标记为通知id 仍按?? 兜底。编码方向通知省略 id其余一律写出对应的编码逻辑在encodeJsonRpcMessage的Request分支RpcSerialization.tscase Request: return { jsonrpc: 2.0, method: response.tag, params: response.payload, // a JSON-RPC notification is a request without an id ...(response.isNotification ? {} : { id: response.id }), ...(response.headers?.length 0 ? { headers: response.headers } : {}), traceId: response.traceId, spanId: response.spanId, sampled: response.sampled }只有isNotification为 true 时才省略id其余情况下id: response.id会被无条件写出因此0与在编码方向同样完整保留。两种 JSON-RPC 序列化共用同一路径仓库提供两种 JSON-RPC 序列化jsonRpc(options?)无帧面向自带帧的传输层默认 content type 为application/json与ndJsonRpc(options?)基于 NDJSON 分帧content type 默认为application/json-rpc分别见 RpcSerialization.ts 与 RpcSerialization.ts。二者最终都调用decodeJsonRpcMessage/encodeJsonRpcMessage因此本次修复对两种模式同时生效无需分别处理。测试验证回归用例锁定的四条边界仓库在 RpcSerialization.test.ts 中为这次修复提供了成组的回归测试直接对应变更集声明的语义1.id: 0往返保真测试 L304-L326解码{jsonrpc:2.0,id:0,method:users.get}得到id: 0编码后输出{jsonrpc:2.0,method:users.get,params:null,id:0}——0未被吞掉。2.id: null映射到通知哨兵测试 L328-L338解码{jsonrpc:2.0,id:null,method:users.get}得到id: 即内部哨兵。3.id: 往返保真测试 L340-L362空字符串 id 解码为id: 编码后输出{jsonrpc:2.0,method:users.get,params:null,id:}——被明确写出而非被省略。4. 无 id 的请求编码为通知测试 L364-L391不带id属性的请求解码后携带isNotification: true编码时id被省略输出{jsonrpc:2.0,method:notifications/message,...}。这组测试把「falsey 但合法」与「真正的通知」彻底区分开0/是合法 id 必须保真null折叠为哨兵缺失id才是通知的唯一判定依据。对使用者的影响与实操建议与异构系统互操作时如果你的服务端或客户端会对端发送id: 0或id: 的请求一些语言与框架默认从 0 开始计数 id升级到包含此补丁的effect版本后这些请求的响应关联将不再错乱。自定义序列化实现如果你基于RpcSerialization.RpcSerialization服务RpcSerialization.ts实现自己的传输层应遵循同样的原则用?? 兜底 id用hasProperty(obj, id)判定通知切勿对 id 做真值判断。通知协议的约定需要发送通知时请省略id字段而不是显式传null或这样解码端才能正确标记isNotification显式null只会折叠为哨兵 id不会被识别为通知。版本边界该变更位于.changeset/pre/pre-release 变更集作用于effect包的 patch 版本Effect v4 当前以rc标签发布见仓库 README.md安装命令为npm install effectrc需要 TypeScript 5.9 且开启strict模式。生产环境请以实际发布的 changelogpackages/effect/CHANGELOG.md为准确认版本。小结一次看似只有一句话的 patch 变更实际锁定了 JSON-RPC 序列化中最容易被忽略的一类边界falsey 但合法的id。通过?? 的 nullish 语义替代真值判断0与空字符串在编解码往返中得以保真通过hasProperty判定通知、用作为null的折叠哨兵既保住了 id 关联的正确性又没有破坏既有的通知协议。这正是 Effect RPC 协议层在「严格类型安全」与「协议兼容」之间精细取舍的一个缩影值得所有自定义 RPC 序列化实现借鉴。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
