错误格式化器

在使用Effect Schema时，解码或编码操作期间遇到的错误可以使用两种内置方法进行格式化：TreeFormatter和ArrayFormatter。这些格式化器有助于以可读和可操作的方式构建和呈现错误。

TreeFormatter（默认）

TreeFormatter是格式化错误的默认方法。它以树状结构组织错误，提供清晰的问题层次结构。

示例（解码缺失属性）

import { Either, Schema, ParseResult } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

const decode = Schema.decodeUnknownEither(Person)

const result = decode({})
if (Either.isLeft(result)) {
  console.error("解码失败:")
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
}
/*
解码失败:
{ readonly name: string; readonly age: number }
└─ ["name"]
   └─ is missing
*/

在此示例中：

• { readonly name: string; readonly age: number }描述了模式的预期结构。
• ["name"]标识导致错误的特定字段。
• is missing解释了"name"字段的问题。

自定义输出

您可以通过使用identifier、title或description等注解来注释模式，使错误输出更加简洁和有意义。这些注解会替换错误消息中默认的TypeScript样式表示。

示例（使用title注解提高清晰度）

添加title注解会将错误消息中的模式结构替换为更易于理解的”Person”，使其更容易理解。

import { Either, Schema, ParseResult } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
}).annotations({ title: "Person" }) // 添加title注解

const result = Schema.decodeUnknownEither(Person)({})
if (Either.isLeft(result)) {
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
}
/*
Person
└─ ["name"]
   └─ is missing
*/

处理多个错误

默认情况下，像Schema.decodeUnknownEither这样的解码函数只报告第一个错误。要列出所有错误，请使用{ errors: "all" }选项。

示例（列出所有错误）

import { Either, Schema, ParseResult } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

const decode = Schema.decodeUnknownEither(Person, { errors: "all" })

const result = decode({})
if (Either.isLeft(result)) {
  console.error("解码失败:")
  console.error(ParseResult.TreeFormatter.formatErrorSync(result.left))
}
/*
解码失败:
{ readonly name: string; readonly age: number }
├─ ["name"]
│  └─ is missing
└─ ["age"]
   └─ is missing
*/

ParseIssueTitle注解

parseIssueTitle注解允许您通过基于正在验证的值生成标题来为错误消息添加动态上下文。例如，它可以包含来自验证对象的ID，使在复杂或嵌套数据结构中更容易识别特定问题。

注解类型

export type ParseIssueTitleAnnotation = (
  issue: ParseIssue
) => string | undefined

返回值：

• 如果函数返回string，TreeFormatter将其用作标题，除非存在message注解（优先级更高）。
• 如果函数返回undefined，TreeFormatter根据以下优先级确定标题：
  1. identifier注解
  2. title注解
  3. description注解
  4. 默认的TypeScript样式模式表示

示例（使用parseIssueTitle的动态标题）

import type { ParseResult } from "effect"
import { Schema } from "effect"

// 为OrderItem问题生成标题的函数
const getOrderItemId = ({ actual }: ParseResult.ParseIssue) => {
  if (Schema.is(Schema.Struct({ id: Schema.String }))(actual)) {
    return `OrderItem with id: ${actual.id}`
  }
}

const OrderItem = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  price: Schema.Number
}).annotations({
  identifier: "OrderItem",
  parseIssueTitle: getOrderItemId
})

// 为Order问题生成标题的函数
const getOrderId = ({ actual }: ParseResult.ParseIssue) => {
  if (Schema.is(Schema.Struct({ id: Schema.Number }))(actual)) {
    return `Order with id: ${actual.id}`
  }
}

const Order = Schema.Struct({
  id: Schema.Number,
  name: Schema.String,
  items: Schema.Array(OrderItem)
}).annotations({
  identifier: "Order",
  parseIssueTitle: getOrderId
})

const decode = Schema.decodeUnknownSync(Order, { errors: "all" })

// 情况1：没有可用的id，使用`identifier`注解
decode({})
/*
throws
ParseError: Order
├─ ["id"]
│  └─ is missing
├─ ["name"]
│  └─ is missing
└─ ["items"]
   └─ is missing
*/

// 情况2：存在ID，使用动态`parseIssueTitle`注解
decode({ id: 1 })
/*
throws
ParseError: Order with id: 1
├─ ["name"]
│  └─ is missing
└─ ["items"]
   └─ is missing
*/

// 情况3：Order和OrderItem都有ID的嵌套问题
decode({ id: 1, items: [{ id: "22b", price: "100" }] })
/*
throws
ParseError: Order with id: 1
├─ ["name"]
│  └─ is missing
└─ ["items"]
   └─ ReadonlyArray<OrderItem>
      └─ [0]
         └─ OrderItem with id: 22b
            ├─ ["name"]
            │  └─ is missing
            └─ ["price"]
               └─ Expected a number, actual "100"
*/

ArrayFormatter

ArrayFormatter提供了一种结构化的、基于数组的错误格式化方法。它将每个错误表示为一个对象，使在数据解码或编码期间更容易分析和解决多个问题。每个错误对象包括_tag、path和message等属性以提高清晰度。

示例（数组格式的单个错误）

import { Either, Schema, ParseResult } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

const decode = Schema.decodeUnknownEither(Person)

const result = decode({})
if (Either.isLeft(result)) {
  console.error("解码失败:")
  console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left))
}
/*
解码失败:
[ { _tag: 'Missing', path: [ 'name' ], message: 'is missing' } ]
*/

在此示例中：

• _tag：指示错误类型（Missing）。
• path：指定数据中错误的位置（['name']）。
• message：描述问题（'is missing'）。

处理多个错误

默认情况下，像Schema.decodeUnknownEither这样的解码函数只报告第一个错误。要列出所有错误，请使用{ errors: "all" }选项。

示例（列出所有错误）

import { Either, Schema, ParseResult } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

const decode = Schema.decodeUnknownEither(Person, { errors: "all" })

const result = decode({})
if (Either.isLeft(result)) {
  console.error("解码失败:")
  console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left))
}
/*
解码失败:
[
  { _tag: 'Missing', path: [ 'name' ], message: 'is missing' },
  { _tag: 'Missing', path: [ 'age' ], message: 'is missing' }
]
*/

React Hook Form

如果您正在使用React并需要表单验证，@hookform/resolvers为effect/Schema提供了适配器，可以与React Hook Form集成以增强表单验证过程。这种集成允许您在React应用程序中利用effect/Schema的强大功能。

有关如何使用@hookform/resolvers将effect/Schema与React Hook Form集成的更详细说明和示例，您可以访问官方npm包页面： React Hook Form Resolvers