effect Schema 默认值错误通道升级构造与解码默认值可携带 SchemaError 并沿路径传播【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文基于 t3code 仓库中 vendored 的 effect-smoleffect 的精简分支源码展开。仓库根目录下.repos/effect-smol/.changeset/pre/schema-defaults-issue-channel.md这份 changeset 记录了一次针对effect包的 patch 级行为变更传递给 Schema 默认值系列 API 的Effect现在允许在错误通道中携带SchemaError当默认值求值失败时解析器会解包底层的SchemaIssue.Issue并把它作为附带了所在字段路径的普通解析失败继续传播。读完本文你将掌握withConstructorDefault与withDecodingDefault*系列 API 的默认值错误处理语义、SchemaError与底层 issue 的解包链路以及如何用另一个 schema 的makeEffect/decode*直接充当默认值。一、这次变更改了什么changeset 原文解读该变更记录位于 .changeset/pre/schema-defaults-issue-channel.md处于pre预发布模式下对应的 changeset 配置见 .changeset/config.json要点如下变更级别effect: patch属于兼容性友好的行为增强不破坏既有调用方式受影响 APISchema.withConstructorDefault、Schema.withDecodingDefault、Schema.withDecodingDefaultKey、Schema.withDecodingDefaultType、Schema.withDecodingDefaultTypeKey五个默认值 API新语义传给这些 API 的Effect允许在错误通道中产生SchemaError失败传播方式默认值失败时解析器解包unwrap底层的SchemaIssue.Issue将其作为一次常规的解析失败向上传播并自动附加上默认值所在的外围字段路径surrounding path直接收益可以方便地把另一个 schema 的makeEffect/decode*结果当作默认值默认值的校验逻辑与主 schema 的解析体系无缝衔接。二、Schema 默认值 API 全景五个入口的职责划分在 Schema.ts 中五个 API 按构造期 vs 解码期和字段级 vs 键级key两条轴划分API阶段触发条件默认值表示错误通道withConstructorDefault构造make构造时字段缺失Typemake 输入侧可携带 Schema 解析错误失败即解析失败withDecodingDefault解码decodeUnknown等字段缺失或为undefined值级Encoded表示可携带SchemaErrorwithDecodingDefaultKey解码键缺失不允许undefined键级Encoded表示可携带SchemaErrorwithDecodingDefaultType解码字段缺失或为undefined值级Type表示无需再经过解码变换可携带SchemaErrorwithDecodingDefaultTypeKey解码键缺失键级Type表示可携带SchemaError从源码签名可确认这一划分withDecodingDefaultKey与withDecodingDefault的默认值类型为Effect.EffectS[Encoded], SchemaError, R见 Schema.ts 与 Schema.ts即默认值以编码侧表示给出需要再走一遍解码变换而withDecodingDefaultType的默认值类型为Effect.EffectS[Type], SchemaError, R见 Schema.ts以解码后的 Type 表示直接给出绕开解码变换withDecodingDefaultTypeKey则在此之上把键设为解码侧可选。三、核心机制SchemaError 如何被解包并沿路径传播变更的精髓在于错误通道的打通底层实现位于toIssueEffect见 Schema.tsfunction toIssueEffectA, R( self: Effect.EffectA, SchemaError, R ): Effect.EffectA, SchemaIssue.Issue, R { return Effect.catchCause(self, (cause) Effect.failCauseSync(() Cause_.map(cause, (error) error.issue))) }它把错误通道中的每个SchemaError通过Cause_.map(cause, (error) error.issue)剥离出底层的SchemaIssue.Issue即解包再交给外围解析器。外围解析器拿到该 issue 后会像对待普通解析失败一样把默认值所在的字段路径拼接到错误信息上——这就是 changeset 中以带有所在路径的解析失败传播的源码级含义。而真正何时执行默认值的判断在 SchemaGetter.ts 的withDefault中export function withDefaultT, R never( defaultValue: Effect.EffectT, SchemaIssue.Issue, R ): GetterT, T | undefined, R { return new Getter((o) { const filtered Option.filter(o, Predicate.isNotUndefined) return Option.isSome(filtered) ? Effect.succeed(filtered) : Effect.mapEager(defaultValue, Option.some) }) }逻辑很直白值不是undefined就直接放行否则求值默认值 Effect。withConstructorDefault在 AST 层的组装见 SchemaAST.ts同样以SchemaGetter.withDefault作为解码变换、SchemaGetter.passthrough()作为编码变换并把默认值以Link形式挂在字段上供构造期使用。四、构造默认值withConstructorDefault 的用法与新能力withConstructorDefault的完整签名见 Schema.tsexport function withConstructorDefaultS extends Constraint WithoutConstructorDefault( defaultValue: Effect.EffectS[~type.make.in], SchemaIssue.Issue ) { return (schema: S): withConstructorDefaultS make(SchemaAST.withConstructorDefault(schema.ast, defaultValue), { schema }) }它只接受满足WithoutConstructorDefault约束尚无构造默认值的 schema且是柯里化风格。最简单的用法是构造一个静态默认值import { Effect, Schema } from effect const MySchema Schema.Struct({ name: Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(anonymous))) }) MySchema.make({}).name // anonymouschangeset 带来的新能力是默认值不再局限于直接成功的静态值可以是任何会产生 Schema 解析错误的 Effect。最典型的场景是把另一个 schema 的decode*当作构造默认值——默认值本身要先通过校验校验失败时错误被解包为底层 issue并作为MySchema下对应字段的解析失败报告出来const schema Schema.Struct({ updatedAt: Schema.DateFromString.pipe( Schema.withConstructorDefault( Schema.DateFromString.decodeUnknown(1970-01-01T00:00:00.000Z) ) ) }) // 构造时未提供 updatedAt默认值经 DateFromString 解析后成功 schema.make({}) // { updatedAt: Date(1970-01-01T00:00:00.000Z) }若默认值里放的是无法解析的字符串make将抛出带updatedAt路径的解析失败而不是静默吞掉错误。五、解码默认值键级与值级、Encoded 与 Type 的组合解码期四个 API 的核心差异在于缺失的判定粒度和默认值的表示侧。以withDecodingDefaultKey为例其 docblock 示例见 Schema.tsconst MySchema Schema.Struct({ name: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(anonymous))) }) Schema.decodeUnknownSync(MySchema)({}).name // anonymous该 API 通过optionalKey(toEncoded(self))让键在编码侧可选键可缺失但不可为undefined默认值以Encoded表示给出仍需经过解码变换。而withDecodingDefault对应值级缺失或undefined都触发默认值适合字段可能被显式传undefined的场景。withDecodingDefaultType系列则以Type表示直接给出默认值实现上先toType(self)再做withDecodingDefault最后encodeTo(optional(self))见 Schema.ts——默认值不需要再经历一次解码语义更贴近字段本来就应该有这个值。这些 API 还统一支持encodingStrategy选项passthrough默认编码输出时保留该键值omit编码输出时省略该键。对应的编码变换在函数入口即根据选项选择SchemaGetter.omit()或SchemaGetter.passthrough()见 Schema.ts适合默认值只影响解码、不应污染输出的数据契约场景。六、失败语义的边界成功、解析失败与缺陷的分野默认值 Effect 允许失败但只允许以 Schema 解析错误的形式失败。这一点在 Schema.test.ts 中有明确的测试佐证正常路径Schema.FiniteFromString.pipe(Schema.withConstructorDefault(Effect.succeed(-1)))在make({})时返回{ a: -1 }构造失败则抛出错误见 Schema.test.ts解析失败合法错误通道Effect.failCause(cause)产生的错误会按解析失败处理缺陷非法错误通道若传入Effect.die(new Error(...))这类非 Schema issue 的缺陷测试断言make抛出Constructor adapter can only throw schema issuesmakeOption抛出Option adapter can only return none for schema issues且底层Cause.hasDies(...)为真见 Schema.test.ts。这从反面印证了 changeset 的语义边界错误通道被拓宽的是Schema 体系内的解析错误而非任意异常或缺陷。默认值函数内部若发生真正的程序缺陷仍会被作为缺陷暴露不会被误包装成输入校验错误。七、实践指引与迁移建议对正在使用或升级到该版本的开发者默认值可以懒解析了当默认值本身有校验需求如日期字符串、UUID、枚举校验直接内联另一个Schema.decodeUnknown(...)/makeEffect即可无需手写catchAll再手工拼接路径——路径拼接由解析器自动完成。按语义选 API键级Key系列强调键不存在值级系列额外覆盖undefinedEncoded系列默认值走完整解码管线Type系列绕开解码变换二者在默认值形态上二选一。编码输出策略别忘配需要仅解码用默认值、编码时省略时显式传{ encodingStrategy: omit }。兼容性本次为 patch 级变更原有Effect.succeed(静态值)的用法完全不受影响唯一需要注意的行为差异是——如果你的默认值 Effect 之前恰好通过错误通道返回了SchemaError此前可能被视为意外错误现在它会按带路径的解析失败正确传播。八、小结本次变更把 Schema 默认值的错误处理纳入统一的解析错误体系默认值 Effect 的错误通道放宽为可携带SchemaError失败时经toIssueEffect解包出底层SchemaIssue.Issue再以带字段路径的解析失败继续传播。结合 SchemaGetter.withDefault 的undefined触发逻辑与 SchemaAST.withConstructorDefault 的变换组装整个默认值机制现在既支持静态兜底值也支持由另一 schema 的解析结果充当默认值这种组合式用法让数据契约中的可选字段与校验逻辑在类型层面真正对齐。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考