配置

配置是任何云原生应用程序的重要方面。Effect通过为配置提供者提供便捷的接口来简化配置管理过程。

Effect中的配置前端使生态系统库和应用程序能够以声明性方式指定其配置要求。它将复杂的任务卸载给ConfigProvider，该提供者可以由第三方库提供。

Effect捆绑了一个简单的默认ConfigProvider，它从环境变量中检索配置数据。此默认提供者可在开发期间使用，或作为过渡到更高级配置提供者之前的起点。

要使我们的应用程序可配置，我们需要理解三个基本要素：

• 配置描述：我们使用Config<A>的实例来描述配置数据。如果配置数据很简单，例如string、number或boolean，我们可以使用Config模块提供的内置函数。对于更复杂的数据类型，如HostPort，我们可以组合原始配置来创建自定义配置描述。

• 配置前端：我们利用Config<A>的实例来加载实例描述的配置数据（Config本身就是一个效果）。此过程利用当前的ConfigProvider来检索配置。

• 配置后端：ConfigProvider作为管理配置加载过程的底层引擎。Effect作为其默认服务的一部分带有默认配置提供者。此默认提供者从环境变量中读取配置数据。如果我们想使用自定义配置提供者，我们可以利用Effect.withConfigProvider API来相应地配置Effect运行时。

基本配置类型

Effect为配置值提供了几种内置类型，您可以直接使用：

类型	描述
string	将配置值读取为字符串。
number	将值读取为浮点数。
boolean	将值读取为布尔值（true或false）。
integer	将值读取为整数。
date	将值解析为Date对象。
literal	读取固定字面量（*）。
logLevel	将值读取为LogLevel。
duration	将值解析为时间持续时间。
redacted	读取敏感值，确保在记录时受到保护。
url	将值解析为有效的URL。

(*) string | number | boolean | null | bigint

示例（加载环境变量）

以下是使用环境变量加载HOST和PORT基本配置的示例：

primitives.ts

import { Effect, Config } from "effect"

