回调函数与异步编程

模块系统解决了代码放在哪里、怎样被加载，却没有解决异步结果怎样穿过这些模块。早期 Node.js 大量依赖回调交付结果；一旦调用方和被调用方没有约定好“什么时候结束、能结束几次、错误交给谁”，模块边界再整齐也挡不住时序混乱。

下面这个故障，就是一个异步操作拥有两个结束出口以后发生的。

我遇到过一种很会伪装的故障：接口偶尔先返回“请求超时”，日志里隔几十毫秒却又出现“查询成功”。更麻烦的是，成功分支还会继续写响应，于是进程报出“响应头已经发送”。同一个请求像是结束了两次。

最初我把怀疑对象列了一排：网络抖动、数据库连接池、客户端重试，甚至日志采集重复上报。可请求编号对得上，客户端也只发了一次。给最终回调加上计数和时间戳以后，证据变得很直接：30 毫秒时超时分支调用一次，80 毫秒时底层任务完成，又调用了一次。

问题藏在一个看起来很正常的超时封装里：

function withTimeoutBroken(start, milliseconds, callback) {
  const timer = setTimeout(() => {
    callback(new Error(`操作超过 ${milliseconds} 毫秒`));
  }, milliseconds);
 
  start((error, result) => {
    clearTimeout(timer);
    callback(error, result);
  });
}
 
withTimeoutBroken(
  (done) => setTimeout(() => done(null, '查询成功'), 80),
  30,
  (error, result) => {
    if (error) {
      console.error(error.message);
      return;
    }
 
    console.log(result);
  },
);

clearTimeout 只能取消还没触发的计时器。超时一旦发生，80 毫秒后的完成通知并不会凭空消失，于是两个分支都拿到了调用 callback 的机会。

这个故障给我的关键提醒是：回调并不只是“传进去的函数”。它是一份控制权契约。执行方决定何时调用、传什么参数、怎样表示失败，以及一次任务最多交付几次结果。只盯着函数体，很容易错过真正危险的地方。

第一条线索：有回调，不等于异步

排查时我先把所有“接收函数参数”的调用都标成异步，结果很快走进了死胡同。回调首先只是一个普通函数：调用方把它交给另一个函数，由接收方按约定调用。至于是在当前调用栈立即调用，还是等某项工作结束后再调用，得看 API 的行为。

map 接收回调，却会同步完成整轮遍历：

const prices = [12, 20, 35];
const discounted = prices.map((price) => price * 0.9);
 
console.log(discounted); // [10.8, 18, 31.5]
console.log('map 已经完成');

readFile 也接收回调，但它会先发起读取并返回，等读取完成后，Node.js 才安排回调执行：

const { readFile } = require('node:fs');
 
console.log('1. 准备读取');
 
