回退

本页面解释了在 Effect 库中处理失败和创建回退机制的各种技术。

orElse

Effect.orElse 允许您尝试运行一个 Effect，如果它失败，您 可以提供一个回退 Effect 来代替运行。

这对于通过定义在第一个 Effect 遇到错误时执行的替代 Effect 来优雅地处理失败很有用。

示例（使用 Effect.orElse 处理回退）

import { Effect } from "effect"

const success = Effect.succeed("success")
const failure = Effect.fail("failure")
const fallback = Effect.succeed("fallback")

// 首先尝试成功的 Effect，不使用回退
const program1 = Effect.orElse(success, () => fallback)
console.log(Effect.runSync(program1))
// 输出："success"

// 首先尝试失败的 Effect，使用回退
const program2 = Effect.orElse(failure, () => fallback)
console.log(Effect.runSync(program2))
// 输出："fallback"

orElseFail

Effect.orElseFail 允许您用自定义失败值替换一个 Effect 的失败。如果 Effect 失败，您可以提供一个新的失败来代替原始失败返回。

此函数仅适用于失败的 Effect。如果 Effect 成功，它将保持不受影响。

示例（使用 Effect.orElseFail 替换失败）

import { Effect } from "effect"

const validate = (age: number): Effect.Effect<number, string> => {
  if (age < 0) {
    return Effect.fail("NegativeAgeError")
  } else if (age < 18) {
    return Effect.fail("IllegalAgeError")
  } else {
    return Effect.succeed(age)
  }
}

const program = Effect.orElseFail(validate(-1), () => "invalid age")

console.log(Effect.runSyncExit(program))
/*
Output:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'invalid age' }
}
*/

orElseSucceed

Effect.orElseSucceed 允许您用成功值替换 Effect 的失败。如果 Effect 失败，它将改为使用提供的值成功，确保 Effect 始终成功完成。

当您想要保证成功结果而不管原始 Effect 是否失败时，这很有用。

该函数确保任何失败都被有效地”吞没”并被成功值替换，这对于在失败情况下提供默认值很有帮助。

此函数仅适用于失败的 Effect。如果 Effect 已经成功，它将保持不变。

示例（使用 Effect.orElseSucceed 用成功替换失败）

import { Effect } from "effect"

const validate = (age: number): Effect.Effect<number, string> => {
  if (age < 0) {
    return Effect.fail("NegativeAgeError")
  } else if (age < 18) {
    return Effect.fail("IllegalAgeError")
  } else {
    return Effect.succeed(age)
  }
}

const program = Effect.orElseSucceed(validate(-1), () => 18)

console.log(Effect.runSyncExit(program))
/*
Output:
{ _id: 'Exit', _tag: 'Success', value: 18 }
*/

firstSuccessOf

Effect.firstSuccessOf 允许您按顺序尝试多个 Effect，一旦其中一个成功，它就返回该结果。如果所有 Effect 都失败，它返回列表中最后一个 Effect 的错误。

当您有几个潜在的替代方案并想要使用第一个有效的方案时，这很有用。

此函数是顺序的，意味着可迭代对象中的 Effect 值将按顺序执行，第一个成功的将决定结果 Effect 值的结果。

空集合错误

如果提供给 Effect.firstSuccessOf 函数的集合为空，它将抛出 IllegalArgumentException 错误。

示例（使用回退查找配置）

在这个示例中，我们尝试从不同节点检索配置。如果主节点失败，我们回退到其他节点，直到找到成功的配置。

import { Effect, Console } from "effect"

interface Config {
  host: string
  port: number
  apiKey: string
}

// 创建带有示例值的配置对象
const makeConfig = (name: string): Config => ({
  host: `${name}.example.com`,
  port: 8080,
  apiKey: "12345-abcde"
})

// 模拟从远程节点检索配置
const remoteConfig = (name: string): Effect.Effect<Config, Error> =>
  Effect.gen(function* () {
    // 模拟 node3 是唯一有可用配置的节点
    if (name === "node3") {
      yield* Console.log(`Config for ${name} found`)
      return makeConfig(name)
    } else {
      yield* Console.log(`Unavailable config for ${name}`)
      return yield* Effect.fail(new Error(`Config not found for ${name}`))
    }
  })

// 定义主配置和潜在的回退节点
const masterConfig = remoteConfig("master")
const nodeConfigs = ["node1", "node2", "node3", "node4"].map(remoteConfig)

// 尝试找到有效的配置，
// 从主节点开始，然后回退到其他节点
const config = Effect.firstSuccessOf([masterConfig, ...nodeConfigs])

// 运行 Effect 来检索配置
const result = Effect.runSync(config)

console.log(result)
/*
Output:
Unavailable config for master
Unavailable config for node1
Unavailable config for node2
Config for node3 found
{ host: 'node3.example.com', port: 8080, apiKey: '12345-abcde' }
*/