// 定义一个加载HOST和PORT配置的程序
const program = Effect.gen(function* () {
  const host = yield* Config.string("HOST") // 读取为字符串
  const port = yield* Config.number("PORT") // 读取为数字

  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(program)

如果您在未设置所需环境变量的情况下运行此程序：

npx tsx primitives.ts

您将看到指示缺少配置的错误：

[Error: (Missing data at HOST: "Expected HOST to exist in the process context")] {
  name: '(FiberFailure) Error',
  [Symbol(effect/Runtime/FiberFailure)]: Symbol(effect/Runtime/FiberFailure),
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
    _tag: 'Fail',
    error: {
      _op: 'MissingData',
      path: [ 'HOST' ],
      message: 'Expected HOST to exist in the process context'
    }
  }
}

要成功运行程序，请按如下所示设置环境变量：

HOST=localhost PORT=8080 npx tsx primitives.ts

输出：

Application started: localhost:8080

使用Schema配置

您可以使用schema定义和解码配置值。

示例（解码配置值）

import { Effect, Schema } from "effect"

// 定义一个期望至少4个字符的字符串的配置
const myConfig = Schema.Config(
  "Foo",
  Schema.String.pipe(Schema.minLength(4))
)

有关更多信息，请参阅Schema.Config文档。

提供默认值

有时，您可能遇到环境变量缺失的情况，导致配置不完整。为了解决这个问题，Effect提供了Config.withDefault函数，允许您指定默认值。这种回退机制确保即使未设置所需的环境变量，您的应用程序也能继续运行。

示例（使用默认值）

defaults.ts

import { Effect, Config } from "effect"

const program = Effect.gen(function* () {
  const host = yield* Config.string("HOST")
  // 如果未设置PORT，则使用默认值8080
  const port = yield* Config.number("PORT").pipe(Config.withDefault(8080))
  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(program)

仅设置HOST环境变量运行此程序：

HOST=localhost npx tsx defaults.ts

产生以下输出：

Application started: localhost:8080

在这种情况下，即使未设置PORT环境变量，程序仍继续运行，使用端口的默认值8080。这确保应用程序保持功能性，而无需明确提供每个配置。

处理敏感值

某些配置值（如API密钥）不应在日志中打印。

Config.redacted函数用于安全处理敏感信息。 它解析配置值并将其包装在Redacted<string>中，这是一个专门设计用于保护机密的数据类型。

当您使用console.log记录Redacted值时，实际内容保持隐藏，提供额外的安全层。要访问真实值，您必须显式使用Redacted.value。

示例（保护敏感数据）

redacted.ts

import { Effect, Config, Redacted } from "effect"

const program = Effect.gen(function* () {
  //      ┌─── Redacted<string>
  //      ▼
  const redacted = yield* Config.redacted("API_KEY")

  // 记录脱敏值，不会泄露实际机密
  console.log(`Console output: ${redacted}`)

  // 使用Redacted.value访问真实值并记录它
  console.log(`Actual value: ${Redacted.value(redacted)}`)
})

Effect.runPromise(program)

当执行此程序时：

API_KEY=my-api-key tsx redacted.ts

输出将如下所示：

Console output: <redacted>
Actual value: my-api-key

如所示，当使用console.log记录Redacted值时，输出为<redacted>，确保敏感数据保持隐藏。但是，通过使用Redacted.value，可以访问和显示真实值（"my-api-key"），提供对机密的受控访问。

使用Redacted包装配置

默认情况下，当您将字符串传递给Config.redacted时，它返回Redacted<string>。您也可以传递Config（如Config.number）以确保只接受经过验证的值。这通过确保敏感数据在脱敏之前得到适当验证来增加额外的安全层。

示例（脱敏和验证数字）

import { Effect, Config, Redacted } from "effect"

const program = Effect.gen(function* () {
  // 使用脱敏包装经过验证的数字配置
  //
  //      ┌─── Redacted<number>
  //      ▼
  const redacted = yield* Config.redacted(Config.number("SECRET"))

  console.log(`Console output: ${redacted}`)
  console.log(`Actual value: ${Redacted.value(redacted)}`)
})

Effect.runPromise(program)

组合配置

Effect提供了几个内置组合器，允许您定义和操作配置。 这些组合器接受Config作为输入并产生另一个Config，从而实现更复杂的配置结构。

组合器	描述
array	为值数组构造配置。
chunk	为值序列构造配置。
option	返回可选配置。如果数据缺失，结果将是None；否则，将是Some。
repeat	描述值序列，每个值都遵循给定配置的结构。
hashSet	为值集合构造配置。
hashMap	为键值映射构造配置。

此外，还有三个用于特定用例的特殊组合器：

组合器	描述
succeed	构造包含预定义值的配置。
fail	构造使用指定错误消息失败的配置。
all	将多个配置组合成元组、结构或参数列表。

示例（使用array组合器）

以下示例演示如何使用Config.array构造函数将环境变量加载为字符串数组。

index.ts

import { Config, Effect } from "effect"

const program = Effect.gen(function* () {
  const config = yield* Config.array(Config.string(), "MYARRAY")
  console.log(config)
})

Effect.runPromise(program)
// Run:
// MYARRAY=a,b,c,a npx tsx index.ts
// Output:
// [ 'a', 'b', 'c', 'a' ]

示例（使用hashSet组合器）

index.ts

import { Config, Effect } from "effect"

const program = Effect.gen(function* () {
  const config = yield* Config.hashSet(Config.string(), "MYSET")
  console.log(config)
})

Effect.runPromise(program)
// Run:
// MYSET=a,"b c",d,a npx tsx index.ts
// Output:
// { _id: 'HashSet', values: [ 'd', 'a', 'b c' ] }

示例（使用hashMap组合器）

index.ts

import { Config, Effect } from "effect"

const program = Effect.gen(function* () {
  const config = yield* Config.hashMap(Config.string(), "MYMAP")
  console.log(config)
})

Effect.runPromise(program)
// Run:
// MYMAP_A=a MYMAP_B=b npx tsx index.ts
// Output:
// { _id: 'HashMap', values: [ [ 'A', 'a' ], [ 'B', 'b' ] ] }

操作符

Effect提供了几个内置操作符来处理配置，允许您根据需要操作和转换它们。

转换操作符

这些操作符使您能够修改配置或验证其值：

操作符	描述
validate	确保配置满足某些条件，如果不满足则返回验证错误。
map	使用提供的函数转换配置的值。
mapAttempt	类似于map，但捕获函数抛出的任何错误并将其转换为验证错误。
mapOrFail	类似于map，但函数可能失败。如果失败，结果是验证错误。

示例（使用validate操作符）

validate.ts

import { Effect, Config } from "effect"

const program = Effect.gen(function* () {
  // 加载NAME环境变量并验证其长度
  const config = yield* Config.string("NAME").pipe(
    Config.validate({
      message: "Expected a string at least 4 characters long",
      validation: (s) => s.length >= 4
    })
  )
  console.log(config)
})

Effect.runPromise(program)

如果我们使用无效的NAME值运行此程序：

NAME=foo npx tsx validate.ts

输出将是：

[Error: (Invalid data at NAME: "Expected a string at least 4 characters long")] {
  name: '(FiberFailure) Error',
  [Symbol(effect/Runtime/FiberFailure)]: Symbol(effect/Runtime/FiberFailure),
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
    _tag: 'Fail',
    error: {
      _op: 'InvalidData',
      path: [ 'NAME' ],
      message: 'Expected a string at least 4 characters long'
    }
  }
}

回退操作符

当您想要在出现错误或数据缺失时提供替代配置时，回退操作符很有用。这些操作符确保即使某些配置值不可用，您的程序仍能运行。

操作符	描述
orElse	首先尝试使用主配置。如果失败或缺失，则回退到另一个配置。
orElseIf	类似于orElse，但仅在错误匹配条件时才切换到回退配置。

示例（使用orElse进行回退）

在此示例中，程序需要两个配置值：A和B。我们设置了两个配置提供者，每个都只包含所需值中的一个。使用orElse操作符，我们组合这些提供者，以便程序可以检索A和B。

orElse.ts

import { Config, ConfigProvider, Effect } from "effect"

// 需要两个配置的程序：A和B
const program = Effect.gen(function* () {
  const A = yield* Config.string("A") // 检索配置A
  const B = yield* Config.string("B") // 检索配置B
  console.log(`A: ${A}, B: ${B}`)
})

// 第一个提供者有A但缺少B
const provider1 = ConfigProvider.fromMap(new Map([["A", "A"]]))

// 第二个提供者有B但缺少A
const provider2 = ConfigProvider.fromMap(new Map([["B", "B"]]))

// 使用`orElse`从provider1回退到provider2
const provider = provider1.pipe(ConfigProvider.orElse(() => provider2))

Effect.runPromise(Effect.withConfigProvider(program, provider))

如果我们运行此程序：

npx tsx orElse.ts

输出将是：

A: A, B: B

Tip

在此示例中，我们使用ConfigProvider.fromMap从简单的JavaScript Map创建配置提供者。这对于测试特别有用，如在测试中模拟配置部分所述。

自定义配置类型

Effect允许您通过使用组合器和操作符组合原始配置来为自定义类型定义配置。

例如，让我们创建一个HostPort类，它有两个字段：host和port。

class HostPort {
  constructor(readonly host: string, readonly port: number) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

要为此自定义类型定义配置，我们可以组合string和number的原始配置：

示例（定义自定义配置）

import { Config } from "effect"

class HostPort {
  constructor(readonly host: string, readonly port: number) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

// 组合'HOST'和'PORT'的配置
const both = Config.all([Config.string("HOST"), Config.number("PORT")])

// 将配置值映射到HostPort实例
const config = Config.map(
  both,
  ([host, port]) => new HostPort(host, port)
)

在此示例中，Config.all(configs)将两个原始配置Config<string>和Config<number>组合成Config<[string, number]>。然后使用Config.map操作符将这些值转换为HostPort类的实例。

示例（使用自定义配置）

App.ts

import { Effect, Config } from "effect"

class HostPort {
  constructor(readonly host: string, readonly port: number) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

// Combine the configuration for 'HOST' and 'PORT'
const both = Config.all([Config.string("HOST"), Config.number("PORT")])

// Map the configuration values into a HostPort instance
const config = Config.map(
  both,
  ([host, port]) => new HostPort(host, port)
)

// 读取配置并启动应用程序的主程序
const program = Effect.gen(function* () {
  const hostPort = yield* config
  console.log(`Application started: ${hostPort.url}`)
})

Effect.runPromise(program)

当您运行此程序时，它将尝试从环境变量中检索HOST和PORT的值：

HOST=localhost PORT=8080 npx tsx App.ts

如果成功，它将打印：

Application started: localhost:8080

嵌套配置

我们已经看到如何在顶层定义配置，无论是原始类型还是自定义类型。但在某些情况下，您可能希望以更嵌套的方式构造配置，将它们组织在公共命名空间下以提高清晰度和可管理性。

例如，考虑以下ServiceConfig类型：

class ServiceConfig {
  constructor(
    readonly host: string,
    readonly port: number,
    readonly timeout: number
  ) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

如果您在应用程序中使用此配置，它将期望在顶层有HOST、PORT和TIMEOUT环境变量。但在许多情况下，您可能希望在共享命名空间下组织配置——例如，将HOST和PORT分组在SERVER命名空间下，同时将TIMEOUT保留在根目录。

为此，您可以使用Config.nested操作符，它允许您在特定命名空间下嵌套配置值。让我们更新前面的示例以反映这一点：

import { Config } from "effect"

class ServiceConfig {
  constructor(
    readonly host: string,
    readonly port: number,
    readonly timeout: number
  ) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

const serverConfig = Config.all([
  Config.string("HOST"),
  Config.number("PORT")
])

const serviceConfig = Config.map(
  Config.all([
    // 从'SERVER'命名空间读取'HOST'和'PORT'
    Config.nested(serverConfig, "SERVER"),
    // 从根命名空间读取'TIMEOUT'
    Config.number("TIMEOUT")
  ]),
  ([[host, port], timeout]) => new ServiceConfig(host, port, timeout)
)

现在，如果您使用此配置设置运行应用程序，它将查找以下环境变量：

• SERVER_HOST用于主机值
• SERVER_PORT用于端口值
• TIMEOUT用于超时值

这种结构化方法使您的配置更有组织，特别是在处理多个服务或复杂应用程序时。

在测试中模拟配置

在测试服务时，有时您需要为测试提供特定的配置。为了模拟这种情况，模拟读取这些值的配置后端很有用。

您可以使用ConfigProvider.fromMap构造函数来实现这一点。 此方法允许您从Map<string, string>创建配置提供者，其中映射表示配置数据。 然后，您可以通过调用Effect.withConfigProvider使用此模拟提供者来替代默认提供者。

示例（为测试模拟配置提供者）

import { Config, ConfigProvider, Effect } from "effect"

class HostPort {
  constructor(readonly host: string, readonly port: number) {}
  get url() {
    return `${this.host}:${this.port}`
  }
}

const config = Config.map(
  Config.all([Config.string("HOST"), Config.number("PORT")]),
  ([host, port]) => new HostPort(host, port)
)

const program = Effect.gen(function* () {
  const hostPort = yield* config
  console.log(`Application started: ${hostPort.url}`)
})

// 使用包含测试数据的映射创建模拟配置提供者
const mockConfigProvider = ConfigProvider.fromMap(
  new Map([
    ["HOST", "localhost"],
    ["PORT", "8080"]
  ])
)

// 使用模拟配置提供者运行程序
Effect.runPromise(Effect.withConfigProvider(program, mockConfigProvider))
// Output: Application started: localhost:8080

这种方法帮助您创建不依赖外部环境变量的隔离测试，确保您的测试使用模拟配置一致地运行。

处理嵌套配置值

对于更复杂的设置，配置通常包括嵌套键。默认情况下，ConfigProvider.fromMap使用.作为嵌套键的分隔符。

示例（提供嵌套配置值）

import { Config, ConfigProvider, Effect } from "effect"

const config = Config.nested(Config.number("PORT"), "SERVER")

const program = Effect.gen(function* () {
  const port = yield* config
  console.log(`Server is running on port ${port}`)
})

// 使用'.'作为嵌套键分隔符的模拟配置
const mockConfigProvider = ConfigProvider.fromMap(
  new Map([["SERVER.PORT", "8080"]])
)

Effect.runPromise(Effect.withConfigProvider(program, mockConfigProvider))
// Output: Server is running on port 8080

自定义路径分隔符

如果您的配置数据使用不同的分隔符（如_），您可以使用ConfigProvider.fromMap中的pathDelim选项更改分隔符。

示例（使用自定义路径分隔符）

import { Config, ConfigProvider, Effect } from "effect"

const config = Config.nested(Config.number("PORT"), "SERVER")

const program = Effect.gen(function* () {
  const port = yield* config
  console.log(`Server is running on port ${port}`)
})

// 使用'_'作为分隔符的模拟配置
const mockConfigProvider = ConfigProvider.fromMap(
  new Map([["SERVER_PORT", "8080"]]),
  { pathDelim: "_" }
)

Effect.runPromise(Effect.withConfigProvider(program, mockConfigProvider))
// Output: Server is running on port 8080

ConfigProvider

Effect中的ConfigProvider模块允许应用程序从不同来源加载配置值。 默认提供者从环境变量读取，但您可以在需要时自定义其行为。

从环境变量加载配置

ConfigProvider.fromEnv函数创建一个从环境变量加载值的ConfigProvider。这是Effect使用的默认提供者，除非指定了另一个。

如果您的应用程序需要嵌套配置键的自定义分隔符，您可以相应地配置ConfigProvider.fromEnv。

示例（更改路径分隔符）

以下示例修改环境变量的路径分隔符（"__"）和序列分隔符（"|"）。

index.ts

import { Config, ConfigProvider, Effect } from "effect"

const program = Effect.gen(function* () {
  // 将SERVER_HOST和SERVER_PORT读取为嵌套配置值
  const port = yield* Config.nested(Config.number("PORT"), "SERVER")
  const host = yield* Config.nested(Config.string("HOST"), "SERVER")
  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(
  Effect.withConfigProvider(
    program,
    // 自定义分隔符
    ConfigProvider.fromEnv({ pathDelim: "__", seqDelim: "|" })
  )
)

要匹配自定义分隔符（"__"），请像这样设置环境变量：

SERVER__HOST=localhost SERVER__PORT=8080 npx tsx index.ts

输出：

Application started: localhost:8080

从JSON加载配置

ConfigProvider.fromJson函数创建一个从JSON对象加载值的ConfigProvider。

示例（从JSON读取嵌套配置）

import { Config, ConfigProvider, Effect } from "effect"

const program = Effect.gen(function* () {
  // 将SERVER_HOST和SERVER_PORT读取为嵌套配置值
  const port = yield* Config.nested(Config.number("PORT"), "SERVER")
  const host = yield* Config.nested(Config.string("HOST"), "SERVER")
  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(
  Effect.withConfigProvider(
    program,
    ConfigProvider.fromJson(
      JSON.parse(`{"SERVER":{"PORT":8080,"HOST":"localhost"}}`)
    )
  )
)
// Output: Application started: localhost:8080

使用嵌套配置命名空间

ConfigProvider.nested函数允许在命名空间下分组配置值。 这在逻辑上构造设置时很有帮助，例如分组SERVER相关的值。

示例（使用嵌套命名空间）

index.ts

import { Config, ConfigProvider, Effect } from "effect"

const program = Effect.gen(function* () {
  const port = yield* Config.number("PORT") // 读取SERVER_PORT
  const host = yield* Config.string("HOST") // 读取SERVER_HOST
  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(
  Effect.withConfigProvider(
    program,
    ConfigProvider.fromEnv().pipe(
      // 使用SERVER作为命名空间
      ConfigProvider.nested("SERVER")
    )
  )
)

由于我们将"SERVER"定义为命名空间，环境变量必须遵循此模式：

SERVER_HOST=localhost SERVER_PORT=8080 npx tsx index.ts

输出：

Application started: localhost:8080

将配置键转换为常量大小写

ConfigProvider.constantCase函数将所有配置键转换为常量大小写（带下划线的大写）。 这在调整环境变量以匹配不同命名约定时很有用。

示例（为环境变量使用constantCase）

index.ts

import { Config, ConfigProvider, Effect } from "effect"

const program = Effect.gen(function* () {
  const port = yield* Config.number("Port") // 读取PORT
  const host = yield* Config.string("Host") // 读取HOST
  console.log(`Application started: ${host}:${port}`)
})

Effect.runPromise(
  Effect.withConfigProvider(
    program,
    // 将键转换为常量大小写
    ConfigProvider.fromEnv().pipe(ConfigProvider.constantCase)
  )
)

由于constantCase将"Port" → "PORT"和"Host" → "HOST"转换，环境变量必须按如下设置：

HOST=localhost PORT=8080 npx tsx index.ts

输出：

Application started: localhost:8080

弃用

Secret 已弃用

自版本3.3.0起弃用：请使用Config.redacted来处理敏感信息。

Config.secret函数以前用于以类似于Config.redacted的方式保护敏感信息。它将配置值包装在Secret类型中，该类型在记录时也会隐藏详细信息，但允许通过Secret.value访问。

示例（使用已弃用的Config.secret）

secret.ts

import { Effect, Config, Secret } from "effect"

const program = Effect.gen(function* () {
  const secret = yield* Config.secret("API_KEY")

  // 记录机密值，不会泄露实际机密
  console.log(`Console output: ${secret}`)

  // 使用Secret.value访问真实值并记录它
  console.log(`Actual value: ${Secret.value(secret)}`)
})

Effect.runPromise(program)

当执行此程序时：

API_KEY=my-api-key tsx secret.ts

输出将如下所示：

Console output: Secret(<redacted>)
Actual value: my-api-key