错误消息

默认错误消息

默认情况下，当发生解析错误时，系统会根据模式的结构和错误的性质自动生成信息性消息（有关更多信息，请参阅 TreeFormatter）。 例如，如果缺少必需属性或数据类型不匹配，错误消息将清楚地说明期望与实际输入的对比。

示例（类型不匹配）

import { Schema } from "effect"

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

Schema.decodeUnknownSync(Person)(null)
// 输出：ParseError: Expected { readonly name: string; readonly age: number }, actual null

示例（缺少属性）

import { Schema } from "effect"

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

Schema.decodeUnknownSync(Person)({}, { errors: "all" })
/*
抛出：
ParseError: { readonly name: string; readonly age: number }
├─ ["name"]
│  └─ is missing
└─ ["age"]
   └─ is missing
*/

示例（错误的属性类型）

import { Schema } from "effect"

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

Schema.decodeUnknownSync(Person)(
  { name: null, age: "age" },
  { errors: "all" }
)
/*
抛出：
ParseError: { readonly name: string; readonly age: number }
├─ ["name"]
│  └─ Expected string, actual null
└─ ["age"]
   └─ Expected number, actual "age"
*/

使用标识符增强错误消息的清晰度

在模式具有多个字段或嵌套结构的场景中，默认错误消息可能变得过于复杂和冗长。 为了解决这个问题，您可以通过使用 identifier、title 和 description 等注解来增强这些消息的清晰度和简洁性。

示例（使用标识符提高清晰度）

import { Schema } from "effect"

const Name = Schema.String.annotations({ identifier: "Name" })

const Age = Schema.Number.annotations({ identifier: "Age" })

const Person = Schema.Struct({
  name: Name,
  age: Age
}).annotations({ identifier: "Person" })

Schema.decodeUnknownSync(Person)(null)
/*
抛出：
ParseError: Expected Person, actual null
*/

Schema.decodeUnknownSync(Person)({}, { errors: "all" })
/*
抛出：
ParseError: Person
├─ ["name"]
│  └─ is missing
└─ ["age"]
   └─ is missing
*/

Schema.decodeUnknownSync(Person)(
  { name: null, age: null },
  { errors: "all" }
)
/*
抛出：
ParseError: Person
├─ ["name"]
│  └─ Expected Name, actual null
└─ ["age"]
   └─ Expected Age, actual null
*/

精炼

当精炼失败时，默认错误消息指示失败是发生在”from”部分还是在定义精炼的谓词内：

示例（精炼错误）

import { Schema } from "effect"

const Name = Schema.NonEmptyString.annotations({ identifier: "Name" })

const Age = Schema.Positive.pipe(Schema.int({ identifier: "Age" }))

const Person = Schema.Struct({
  name: Name,
  age: Age
}).annotations({ identifier: "Person" })

// From侧失败
Schema.decodeUnknownSync(Person)({ name: null, age: 18 })
/*
throws:
ParseError: Person
└─ ["name"]
   └─ Name
      └─ From side refinement failure
         └─ Expected string, actual null
*/

// 谓词精炼失败
Schema.decodeUnknownSync(Person)({ name: "", age: 18 })
/*
throws:
ParseError: Person
└─ ["name"]
   └─ Name
      └─ Predicate refinement failure
         └─ Expected a non empty string, actual ""
*/

在第一个示例中，错误消息指示name属性中的”from side”精炼失败，指定期望字符串但收到了null。 在第二个示例中，报告了”predicate”精炼失败，指示name期望非空字符串但提供了空字符串。

转换

不同类型或格式之间的转换偶尔会导致错误。 系统提供结构化的错误消息来指定错误发生的位置：

• 编码侧失败： 此侧的错误通常表示转换的输入与预期的初始类型或格式不匹配。例如，期望string时收到null。
• 转换过程失败： 当转换逻辑本身失败时会出现此类错误，例如当输入不满足转换函数中指定的条件时。
• 类型侧失败： 当转换的输出不满足解码侧的模式要求时发生。如果转换后的值未通过后续验证或条件，就会发生这种情况。

示例（转换错误）

import { ParseResult, Schema } from "effect"

const schema = Schema.transformOrFail(
  Schema.String,
  Schema.String.pipe(Schema.minLength(2)),
  {
    strict: true,
    decode: (s, _, ast) =>
      s.length > 0
        ? ParseResult.succeed(s)
        : ParseResult.fail(new ParseResult.Type(ast, s)),
    encode: ParseResult.succeed
  }
)

