Effect Schema 过滤器输出扩展FilterOutput / FilterIssue 深度指南【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本文聚焦 Effect 开源仓库packages/effect中 Schema 模块对自定义过滤器filter失败输出的一次关键演进通过扩展FilterOutput类型并新增FilterIssue让Schema.makeFilter的谓词既可以精确地把失败挂载到嵌套路径上自动构造Pointer也可以一次性汇总多个校验失败自动聚合为Composite无需再手动引入SchemaIssue手工拼接底层 issue 结构。阅读本文后你将掌握新版过滤器返回值的全部形态、与旧版{ path, message }的机械迁移方法以及SchemaGetter.checkEffect同步改名的细节并能直接落地到自己的校验代码中。背景makeFilter与FilterOutput的归一化流程在 Effect Schema 中Schema.makeFilter用于从谓词函数创建自定义校验过滤器谓词接收“已解码的输入值、Schema AST、解析选项”三个参数并返回一个FilterOutput。makeFilter的完整签名位于 Schema.tsexport const makeFilter: T( filter: (input: T, ast: SchemaAST.AST, options: SchemaAST.ParseOptions) FilterOutput, annotations?: Annotations.Filter | undefined, abort?: boolean ) SchemaAST.FilterT SchemaAST.makeFilter从源码看FilterOutput是本次变更的核心类型定义于 Schema.tsexport type FilterOutput undefined | boolean | FilterIssue | ReadonlyArrayFilterIssue谓词返回的每一种形态都会在解析前被归一化为SchemaIssue.Issue或undefined表示成功再挂接到解析结果上。归一化逻辑集中在 SchemaIssue.ts 的normalizeFilterOutput中export function normalizeFilterOutput( ast: SchemaAST.AST, out: Schema.FilterOutput, input?: unknown, options?: SchemaAST.ParseOptions ): Issue | undefined { if (Array.isArray(out)) { if (!Arr.isReadonlyArrayNonEmpty(out)) { return undefined } return out.length 1 ? makeFilterIssue(out[0], input, options) : new Composite(ast, Arr.map(out, (entry) makeFilterIssue(entry, input, options)), input, options) } return makeSingle(out as undefined | boolean | Schema.FilterIssue, input, options) }此外makeFilter还接受两个可选参数annotations用于为过滤器本身附加注解默认格式化器渲染失败信息时优先使用message其次是expected两者都没有时才回退到filterabort为true时该过滤器失败后会立即中止解析不再继续收集后续校验的失败。单一失败形态undefined、布尔值与FilterIssueFilterOutput中“单个失败”的分支保持向后兼容按 Schema.ts 的文档说明undefined校验成功输入通过过滤器true等价于undefined在谓词是纯布尔表达式时更直观false通用失败产生一个无自定义消息的InvalidValue并遵循reportInput选项FilterIssue单个失败条目具体形态见下一节。这些分支在makeSingleSchemaIssue.ts中处理undefined直接返回成功布尔值true成功、false生成无消息的InvalidValue其余情况交给makeFilterIssue展开。新增类型FilterIssue三种可返回的失败条目FilterIssue是本次改动引入的新公开类型定义于 Schema.tsexport type FilterIssue string | SchemaIssue.Issue | { readonly path: ReadonlyArrayPropertyKey readonly issue: string | SchemaIssue.Issue }三种形态分别对应string以该字符串为消息的失败。底层生成SchemaIssue.InvalidValue字符串作为 issue 的message注解且遵循reportInputSchemaIssue.Issue直接返回一个已完整构造的 issue原样透传不因reportInput启用而被额外丰富{ path, issue }把失败挂到指定嵌套路径下issue既可以是消息字符串包装为遵循reportInput的InvalidValue也可以是完整SchemaIssue.Issue原样保留最终整体包装为SchemaIssue.Pointer。FilterIssue同时作为数组分支的元素类型也可以单独作为返回值使用。展开逻辑见makeFilterIssueSchemaIssue.tsfunction makeFilterIssue( entry: Schema.FilterIssue, input?: unknown, options?: SchemaAST.ParseOptions ): Issue { if (isIssue(entry)) { return entry } if (typeof entry string) { return new InvalidValue({ message: entry }, input, options) } const inner typeof entry.issue string ? new InvalidValue({ message: entry.issue }, input, options) : entry.issue return new Pointer(entry.path, inner) }新能力一{ path, issue }——嵌套路径失败免手写Pointer在旧版中若要把失败信息定位到结构体的某个字段谓词只能返回{ path, message: string }且无法携带更细粒度的 issue。本次变更将对象形态改名为{ path, issue }其中issue升级为string | SchemaIssue.Issue当issue是string时行为与旧版message完全一致当issue是完整SchemaIssue.Issue时你可以在嵌套路径上直接挂接一个已构造好的 issue而无需手动构造Pointer——这正是新版本要消除的样板代码。官方文档示例Schema.ts展示了如何在校验“两次密码一致”时把失败定位到password字段import { Result, Schema } from effect const schema Schema.Struct({ password: Schema.String, confirmPassword: Schema.String }).check( Schema.makeFilter((o) o.password o.confirmPassword ? undefined : { path: [password], issue: password and confirmPassword must match } ) ) const result Schema.decodeUnknownResult(schema)({ password: 123456, confirmPassword: 1234567 }) if (Result.isFailure(result) result.failure.issue._tag Filter result.failure.issue.issue._tag Pointer) { result.failure.issue.issue.path // [password] }仓库测试 Schema.test.ts 还验证了issue传完整InvalidValue的场景失败消息为custom issue并自动渲染出at [a]的路径定位行证明Pointer包装确实由框架自动完成。新能力二ReadonlyArrayFilterIssue——多字段校验一次汇总在旧版中跨字段校验如“a、b、c 同时为正数”若要多条失败必须手动 importSchemaIssue并手工构造Composite。新版让谓词直接返回ReadonlyArraySchema.FilterIssue由框架统一处理空数组视为成功等价于undefined单元素数组等价于直接返回该元素不产生多余的包装多元素数组按元素顺序聚合为一个SchemaIssue.CompositeComposite的 AST 取过滤器所在的 schema AST。上述语义在 normalizeFilterOutput 中逐分支实现先判空、再判单元素、最后构造Composite。多失败示例同样记录在 Schema.tsimport { Result, Schema } from effect const schema Schema.Struct({ a: Schema.Finite, b: Schema.Finite, c: Schema.Finite }).check( Schema.makeFilter((o) { const issues: ArraySchema.FilterIssue [] if (o.a 0) { if (o.b 0) issues.push({ path: [b], issue: b must be greater than 0 }) if (o.c 0) issues.push({ path: [c], issue: c must be greater than 0 }) } return issues }) ) const result Schema.decodeUnknownResult(schema)({ a: 1, b: 0, c: 0 }) if (Result.isFailure(result) result.failure.issue._tag Filter result.failure.issue.issue._tag Composite) { result.failure.issue.issue.issues.map((issue) issue._tag Pointer ? issue.path : []) // [[b], [c]] }注意多元素聚合要全部呈现需要解析选项errors: all否则默认的“首个错误即停”策略只会暴露第一条失败。这一前提在测试 Schema.test.ts 中得到印证——该用例显式传入了parseOptions: { errors: all }并断言输出两行error message N与对应的at [a]/at [b]定位。混合形态与测试验证数组分支并不限定元素同质。测试 Schema.test.ts 验证了“字符串、完整 Issue、{ path, issue }三种元素混排”的场景最终输出依次为顶层消息、直通 issue 和带路径定位的消息证明makeFilterIssue对每类元素的分派是独立且可组合的。仓库中针对新老形态的断言覆盖还包括空数组成功L9180-L9186与单元素折叠L9188-L9198两类边界情况可作为理解语义的可靠参照。破坏性变更{ path, message }→{ path, issue }的机械迁移这是本次发布中唯一的破坏性变更对象形态的字段从message改名为issue。凡是旧写法{ path, message }的调用点只需重命名字段即可迁移是机械性的// before Schema.makeFilter((o) ({ path: [a], message: bad })) // after Schema.makeFilter((o) ({ path: [a], issue: bad }))变更集.changeset/pre/expand-schema-filter-output.md将本次改动标记为patch级别并明确说明undefined、true、false、string、SchemaIssue.Issue这些单一失败形态不受影响升级时只需关注对象形态调用点。同步改动SchemaGetter.checkEffect的返回类型同一变更还波及了SchemaGetter.checkEffectSchemaGetter.ts其接受的校验结果中{ path, message }同样更名为{ path, issue }。该方法用于创建“效应式”校验 getter可异步、可依赖 Effect 服务仅当输入为Some时执行返回undefined/true表示通过false/string/Issue/{ path, issue }表示失败且不会转换值本身。其实现复用SchemaIssue.makeSingle完成归一化const issue SchemaIssue.makeSingle(out, t, options) return issue ? Effect.fail(issue) : Effect.succeed(Option.some(t))官方示例SchemaGetter.ts演示了checkEffect配合Effect.succeed实现“非负校验”的最小写法若需要嵌套路径同样返回{ path, issue }即可获得与makeFilter一致的定位渲染。小结本次 Schema 过滤器输出扩展本质上是把“失败报告”的构造责任从调用方移交给框架新增Schema.FilterIssue联合类型统一了string、完整Issue与{ path, issue }三种失败条目FilterOutput新增数组分支空数组为成功、单元素折叠、多元素自动聚合为Composite跨字段校验不再需要手写SchemaIssue对象形态message→issue的破坏性变更属于机械迁移checkEffect同步改名单一失败形态全部保持兼容。实际升级时建议按变更集说明先全局检索{ path, message }写法完成字段重命名再对多字段校验场景尝试返回ArrayFilterIssue配合errors: all解析选项即可获得更完整、更易于定位的校验错误输出。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考