JavaScript TransformStream 怎样组织自定义转换管道

如果一个前端数据源需要经过“清理文本、补充字段、再编码”这样的连续处理，最容易失控的写法是把所有逻辑塞进一个回调。TransformStream 更适合把每个转换阶段拆开：它有一个 writable 输入端和一个 readable 输出端，使用 pipeThrough() 就能把多个阶段接成管道。

本文只围绕一个可复用的 JavaScript 转换管道展开：先去掉每个文本块两侧空白，再添加统一前缀。这样既能看清最小写法，也能看清每个参数的职责。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/TransformStream

先看 TransformStream 的两端

new TransformStream(transformer) 返回一个转换节点。上游写入 writable，下游从 readable 读取；转换器对象可以实现 start、transform 和 flush。真正的组合点是 ReadableStream.prototype.pipeThrough()：它返回下一个可读流，而不是把当前流永久消费掉。

用 pipeThrough 组织两个自定义阶段

下面的两个转换器各自只做一件事。第一个处理输入块，第二个接收第一个阶段的结果。示例中的源流只是为了说明连接方式，实际项目中可以替换为 fetch() 响应体或其他可读流。

// 第一个阶段：清理每个文本块的首尾空白
const trimStream = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(String(chunk).trim());
  }
});

// 第二个阶段：给已经清理的文本统一添加前缀
const prefixStream = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(`[消息] ${chunk}`);
  }
});

// 用一个简单的源流演示两个阶段的组合关系
const source = new ReadableStream({
  start(controller) {
    controller.enqueue("  第一条  ");
    controller.enqueue("第二条");
    controller.close(); // 没有更多输入时关闭源流
  }
});

const result = source
  .pipeThrough(trimStream)
  .pipeThrough(prefixStream);

// 读取最终输出；真实项目也可以继续 pipeThrough 下一个阶段
const reader = result.getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(value);
}

这个连接方式的重点不是把两个回调写在一起，而是让每个转换器都遵守同一个输入/输出契约。后续要增加 JSON 解析或编码阶段时，只需要继续调用 pipeThrough()，不必改写已有阶段。

transform、flush 和 controller 分别管什么

transform(chunk, controller) 面向每个输入块；需要向下游产生数据时调用 controller.enqueue(value)。如果一个输入块不应产生输出，可以不调用 enqueue，但这会让该块被有意过滤，不能误当成“自动透传”。

flush(controller) 只在输入结束时处理收尾内容，例如把尚未完成的缓冲片段补成最后一条记录。它不是每个 chunk 都会调用的回调。转换器也可以在 transform 中返回 Promise，以等待异步处理。

发生不可恢复错误时，用 controller.error(error) 把错误传播给管道；controller.terminate() 则表示主动终止转换。两者都不是普通的业务输出，不能用 enqueue 传递一个“错误字符串”来替代。

落地时记住四个边界

• 继续串联用 pipeThrough：pipeTo() 的结果是 Promise，适合把流写入终点，不适合作为下一个转换阶段。
• 输出由 enqueue 决定：每个输入块可以产生零个、一个或多个输出块，是否输出要由转换逻辑明确决定。
• 结束逻辑放在 flush：不要在每次 transform 调用中重复执行只应发生一次的收尾动作。
• 错误不要吞掉：异步转换失败时让 Promise 拒绝或调用 controller.error()，让下游能够感知管道已经失败。

因此，组织自定义转换管道的最小心智模型是：每个 TransformStream 都是一个独立的“输入端—转换规则—输出端”节点，pipeThrough() 负责组合节点，controller 负责决定输出、错误和终止。把这三层职责分开，管道就更容易替换、测试和继续扩展。

常见问题

TransformStream 不写 transformer 会怎样？它仍然可以作为转换节点使用，数据不会被修改；需要改变数据时再提供转换器。

为什么 transform 中看不到结果？转换回调只负责接收输入块，必须通过 controller.enqueue() 把要交给下游的值明确写出。