// 编码侧失败
Schema.decodeUnknownSync(schema)(null)
/*
throws:
ParseError: (string <-> minLength(2))
└─ Encoded side transformation failure
   └─ Expected string, actual null
*/

// 转换失败
Schema.decodeUnknownSync(schema)("")
/*
throws:
ParseError: (string <-> minLength(2))
└─ Transformation process failure
   └─ Expected (string <-> minLength(2)), actual ""
*/

// 类型侧失败
Schema.decodeUnknownSync(schema)("a")
/*
throws:
ParseError: (string <-> minLength(2))
└─ Type side transformation failure
   └─ minLength(2)
      └─ Predicate refinement failure
         └─ Expected a string at least 2 character(s) long, actual "a"
*/

自定义错误消息

您可以使用message注解为模式的不同部分定义专门定制的自定义错误消息。 这允许开发人员提供更具上下文特定性的反馈，可以改善调试和验证过程。

以下是MessageAnnotation类型的概述，您可以使用它来制作这些消息：

type MessageAnnotation = (issue: ParseIssue) =>
  | string
  | Effect<string>
  | {
      readonly message: string | Effect<string>
      readonly override: boolean
    }

返回类型	描述
string	提供直接描述错误的静态消息。
Effect<string>	利用可以合并同步过程结果或依赖可选依赖项的动态消息。
Object (with message and override)	允许您定义特定的错误消息以及布尔标志（override）。此标志确定自定义消息是否应取代任何默认或嵌套的自定义消息，为显示给用户的错误输出提供精确控制。

示例（为字符串模式添加自定义错误消息）

import { Schema } from "effect"

// 定义没有自定义消息的字符串模式
const MyString = Schema.String

// 尝试解码`null`，导致默认错误消息
Schema.decodeUnknownSync(MyString)(null)
/*
throws:
ParseError: Expected string, actual null
*/

// 定义带有自定义错误消息的字符串模式
const MyStringWithMessage = Schema.String.annotations({
  message: () => "not a string"
})

// 使用自定义模式解码，显示新的错误消息
Schema.decodeUnknownSync(MyStringWithMessage)(null)
/*
throws:
ParseError: not a string
*/

示例（带有覆盖选项的联合模式的自定义错误消息）

import { Schema } from "effect"

// 定义没有自定义消息的联合模式
const MyUnion = Schema.Union(Schema.String, Schema.Number)

// 解码`null`，导致默认联合错误消息
Schema.decodeUnknownSync(MyUnion)(null)
/*
throws:
ParseError: string | number
├─ Expected string, actual null
└─ Expected number, actual null
*/

// 定义带有自定义消息和覆盖标志的联合模式
const MyUnionWithMessage = Schema.Union(
  Schema.String,
  Schema.Number
).annotations({
  message: () => ({
    message: "Please provide a string or a number",
    // 确保此消息替换所有嵌套消息
    override: true
  })
})

// 使用自定义模式解码，显示新的错误消息
Schema.decodeUnknownSync(MyUnionWithMessage)(null)
/*
throws:
ParseError: Please provide a string or a number
*/

消息的一般准则

确定消息遵循的一般逻辑如下：

1. 如果没有设置自定义消息，则使用与操作（即解码或编码）失败的最内层模式相关的默认消息。

2. 如果设置了自定义消息，则使用对应于第一个失败模式的消息，从最内层模式开始到最外层模式。但是，如果失败的模式没有自定义消息，则使用默认消息。

3. 作为可选功能，您可以通过将overwrite标志设置为true来覆盖准则2。这允许自定义消息优先于来自内部模式的所有其他自定义消息。这是为了解决用户想要定义单个累积自定义消息来描述有效值必须具有的属性并且不想看到默认消息的场景。

让我们看一些实际示例。

标量模式

示例（标量模式的简单自定义消息）

import { Schema } from "effect"

const MyString = Schema.String.annotations({
  message: () => "my custom message"
})

const decode = Schema.decodeUnknownSync(MyString)

try {
  decode(null)
} catch (e: any) {
  console.log(e.message) // "my custom message"
}

精炼

此示例演示在精炼链中的最后一个精炼上设置自定义消息。如您所见，只有当与maxLength相关的精炼失败时才使用自定义消息；否则，使用默认消息。

示例（链中最后一个精炼的自定义消息）

import { Schema } from "effect"

