使用Effect-TS在TypeScript中构建生产就绪应用

技术背景

Effect是一个强大的TypeScript框架，它提供了一个成熟的函数式效果系统以及丰富的标准库。该框架由多个包组成，这些包协同工作，助力开发者构建健壮的TypeScript应用程序。核心包effect是框架的基础，提供了管理副作用、确保类型安全和支持并发的原语。

实现步骤

1. 了解仓库结构

Effect的单仓库（Monorepo）被组织成多个包，每个包都扩展了核心功能。以下是包含的包概述：

包名	描述
effect	核心包
@effect/ai	AI工具
@effect/ai-openai	OpenAI工具
@effect/ai-anthropic	Anthropic工具
@effect/cli	CLI工具
@effect/cluster	分布式计算工具
@effect/cluster-browser	浏览器集群工具
@effect/cluster-node	Node.js集群工具
@effect/cluster-workflow	集群工作流管理
@effect/experimental	实验性功能和API
@effect/opentelemetry	OpenTelemetry集成
@effect/platform	跨平台运行时工具
@effect/platform-browser	浏览器平台工具
@effect/platform-bun	Bun平台工具
@effect/platform-node	Node.js平台工具
@effect/platform-node-shared	Node.js共享工具
@effect/printer	通用打印工具
@effect/printer-ansi	ANSI兼容打印工具
@effect/rpc	远程过程调用（RPC）工具
@effect/rpc-http	基于HTTP的RPC工具
@effect/sql	SQL数据库工具
@effect/sql-clickhouse	ClickHouse的@effect/sql实现
@effect/sql-d1	Cloudflare D1的@effect/sql实现
@effect/sql-drizzle	Drizzle的@effect/sql实现
@effect/sql-kysely	Kysely的@effect/sql实现
@effect/sql-libsql	使用@libsql/client库的@effect/sql实现
@effect/sql-mssql	使用mssql tedious库的@effect/sql实现
@effect/sql-mysql2	使用mysql2库的@effect/sql实现
@effect/sql-pg	使用postgres.js库的@effect/sql实现
@effect/sql-sqlite-bun	使用bun:sqlite库的@effect/sql实现
@effect/sql-sqlite-do	Cloudflare Durable Objects sqlite存储的@effect/sql实现
@effect/sql-sqlite-node	使用better-sqlite3库的@effect/sql实现
@effect/sql-sqlite-react-native	使用react-native-quick-sqlite库的@effect/sql实现
@effect/sql-sqlite-wasm	使用@sqlite.org/sqlite-wasm库的@effect/sql实现
@effect/typeclass	函数式编程类型类
@effect/vitest	Vitest测试工具

2. 贡献代码

2.1 设置环境

首先，fork仓库并克隆到本地。进入克隆的仓库并创建一个新分支：

git checkout -b my-branch

运行以下命令安装所有依赖：

pnpm install  # Requires pnpm version 10.4.0

2.2 进行更改

• 实现更改：对代码库进行所需的更改。如果更改影响功能，请添加相应的测试以验证更新。
• 验证更改：运行以下命令确保更改不会引入任何问题：

pnpm codegen (可选): 如果更改了包结构或引入了新模块，重新生成包入口点。
pnpm check: 确认代码编译无错误。
pnpm test: 执行所有单元测试，确保更改未破坏现有功能。
pnpm circular: 检查导入中是否存在循环依赖。
pnpm lint: 确保代码符合编码标准。如果遇到样式问题，使用pnpm lint-fix自动纠正。
pnpm test-types: 运行类型级测试。测试使用tstyche编写。
pnpm docgen: 确保文档正确生成并反映所做的更改。

2.3 文档记录

• JSDoc注释：添加新功能时，使用JSDoc注释记录代码。至少包含以下内容：
  • 简短描述：总结功能的目的和用途。
  • 示例：在@example标签下提供使用示例。
  • 版本：使用@since标签指示功能引入的版本。
  • 类别（可选）：使用@category标签对功能进行分类。
• 变更集文档：在提交更改之前，使用变更集记录更改：

pnpm changeset

在创建变更集过程中，选择适合更改的级别：

• patch：用于小修复或不影响库整体功能的小更改。
• minor：用于增强功能但不破坏现有功能的新特性。
• major：用于引入向后不兼容更改的任何更改。

2.4 提交更改

• 提交到仓库：使用清晰描述的提交消息将更改提交到仓库：

git commit -am 'Add some feature'

• 关联问题：如果提交解决了一个开放问题，在提交消息中直接引用问题编号。如果提交解决了问题，可以添加, closes #<issue-number>：

git commit -am 'Add some feature, closes #123'

2.5 推送到Fork

将更改推送到GitHub的fork：

git push origin my-branch

2.6 创建拉取请求

根据更改类型，针对原始仓库的相应分支创建拉取请求：

• main分支：用于小补丁或错误修复。
• next-minor分支：用于非破坏性的新功能。
• next-major分支：用于引入破坏性更改的变更。

核心代码

以下是一个简单的使用Effect的示例：

import { Effect } from "effect"

console.log(Effect.runSyncExit(Effect.succeed(1)))
/*
Output:
{
  _id: "Exit",
  _tag: "Success",
  value: 1
}
*/

最佳实践

• 在开发过程中，及时更新文档，确保代码和文档的一致性。
• 编写清晰、可维护的代码，并添加足够的注释。
• 在提交更改之前，确保所有测试通过，避免引入新的问题。

常见问题

• 依赖安装问题：确保使用的pnpm版本为10.4.0或更高。
• 测试失败：检查更改是否影响了现有功能，添加或修改相应的测试用例。
• 提交被拒绝：检查提交消息是否清晰，是否正确关联了问题，以及拉取请求是否针对正确的分支。