Show HN: Pure Effect – 无需数据库，在本地复现生产环境 Bug

背景

在软件开发中，一个经典且令人头疼的问题是：“它在你的机器上能跑，但在生产环境却坏了，且无法复现。”

造成这一困境的根本原因通常在于业务逻辑（Business Logic）与输入/输出操作（I/O）纠缠在一起。当开发者编写类似 await db.findUser(email) 的代码时，数据库调用会在逻辑执行的中间立即触发。这意味着：

1. 测试困难：为了检查行为，测试必须实际执行 I/O 操作，这通常依赖于 Mock 对象、Fake 实现或 Docker 容器。
2. 调试盲区：当生产环境发生故障时，开发者往往只拿到一个堆栈跟踪（Stack Trace）。由于请求实际发出的 I/O 调用从未被记录，因此无法在本地重放（Replay）以追溯确切的路径。

传统的 async/await 模式让 I/O 成为了逻辑本身的一部分，导致验证代码正确性必须通过执行它，而失败的运行往往不留痕迹，难以逐步排查。

核心内容

Pure Effect 是一个用于 JavaScript 和 TypeScript 的零依赖 Effect 库。它的核心理念是：业务逻辑不直接执行 I/O，而是返回描述“它将执行什么 I/O”的纯对象（Plain Objects）。

通过这种模式，开发者可以在测试中读取这些对象，或者从失败的生产运行中重放它们。直到解释器（Interpreter）运行这些指令之前，数据库永远不会被触碰。

1. 核心范式转变：从“执行”到“描述”

Pure Effect 将程序视为一棵由 Effect 组成的树。解释器在系统的边缘（Edge）遍历这棵树并执行实际的副作用。

• 传统模式：调用立即触发，无法预知结果，难以测试。
• Pure Effect 模式：
  • 首先读取逻辑“打算”做什么（返回一个惰性对象）。
  • 将生产环境中实际看到的结果（Recorded Data）喂给这个逻辑树。
  • 沿着完全相同的路径行走，无需连接任何基础设施。

2. 六大基础构建块

Pure Effect 仅由六种基本形状组成，易于学习且可组合：

1. Success(value)：
   • 成功的计算结果。返回 { type: 'Success', value }。
   • 任何管道步骤都可以返回它，以将数据传递给下一步。
2. Failure(error)：
   • 立即停止管道并短路剩余步骤。
   • 保留可选的 initialInput 用于诊断。
3. Command(cmd, next)：
   • 将副作用描述为数据。
   • cmd 是实际运行的函数；next 接收 cmd 的结果并返回下一个 Effect。
4. Ask(next)：
   • 读取传递给 runEffect 的上下文对象（如 tenant、request id、config），而无需在每个函数签名中显式传递。
5. Retry(effect, opts)：
   • 用失败重试机制包装任何 Effect。
   • 可配置尝试次数、延迟和退避策略。耗尽后返回结构化的 Failure。
6. Parallel(effects, next)：
   • 通过 Promise.all 并发运行 Effect 树。
   • Ask 上下文会自动流入每个分支。第一个 Failure 会导致短路。

3. 代码实现示例

以下是一个用户注册流程的对比演示：

纯函数逻辑（无 I/O，无导入，即时可测）：

import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect';

// 验证逻辑：返回纯数据
function validateRegistration(input) {
  if (!input.email?.includes('@')) return Failure('Invalid email.');
  if (input.password?.length < 8) return Failure('Password too short.');
  return Success(input);
}

function ensureEmailAvailable(found) {
  return found ? Failure('Email already in use.') : Success(true);
}

// 命令：副作用被描述为数据，由解释器执行
function findUserByEmail(email) {
  const cmdFindUser = () => db.findUserByEmail(email);
  return Command(cmdFindUser, (found) => Success(found));
}

function saveUser(input) {
  const cmdSaveUser = () => db.saveUser(input);
  return Command(cmdSaveUser, (saved) => Success(saved));
}

// 管道：组合成单个流程
const registerUserFlow = (input) => effectPipe(
  validateRegistration,
  () => findUserByEmail(input.email),
  ensureEmailAvailable,
  () => saveUser(input)
)(input);

测试与运行：

• 测试：断言结构，无需 Mock，无需 I/O。

  const flow = registerUserFlow({ email: '[email protected]', password: 'password123' });
  assert.equal(flow.cmd.name, 'cmdFindUser');
  assert.equal(flow.next(null).cmd.name, 'cmdSaveUser');
  

• 运行：在边界处将树交给解释器。

  const saved = await runEffect(registerUserFlow(input), { flowName: 'register' });
  

4. 开箱即用的功能

• 断言代码行为：管道返回惰性对象。你可以遍历树并检查每一步，无需 Mock、内存 Fake 或容器。
• 本地逐步调试失败请求：记录生产环境中每个命令的返回值，然后将其喂回同一棵树，从而重走确切路径，无需附加基础设施。
• 无需等待即可测试弹性：用重试语义包装任何 Effect。由于配置是纯数据，测试可以直接断言配置，无需定时器、sleep 或不稳定的时序。
• 并发分支，有序结果：具备 Promise.all 语义，首个失败即短路。Ask 上下文自动流入每个分支。
• 不污染签名的上下文：从框架层解析 tenant、trace id 或 config。领域函数保持干净，仅使用 Ask。
• 用于追踪的生命周期钩子：onRun、onStep 和 onBeforeCommand 允许在不触碰领域代码的情况下，将工作流包裹在 Span 中。

5. 适用边界

Pure Effect 将单个有限操作描述为一棵树，你在运行前读取它。这是它的优势，也是其边界：它适用于**请求形状（Request-shaped）**的操作，而非后台进程（Background processes）。

关键要点

• 解耦逻辑与 I/O：业务逻辑返回描述 I/O 的纯对象，而非直接执行 I/O。
• 零依赖与零基础设施：测试和调试无需数据库、Mock 或容器，因为逻辑本身就是数据。
• 生产 Bug 重放：通过记录生产环境中的命令结果，并在本地重放数据结构，可以精确复现和调试生产故障。
• AI 代码生成的审计工具：AI 生成的代码通常基于 async/await，难以在不执行的情况下验证控制流。Pure Effect 允许开发者在 AI 代码执行前读取其控制流（命令顺序、分支路径），从而在运行前排除错误路径。
• 结构化错误处理：内置 Failure 和 Retry 机制，使错误处理和重试逻辑成为可测试、可配置的数据结构。
• 上下文管理：通过 Ask 机制，在不污染领域函数签名的前提下，优雅地获取请求级上下文（如 Trace ID、Tenant ID）。

意义与影响

Pure Effect 提供了一种应对现代 Web 开发中“测试与调试复杂性”的新范式。

1. 提升调试效率：它将“黑盒”式的异步执行转化为“白盒”式的结构遍历。开发者不再需要猜测生产环境发生了什么，而是可以通过检查数据结构来“阅读”程序的执行路径。
2. 增强代码可测试性：通过将副作用抽象为数据