const MyString = Schema.String.pipe(
  Schema.minLength(1),
  Schema.maxLength(2)
).annotations({
  // 此消息仅在最后一个过滤器（`maxLength`）失败时显示
  message: () => "my custom message"
})

const decode = Schema.decodeUnknownSync(MyString)

try {
  decode(null)
} catch (e: any) {
  console.log(e.message)
  /*
   minLength(1) & maxLength(2)
   └─ From side refinement failure
      └─ minLength(1)
         └─ From side refinement failure
            └─ Expected string, actual null
  */
}

try {
  decode("")
} catch (e: any) {
  console.log(e.message)
  /*
   minLength(1) & maxLength(2)
   └─ From side refinement failure
      └─ minLength(1)
         └─ Predicate refinement failure
            └─ Expected a string at least 1 character(s) long, actual ""
  */
}

try {
  decode("abc")
} catch (e: any) {
  console.log(e.message)
  // "my custom message"
}

当设置多个自定义消息时，使用对应于第一个失败谓词的消息，从最内层精炼开始到最外层：

示例（多个精炼的自定义消息）

import { Schema } from "effect"

const MyString = Schema.String
  // 此消息仅在传入非字符串输入时显示
  .annotations({ message: () => "String custom message" })
  .pipe(
    // 此消息仅在过滤器`minLength`失败时显示
    Schema.minLength(1, { message: () => "minLength custom message" }),
    // 此消息仅在过滤器`maxLength`失败时显示
    Schema.maxLength(2, { message: () => "maxLength custom message" })
  )

const decode = Schema.decodeUnknownSync(MyString)

try {
  decode(null)
} catch (e: any) {
  console.log(e.message) // String custom message
}

try {
  decode("")
} catch (e: any) {
  console.log(e.message) // minLength custom message
}

try {
  decode("abc")
} catch (e: any) {
  console.log(e.message) // maxLength custom message
}

您可以通过将override标志设置为true来更改默认行为。当您想要创建一个描述有效值所需属性的单一综合自定义消息而不显示默认消息时，这很有用。

示例（覆盖默认消息）

import { Schema } from "effect"

const MyString = Schema.String.pipe(
  Schema.minLength(1),
  Schema.maxLength(2)
).annotations({
  // 通过将`override`标志设置为`true`，此消息将始终为任何错误显示
  message: () => ({ message: "my custom message", override: true })
})

const decode = Schema.decodeUnknownSync(MyString)

try {
  decode(null)
} catch (e: any) {
  console.log(e.message) // my custom message
}

try {
  decode("")
} catch (e: any) {
  console.log(e.message) // my custom message
}

try {
  decode("abc")
} catch (e: any) {
  console.log(e.message) // my custom message
}

转换

在此示例中，IntFromString是一个将字符串转换为整数的转换模式。它根据不同场景应用特定的验证消息。

示例（字符串到整数转换的自定义错误消息）

import { ParseResult, Schema } from "effect"

const IntFromString = Schema.transformOrFail(
  // 此消息仅在输入不是字符串时显示
  Schema.String.annotations({ message: () => "please enter a string" }),
  // 此消息仅在输入可以转换为数字但不是整数时显示
  Schema.Int.annotations({ message: () => "please enter an integer" }),
  {
    strict: true,
    decode: (s, _, ast) => {
      const n = Number(s)
      return Number.isNaN(n)
        ? ParseResult.fail(new ParseResult.Type(ast, s))
        : ParseResult.succeed(n)
    },
    encode: (n) => ParseResult.succeed(String(n))
  }
)
  // 此消息仅在输入无法转换为数字时显示
  .annotations({ message: () => "please enter a parseable string" })

const decode = Schema.decodeUnknownSync(IntFromString)

try {
  decode(null)
} catch (e: any) {
  console.log(e.message) // please enter a string
}

try {
  decode("1.2")
} catch (e: any) {
  console.log(e.message) // please enter an integer
}

try {
  decode("not a number")
} catch (e: any) {
  console.log(e.message) // please enter a parseable string
}

复合模式

与string或number等简单标量值不同，自定义消息系统在处理复杂模式时变得特别有用。例如，考虑一个包含嵌套结构的模式，如包含其他结构数组的结构。让我们探索一个示例，演示默认消息在处理此类嵌套结构中的解码错误时的优势：

示例（嵌套模式中的自定义错误消息）

import { Schema, pipe } from "effect"

