管理服务

在编程的上下文中，服务指的是可以被应用程序不同部分使用的可重用组件或功能。 服务旨在提供特定的能力，并且可以在多个模块或组件之间共享。

服务通常封装应用程序不同部分所需的常见任务或操作。 它们可以处理复杂操作、与外部系统或 API 交互、管理数据或执行其他专门任务。

服务通常设计为模块化的，与应用程序的其余部分解耦。 这使得它们可以轻松维护、测试和替换，而不会影响应用程序的整体功能。

在深入研究服务及其在应用程序开发中的集成时，从函数管理和依赖处理的基本原则开始是有帮助的，而不依赖于高级构造。想象一下必须手动将服务传递给每个需要它的函数：

const processData = (data: Data, databaseService: DatabaseService) => {
  // Operations using the database service
}

随着应用程序的增长，这种方法变得繁琐且难以管理，服务需要通过多层函数传递。

为了简化这一点，您可能会考虑使用捆绑各种服务的环境对象：

type Context = {
  databaseService: DatabaseService
  loggingService: LoggingService
}

const processData = (data: Data, context: Context) => {
  // Using multiple services from the context
}

然而，这引入了新的复杂性：您必须确保在使用环境之前正确设置所有必要的服务，这可能导致紧密耦合的代码，并使函数组合和测试变得更加困难。

使用 Effect 管理服务

Effect 库通过利用类型系统简化了这些依赖关系的管理。 不需要手动传递服务或环境对象，Effect 允许您使用 Effect 类型中的 Requirements 参数直接在函数的类型签名中声明服务依赖关系：

                         ┌─── 表示所需的依赖关系
                         ▼
Effect<Success, Error, Requirements>

在使用 Effect 时，它在实践中的工作方式如下：

依赖声明：您直接在函数的类型中指定函数需要哪些服务，将依赖管理的复杂性推入类型系统。

服务提供：Effect.provideService 用于使服务实现对需要它的函数可用。通过在开始时提供服务，您确保应用程序的所有部分都能一致地访问所需的服务，从而维护清洁和解耦的架构。

这种方法抽象了手动服务处理，让开发者专注于业务逻辑，而编译器确保所有依赖关系都得到正确管理。它还使代码更易于维护和扩展。

让我们逐步了解在 Effect 中管理服务：

1. 创建服务：定义具有独特功能和接口的服务。
2. 使用服务：在应用程序的函数中访问和利用服务。
3. 提供服务实现：提供服务的实际实现以满足声明的需求。

工作原理

到目前为止，我们使用 Effect 框架的示例都处理独立于外部服务运行的 effect。 这意味着我们 Effect 类型签名中的 Requirements 参数被设置为 never，表示没有依赖关系。

然而，现实世界的应用程序通常需要依赖特定服务才能正确运行的 effect。这些服务通过称为 Context 的构造进行管理和访问。

Context 作为 effect 可能需要的所有服务的存储库或容器。 它就像一个维护这些服务的存储，允许应用程序的各个部分根据需要访问和使用它们。

存储在 Context 中的服务直接反映在 Effect 类型的 Requirements 参数中。 Context 中的每个服务都由唯一的”标签”标识，这本质上是服务的唯一标识符。

当 effect 需要使用特定服务时，服务的标签包含在 Requirements 类型参数中。

创建服务

要创建新服务，您需要两样东西：

1. 唯一的标识符。
2. 描述服务可能操作的类型。

示例（定义随机数生成器服务）

让我们创建一个用于生成随机数的服务。

1. 标识符。我们将使用字符串 "MyRandomService" 作为唯一标识符。
2. 类型。服务类型将有一个名为 next 的操作，返回一个随机数。

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

导出的 Random 值在 Effect 中被称为标签。它作为服务的表示，允许 Effect 在运行时定位和使用此服务。

服务将存储在名为 Context 的集合中，可以将其视为键为标签、值为服务的 Map：

type Context = Map<Tag, Service>

为什么使用标识符？

您需要指定标识符以使标签全局化。这确保具有相同标识符的两个标签引用同一个实例。

使用唯一标识符在可能发生热重载的场景中特别有用，因为它有助于在重载过程中保持实例。它确保没有实例重复（虽然不应该发生，但某些打包器和框架可能表现不可预测）。

让我们总结一下到目前为止涵盖的概念：