readFile(__filename, 'utf8', (error, text) => {
  if (error) {
    console.error('3. 读取失败：', error.message);
    return;
  }
 
  console.log('3. 读取完成，字符数：', text.length);

把代码保存为 .cjs 文件并运行，输出顺序会是 1、2、3。这里容易产生一个经典误判：既然读取已经启动，结果是不是也能在后面一行拿到？

const { readFile } = require('node:fs');
 
let content;
 
readFile(__filename, 'utf8', (error, text) => {
  if (error) return;
  content = text;
});
 
console.log(content); // undefined

这不是作用域问题，也不是磁盘“太慢”。执行 console.log 时，赋值语句还没有机会运行。任何依赖 content 的动作都必须从完成回调继续，或交给另一种能表达异步结果的抽象。

回调开始运行后，JavaScript 仍会逐行执行

“异步”描述的是回调何时获得执行机会，不代表回调里的计算自动并行。事件循环开始执行一个回调后，其中的 JavaScript 仍会逐行运行，直到函数返回或再次发起异步工作。

如果我在文件读取回调里解析一个巨大的 JSON，或者跑一段耗时循环，其他请求仍然要等待。健康的 I/O 回调通常只做少量协调：检查错误、整理结果、启动后续异步任务。CPU 密集计算需要拆分、交给工作线程，或迁移到更合适的执行环境。

最难推理的是“有时同步，有时异步”

缓存封装很容易制造这种不一致：命中缓存时立即调用，未命中时等 I/O 完成再调用。

function loadProfile(userId, callback) {
  if (profileCache.has(userId)) {
    callback(null, profileCache.get(userId)); // 同步
    return;
  }
 
  readProfile(userId, callback); // 异步
}

调用方很难知道回调是在 loadProfile 返回前还是返回后执行。测试可能因为缓存状态不同而呈现完全不同的顺序，初始化逻辑也可能只在某条路径出错。

如果这个 API 承诺异步完成，就应让命中缓存的分支也延后交付：

function loadProfile(userId, callback) {
  if (profileCache.has(userId)) {
    queueMicrotask(() => callback(null, profileCache.get(userId)));
    return;
  }
 
  readProfile(userId, callback);
}

这里的重点不是所有回调都必须异步，而是同一个 API 的时序要稳定，并把这个约定告诉调用方。

关键转折：把回调当成接口，而不是写法

事故复现以后，我没有立刻把代码改成 Promise。先把回调接口的规则写清楚，反而更容易看出每个分支哪里越界：

1. 单次异步任务使用 (error, result) 交付结局。
2. 失败和成功互斥，调用方先检查 error。
3. 所有终止路径最终只调用一次完成回调。
4. API 的调用时机保持一致，不让缓存状态改变时序。

这四条约束就是回调代码能否被可靠组合的地基。

Error-first：让失败走固定通道

Node.js 中常见的单次异步接口采用错误优先回调：

callback(error, result)

失败时调用 callback(error)，成功时调用 callback(null, result)。这不是 JavaScript 语法，而是一种广泛采用的接口协议。它让调用方不必猜测错误究竟会被抛出、塞进结果，还是用某个布尔值表示。

先创建 settings.json：

{
  "port": 3000
}

再运行读取代码：

const { readFile } = require('node:fs');
 
readFile('settings.json', 'utf8', (error, text) => {
  if (error) {
    console.error('配置读取失败：', error.message);
    return;
  }
 
  console.log('读取到的文本长度：', text.length);
});

错误分支中的 return 不是把结果返回给 readFile。它只是结束当前回调，避免代码处理完失败后又跌进成功路径。这种提前返回能让主路径保持平直，也减少一次任务出现两个结局的机会。

封装时，不要泄漏内部的错误表达

假设我想把“读取文件”和“解析 JSON”封装成 readJson。磁盘读取通过回调报告失败，JSON.parse 却会同步抛出异常。封装层应把这两种失败统一到一个出口：

const { readFile } = require('node:fs');
 
function readJson(filePath, callback) {
  readFile(filePath, 'utf8', (readError, text) => {
    if (readError) {
      callback(readError);
      return;
    }
 
    let value;
 
    try {
      value =

这里有个不起眼却重要的细节：callback(null, value) 位于 try 外。如果把它也包进 try，调用方的回调一旦抛错，readJson 会误以为 JSON 解析失败，进入 catch 后再调用一次 callback(parseError)。内部封装由此吞掉调用方的编程错误，还破坏了“只完成一次”的约束。

修复事故：所有完成路径共用一道门

超时和底层任务是两条竞争的结束路径。仅在各分支里写 return 不够，因为它们属于两次不同的函数调用，彼此看不见。解决方法是让它们共享同一个一次性出口：

function once(callback) {
  let called = false;
 
  return (...args) => {
    if (called) return;
    called = true;
    callback(...args);
  };
}
 
function withTimeout(start, milliseconds, callback) {
  let

once 让计时器、正常完成和启动时的同步异常争用同一道门，只有最先到达的结果能通过。deliveryStarted 还守住了一个异常边界：如果 start 同步调用 done，而调用方自己的回调抛错，这个错误应继续抛出，不能被误报成启动失败。

不过这个修复只保证“不重复交付”，并没有停止底层工作。生产环境还应尽量把取消能力传下去，例如使用 AbortController、关闭请求或调用驱动提供的取消方法。否则超时任务虽然不再改写响应，仍可能继续消耗连接、CPU 和内存。

还要区分完成回调与事件监听器。读取一个文件是单次完成操作，回调应只来一次；可读流的 data 事件表达一串数据块，监听器原本就会多次执行。“只能调用一次”不是套在所有函数上的规定，而是单次结果接口的约束。

控制流：先问是否依赖，再决定是否嵌套

故障修好后，我继续整理调用链，发现不少嵌套并不是异步代码的必然结果，只是没有先分清任务之间的关系。

两次读取互不依赖，可以同时发起：

const { readFile } = require('node:fs');
 
readFile('a.txt', 'utf8', (error, text) => {
  if (error) return console.error('a.txt：', error.message);
  console.log('A：', text.length);
});
 
readFile('b.txt', 'utf8'

这两项读取的完成顺序不确定，代码也不应依赖日志 A 与 B 的先后。如果第二项任务必须使用第一项结果，才需要表达串行依赖。例如先查用户，再用用户编号查订单：

const users = new Map([[1, { id: 1, name: '小林' }]]);
 
const orders = new Map([
  [
    1,
    [
      { id: 'A101', total: 88 },
      { id: 'A102', total: 120 },
    ],
  ],
]);
 
function findUser(userId, 

这里的嵌套准确表达了数据依赖，本身并不是错误。只有当步骤、失败分支和共享状态不断增加，结构才会开始失控。

回调地狱的根源不是括号

我曾试过把匿名函数全部改成命名函数，缩进确实好看了，但维护压力并没有自动消失。真正的问题通常是四件事叠在一起：

• 时间依赖藏在多层函数里，启动顺序需要向内追踪；
• 错误出口散落在各层，漏掉一次返回就会继续执行；
• 中间状态跨越多个闭包，改动一步可能牵动整条链；
• 调用时机与次数由被调用方掌握，接口失约会扰乱整个流程。

把每个业务步骤拆成输入、输出明确的小函数，会比单纯调整缩进更有效：

function loadUserSummary(userId, callback) {
  findUser(userId, (error, user) => afterUser(error, user, callback));
}
 
function afterUser(error, user, callback) {
  if (error) {
    callback(error);
    return;
  }
 
  findOrders(user.id, (orderError, userOrders) =>

这段代码依然使用回调，数据依赖也没有消失，但每一步现在可以单独测试。整理类似流程时，我会坚持三个判断：独立任务并发发起；依赖任务显式串行；所有步骤遵守同一种 Error-first 协议，最终汇入一个完成出口。

异常为什么逃过了外层 try...catch

排查日志时，另一个误导我的点是：调用处明明包了 try...catch，回调里抛出的错误却仍然让进程退出。

const { readFile } = require('node:fs');
 
try {
  readFile('missing.txt', 'utf8', (error, text) => {
    if (error) throw error;
    console.log(text);
  });
} catch (error) {
  console.error('这里接不到 readFile 回调里的错误');
}

try...catch 只能捕获当前调用栈抛出的异常。readFile 返回后，try 已经结束；回调稍后运行时处在另一轮调用栈中，原来的 catch 根本不在场。

可预期的读取失败应在回调里处理，或继续交给上层完成回调：

const { readFile } = require('node:fs');
 
function printFile(filePath, callback) {
  readFile(filePath, 'utf8', (error, text) => {
    if (error) {
      callback(error);
      return;
    }
 
    console.log(text);
    callback(null);

回调内部的同步操作则可以在最窄范围使用 try...catch，例如前面的 JSON.parse。范围越精确，越不容易把调用方自己的 bug 误当成底层失败。

也并非所有异步对象都用 Error-first 完成回调报告错误。流等 EventEmitter 对象通常通过 'error' 事件传递失败。写适配层之前必须先确认具体 API 的契约，不能仅凭“这是 Node.js”就套用同一种模式。

迁移到 Promise 时，先保住原有语义

当回调链已经难以组合，Promise 能把单次异步结果放进一个有状态的对象中。变化的是结果的交付方式，不是文件、网络或数据库工作突然换了一套运行机制。

如果旧函数的最后一个参数是标准 Error-first 回调，可以用 node:util 的 promisify 适配：

const { readFile } = require('node:fs');
const { promisify } = require('node:util');
 
const readFileAsync = promisify(readFile);
 
async function showSourceLength() {
  const text = await readFileAsync(__filename, 'utf8');
  console.log('字符数：', text.length);

promisify 默认假设最后一个参数是 (error, value) 形式的回调。使用两个独立回调、一次交付多个成功值，或依赖方法 this 的旧接口，都需要专门适配。已有 Promise 入口的模块则可以直接使用对应入口，例如 node:fs/promises。

迁移也不会自动修复失约的旧接口。如果底层函数有时同步、有时异步，或者会多次调用回调，应该先把边界行为查清，再做包装。抽象可以改变写法，却不能替我们补全缺失的契约。

我现在怎样检查一个回调 API

经历那次“双重完成”以后，我会按一张固定清单审查回调代码：

1. 画时序。 标出同步返回、异步完成和回调真正执行的先后，避免提前读取结果。
2. 列出口。 把成功、失败、超时、取消、异常和重试全部列出，确认它们最终汇入同一个完成函数。
3. 守协议。 使用一致的 (error, result) 结构，失败后立即结束当前回调。
4. 查次数。 单次任务只交付一次；可能竞争时用 once 防护，并尽量取消落败的底层任务。
5. 拆依赖。 无依赖任务可以并发，有依赖任务显式串行，步骤函数保持输入输出清楚。
6. 缩小异常边界。 只捕获当前调用栈中确实能够理解和转换的同步异常。

这套方法比“看见嵌套就改 Promise”更可靠。Promise 和 async/await 能改善组合方式，但控制权、错误通道、调用时机和单次完成仍是底层必须兑现的承诺。

动手检查这份契约

假设你要封装一个 loadProfile(userId, callback)，它内部有缓存：命中缓存时能立刻拿到数据，未命中时要异步读取。先回答三个问题：

1. 缓存命中和未命中时，回调是否会在不同的时机执行？
2. 读取失败后有没有可能继续走到成功回调？
3. 超时与读取完成同时发生时，谁能保证只交付一次？

回调最值得掌握的不是嵌套语法，而是边界意识：谁拥有控制权，什么时候交付结果，失败怎样传播，单次任务怎样确保只结束一次。只要这些问题有明确答案，无论继续维护回调，还是迁移到 Promise，异步流程都不会再靠运气运行。

当这些契约明确以后，回调真正剩下的问题是组合成本：三个顺序步骤、两个并行步骤和一个统一错误出口，很快就会把控制流拆散在多层闭包中。Promise 并没有改变异步工作的底层机制，它改变的是结果的表达方式——让未来的成功或失败可以被返回、串联和统一捕获。