const schema = Schema.Struct({
  outcomes: pipe(
    Schema.Array(
      Schema.Struct({
        id: Schema.String,
        text: pipe(
          Schema.String.annotations({
            message: () => "error_invalid_outcome_type"
          }),
          Schema.minLength(1, { message: () => "error_required_field" }),
          Schema.maxLength(50, {
            message: () => "error_max_length_field"
          })
        )
      })
    ),
    Schema.minItems(1, { message: () => "error_min_length_field" })
  )
})

Schema.decodeUnknownSync(schema, { errors: "all" })({
  outcomes: []
})
/*
throws
ParseError: { readonly outcomes: minItems(1) }
└─ ["outcomes"]
   └─ error_min_length_field
*/

Schema.decodeUnknownSync(schema, { errors: "all" })({
  outcomes: [
    { id: "1", text: "" },
    { id: "2", text: "this one is valid" },
    { id: "3", text: "1234567890".repeat(6) }
  ]
})
/*
throws
ParseError: { readonly outcomes: minItems(1) }
└─ ["outcomes"]
   └─ minItems(1)
      └─ From side refinement failure
         └─ ReadonlyArray<{ readonly id: string; readonly text: minLength(1) & maxLength(50) }>
            ├─ [0]
            │  └─ { readonly id: string; readonly text: minLength(1) & maxLength(50) }
            │     └─ ["text"]
            │        └─ error_required_field
            └─ [2]
               └─ { readonly id: string; readonly text: minLength(1) & maxLength(50) }
                  └─ ["text"]
                     └─ error_max_length_field
*/

有效果的消息

错误消息可以通过返回Effect超越简单字符串，允许它们访问依赖项，如国际化服务。这种方法让消息根据外部上下文或服务动态调整。下面是一个说明如何创建基于效果的消息的示例。

示例（带有国际化服务的基于效果的消息）

import {
  Context,
  Effect,
  Either,
  Option,
  Schema,
  ParseResult
} from "effect"

// 为自定义消息定义国际化服务
class Messages extends Context.Tag("Messages")<
  Messages,
  {
    NonEmpty: string
  }
>() {}

// 定义一个带有基于效果的消息的模式
// 该消息依赖于Messages服务
const Name = Schema.NonEmptyString.annotations({
  message: () =>
    Effect.gen(function* () {
      // 尝试检索Messages服务
      const service = yield* Effect.serviceOption(Messages)
      // 如果服务不可用，使用回退消息
      return Option.match(service, {
        onNone: () => "Invalid string",
        onSome: (messages) => messages.NonEmpty
      })
    })
})

// 尝试在不提供Messages服务的情况下解码空字符串
Schema.decodeUnknownEither(Name)("").pipe(
  Either.mapLeft((error) =>
    ParseResult.TreeFormatter.formatError(error).pipe(
      Effect.runSync,
      console.log
    )
  )
)
// Output: Invalid string

// 提供Messages服务以自定义错误消息
Schema.decodeUnknownEither(Name)("").pipe(
  Either.mapLeft((error) =>
    ParseResult.TreeFormatter.formatError(error).pipe(
      Effect.provideService(Messages, {
        NonEmpty: "should be non empty"
      }),
      Effect.runSync,
      console.log
    )
  )
)
// Output: should be non empty

缺失消息

您可以使用missingMessage注解为缺失的字段或元组元素提供自定义消息。

示例（缺失属性的自定义消息）

在此示例中，为Person模式中缺失的name属性定义了自定义消息。

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.propertySignature(Schema.String).annotations({
    // 如果"name"缺失的自定义消息
    missingMessage: () => "Name is required"
  })
})

Schema.decodeUnknownSync(Person)({})
/*
throws:
ParseError: { readonly name: string }
└─ ["name"]
   └─ Name is required
*/

示例（缺失元组元素的自定义消息）

在这里，Point元组模式中的每个元素在元素缺失时都有特定的自定义消息。

import { Schema } from "effect"

const Point = Schema.Tuple(
  Schema.element(Schema.Number).annotations({
    // 如果X缺失的消息
    missingMessage: () => "X coordinate is required"
  }),
  Schema.element(Schema.Number).annotations({
    // 如果Y缺失的消息
    missingMessage: () => "Y coordinate is required"
  })
)

Schema.decodeUnknownSync(Point)([], { errors: "all" })
/*
throws:
ParseError: readonly [number, number]
├─ [0]
│  └─ X coordinate is required
└─ [1]
   └─ Y coordinate is required
*/