概念	描述
服务	提供特定功能的可重用组件，在应用程序的不同部分中使用。
标签	表示服务的唯一标识符，允许 Effect 定位和使用它。
上下文	存储服务的集合，功能类似于以标签为键、服务为值的映射。

使用服务

现在我们已经定义了服务标签，让我们通过构建一个简单的程序来看看如何使用它。

示例（使用随机数服务）

Using Effect.gen

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

// 使用服务
//
//      ┌─── Effect<void, never, Random>
//      ▼
const program = Effect.gen(function* () {
  const random = yield* Random
  const randomNumber = yield* random.next
  console.log(`random number: ${randomNumber}`)
})

在上面的代码中，我们可以观察到我们能够像 effect 本身一样 yield Random 标签。 这允许我们访问服务的 next 操作。

Using pipe

import { Effect, Context, Console } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

// 使用服务
//
//      ┌─── Effect<void, never, Random>
//      ▼
const program = Random.pipe(
  Effect.andThen((random) => random.next),
  Effect.andThen((randomNumber) =>
    Console.log(`random number: ${randomNumber}`)
  )
)

在上面的代码中，我们可以观察到我们能够像 effect 本身一样对 Random 标签进行 flat-map。 这允许我们在 Effect.andThen 回调中访问服务的 next 操作。

值得注意的是，program 变量的类型在 Requirements 类型参数中包含 Random：

const program: Effect<void, never, Random>

This indicates that our program requires the Random service to be provided in order to execute successfully.

If we attempt to execute the effect without providing the necessary service we will encounter a type-checking error:

Example (Type Error Without Service Provision)

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

// Using the service
const program = Effect.gen(function* () {
  const random = yield* Random
  const randomNumber = yield* random.next
  console.log(`random number: ${randomNumber}`)
})

Effect.runSync(program)
Error ts(2379)  ― Argument of type 'Effect<void, never, Random>' is not assignable to parameter of type 'Effect<void, never, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
  Type 'Random' is not assignable to type 'never'.

To resolve this error and successfully execute the program, we need to provide an actual implementation of the Random service.

In the next section, we will explore how to implement and provide the Random service to our program, enabling us to run it successfully.

Providing a Service Implementation

In order to provide an actual implementation of the Random service, we can utilize the Effect.provideService function.

Example (Providing a Random Number Implementation)

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

// Using the service
const program = Effect.gen(function* () {
  const random = yield* Random
  const randomNumber = yield* random.next
  console.log(`random number: ${randomNumber}`)
})

// Providing the implementation
//
//      ┌─── Effect<void, never, never>
//      ▼
const runnable = Effect.provideService(program, Random, {
  next: Effect.sync(() => Math.random())
})

// Run successfully
Effect.runPromise(runnable)
/*
Example Output:
random number: 0.8241872233134417
*/

In the code above, we provide the program we defined earlier with an implementation of the Random service.

We use the Effect.provideService function to associate the Random tag with its implementation, an object with a next operation that generates a random number.

Notice that the Requirements type parameter of the runnable effect is now never. This indicates that the effect no longer requires any service to be provided.

With the implementation of the Random service in place, we are able to run the program without any further requirements.

Extracting the Service Type

To retrieve the service type from a tag, use the Context.Tag.Service utility type.

Example (Extracting Service Type)

import { Effect, Context } from "effect"

// Declaring a tag
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

// Extracting the type
type RandomShape = Context.Tag.Service<Random>
/*
This is equivalent to:
type RandomShape = {
    readonly next: Effect.Effect<number>;
}
*/

Using Multiple Services

When we require the usage of more than one service, the process remains similar to what we’ve learned in defining a service, repeated for each service needed.

Example (Using Random and Logger Services)

Let’s examine an example where we need two services, namely Random and Logger:

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  {
    readonly next: Effect.Effect<number>
  }
>() {}

// Declaring a tag for the logging service
class Logger extends Context.Tag("MyLoggerService")<
  Logger,
  {
    readonly log: (message: string) => Effect.Effect<void>
  }
>() {}

const program = Effect.gen(function* () {
  // Acquire instances of the 'Random' and 'Logger' services
  const random = yield* Random
  const logger = yield* Logger

  const randomNumber = yield* random.next

  yield* logger.log(String(randomNumber))
})

The program effect now has a Requirements type parameter of Random | Logger:

const program: Effect<void, never, Random | Logger>

indicating that it requires both the Random and Logger services to be provided.

To execute the program, we need to provide implementations for both services:

