Effect-TS平台入门模式Skill effect-patterns-platform-getting-started

---

name: effect-patterns-platform-getting-started 描述: Effect-TS 平台入门模式。用于在 Effect-TS 应用程序中处理平台入门相关任务。

Effect-TS 模式：平台入门

本技能提供 2 个精选的 Effect-TS 模式，用于平台入门。 在以下任务中使用此技能：

• 平台入门
• Effect-TS 应用程序中的最佳实践
• 真实世界的模式和解决方案

---

🟢 初学者模式

您的第一个平台操作

规则: 使用 @effect/platform 进行跨平台系统操作，并与 Effect 集成。

良好示例:

import { Effect } from "effect"
import { FileSystem } from "@effect/platform"
import { NodeContext, NodeRuntime } from "@effect/platform-node"

// Read a file - returns Effect<string, PlatformError>
const readConfig = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem
  
  // Read file as UTF-8 string
  const content = yield* fs.readFileString("./config.json")
  
  return JSON.parse(content)
})

// Write a file
const writeLog = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem
  
  yield* fs.writeFileString(
    "./app.log",
    `Started at ${new Date().toISOString()}
`
  )
})

// Combine operations
const program = Effect.gen(function* () {
  const config = yield* readConfig
  yield* Effect.log(`Loaded config: ${config.appName}`)
  
  yield* writeLog
  yield* Effect.log("Log file created")
})

// Run with Node.js platform
program.pipe(
  Effect.provide(NodeContext.layer),
  NodeRuntime.runMain
)

原理:

Effect 平台提供类型安全、跨平台的系统操作。使用 @effect/platform-node 用于 Node.js 或 @effect/platform-bun 用于 Bun。

---

平台将系统操作包装在 Effect 中，为您提供：

1. 类型安全 - 文件操作返回 Effect<Content, PlatformError>
2. 资源管理 - 文件自动关闭
3. 跨平台 - 相同代码在 Node.js、Bun、浏览器上工作
4. 可组合性 - 将文件操作与其他效果链式连接

---

---

访问环境变量

规则: 使用 Effect 访问环境变量，并正确处理错误。

良好示例:

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

// ============================================
// BASIC: Read required variable
// ============================================

const getApiKey = Config.string("API_KEY")

const program1 = Effect.gen(function* () {
  const apiKey = yield* getApiKey
  yield* Effect.log(`API Key: ${apiKey.slice(0, 4)}...`)
})

// ============================================
// OPTIONAL: With default value
// ============================================

const getPort = Config.number("PORT").pipe(
  Config.withDefault(3000)
)

const program2 = Effect.gen(function* () {
  const port = yield* getPort
  yield* Effect.log(`Server will run on port ${port}`)
})

// ============================================
// OPTIONAL: Return Option instead of failing
// ============================================

const getOptionalFeature = Config.string("FEATURE_FLAG").pipe(
  Config.option
)

const program3 = Effect.gen(function* () {
  const feature = yield* getOptionalFeature
  
  if (Option.isSome(feature)) {
    yield* Effect.log(`Feature enabled: ${feature.value}`)
  } else {
    yield* Effect.log("Feature flag not set")
  }
})

// ============================================
// COMBINED: Multiple variables as config object
// ============================================

const AppConfig = Config.all({
  apiKey: Config.string("API_KEY"),
  apiUrl: Config.string("API_URL"),
  port: Config.number("PORT").pipe(Config.withDefault(3000)),
  debug: Config.boolean("DEBUG").pipe(Config.withDefault(false)),
})

const program4 = Effect.gen(function* () {
  const config = yield* AppConfig
  
  yield* Effect.log(`API URL: ${config.apiUrl}`)
  yield* Effect.log(`Port: ${config.port}`)
  yield* Effect.log(`Debug: ${config.debug}`)
})

// ============================================
// RUN: Will fail if required vars missing
// ============================================

Effect.runPromise(program4).catch((error) => {
  console.error("Missing required environment variables")
  console.error(error)
})

原理:

使用 Effect 的内置函数或平台的环境服务访问环境变量，以实现类型安全的配置。

---

环境变量可能缺失或格式错误。Effect 帮助您：

1. 处理缺失变量 - 返回 Option 或失败并带有类型化错误
2. 验证值 - 使用 Schema 解析和验证
3. 提供默认值 - 当变量缺失时使用回退值
4. 文档化需求 - 类型显示需要什么

---

---