Example (Providing Multiple Services)

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  {
    readonly next: Effect.Effect<number>
  }
>() {}

// Declaring a tag for the logging service
class Logger extends Context.Tag("MyLoggerService")<
  Logger,
  {
    readonly log: (message: string) => Effect.Effect<void>
  }
>() {}

const program = Effect.gen(function* () {
  const random = yield* Random
  const logger = yield* Logger
  const randomNumber = yield* random.next
  return yield* logger.log(String(randomNumber))
})

// Provide service implementations for 'Random' and 'Logger'
const runnable = program.pipe(
  Effect.provideService(Random, {
    next: Effect.sync(() => Math.random())
  }),
  Effect.provideService(Logger, {
    log: (message) => Effect.sync(() => console.log(message))
  })
)

Alternatively, instead of calling provideService multiple times, we can combine the service implementations into a single Context and then provide the entire context using the Effect.provide function:

Example (Combining Service Implementations)

import { Effect, Context } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  {
    readonly next: Effect.Effect<number>
  }
>() {}

// Declaring a tag for the logging service
class Logger extends Context.Tag("MyLoggerService")<
  Logger,
  {
    readonly log: (message: string) => Effect.Effect<void>
  }
>() {}

const program = Effect.gen(function* () {
  const random = yield* Random
  const logger = yield* Logger
  const randomNumber = yield* random.next
  return yield* logger.log(String(randomNumber))
})

// Combine service implementations into a single 'Context'
const context = Context.empty().pipe(
  Context.add(Random, { next: Effect.sync(() => Math.random()) }),
  Context.add(Logger, {
    log: (message) => Effect.sync(() => console.log(message))
  })
)

// Provide the entire context
const runnable = Effect.provide(program, context)

Optional Services

There are situations where we may want to access a service implementation only if it is available. In such cases, we can use the Effect.serviceOption function to handle this scenario.

The Effect.serviceOption function returns an implementation that is available only if it is actually provided before executing this effect. To represent this optionality it returns an Option of the implementation.

Example (Handling Optional Services)

To determine what action to take, we can use the Option.isNone function provided by the Option module. This function allows us to check if the service is available or not by returning true when the service is not available.

import { Effect, Context, Option } from "effect"

// Declaring a tag for a service that generates random numbers
class Random extends Context.Tag("MyRandomService")<
  Random,
  { readonly next: Effect.Effect<number> }
>() {}

const program = Effect.gen(function* () {
  const maybeRandom = yield* Effect.serviceOption(Random)
  const randomNumber = Option.isNone(maybeRandom)
    ? // the service is not available, return a default value
      -1
    : // the service is available
      yield* maybeRandom.value.next
  console.log(randomNumber)
})

In the code above, we can observe that the Requirements type parameter of the program effect is never, even though we are working with a service. This allows us to access something from the context only if it is actually provided before executing this effect.

When we run the program effect without providing the Random service:

Effect.runPromise(program).then(console.log)
// Output: -1

We see that the log message contains -1, which is the default value we provided when the service was not available.

However, if we provide the Random service implementation:

Effect.runPromise(
  Effect.provideService(program, Random, {
    next: Effect.sync(() => Math.random())
  })
).then(console.log)
// Example Output: 0.9957979486841035

We can observe that the log message now contains a random number generated by the next operation of the Random service.

Handling Services with Dependencies

Sometimes a service in your application may depend on other services. To maintain a clean architecture, it’s important to manage these dependencies without making them explicit in the service interface. Instead, you can use layers to handle these dependencies during the service construction phase.

Example (Defining a Logger Service with a Configuration Dependency)

Consider a scenario where multiple services depend on each other. In this case, the Logger service requires access to a configuration service (Config).

import { Effect, Context } from "effect"

// Declaring a tag for the Config service
class Config extends Context.Tag("Config")<Config, {}>() {}

// Declaring a tag for the logging service
class Logger extends Context.Tag("MyLoggerService")<
  Logger,
  {
    // ❌ Avoid exposing Config as a requirement
    readonly log: (message: string) => Effect.Effect<void, never, Config>
  }
>() {}

To handle these dependencies in a structured way and prevent them from leaking into the service interfaces, you can use the Layer abstraction. For more details on managing dependencies with layers, refer to the Managing Layers page.

Use Layers for Dependencies

When a service has its own requirements, it’s best to separate implementation details into layers. Layers act as constructors for creating the service, allowing us to handle dependencies at the construction level rather than the service level.