一条坏记录,Promise.all 让客户数据同步陷入未知
reject 不会取消剩余写入,只有 allSettled 的逐条结果能说明同步了什么、能否安全重跑。
要点速览
- Promise.all 遇到第一个错误就 reject,但不会取消其余操作,对客户系统的写入仍在继续。
- 对于彼此独立的记录,Promise.allSettled 会给出每条记录的结果,便于生成报告并只重试失败项。
- p-limit 只限制同时运行的任务数。按每秒请求数计算的配额需要令牌桶这类单独机制,并配合 429 重试。
设想你正坐在客户办公室里跑第一次同步:把 5,000 个联系人从旧系统迁到新的 CRM。几秒钟后,终端只打出一行:“sync failed”。客户问你成功迁过去多少条、失败了多少条,你答不上来。
问题通常不在客户的 API,而在一行看上去完全无害的代码:await Promise.all(contacts.map(upsert))。几乎每个刚接触 JavaScript 异步编程的人都写过它,在 20 条记录的演示里它也跑得好好的。
对前线部署工程师(FDE)来说,这与其说是一堂语法课,不如说关乎做事的方法。和客户系统做集成时,你必须说得清:哪些记录过去了,哪些失败了、原因是什么,以及再跑一次是否安全。要回答这三个问题,就得准确理解每个 Promise 函数的行为。
Promise.all 的设计就是遇错即停
根据 MDN,只要任意一个输入 promise reject,Promise.all 就会立即 reject。这是快速失败(fail-fast)行为。如果 5,000 个联系人里有一个邮箱格式不对,API 返回 400,整个 await 就会抛错,其余 4,999 条记录的结果也随之丢失。
还有一个更危险的细节。MDN 明确指出,返回的 promise 被 reject,并不会取消其余操作。你的代码已经跳进 catch,打出了“sync failed”,但仍有成千上万个请求在往客户的 CRM 里写数据,而且没人跟踪。
结果是客户数据处于一种谁也说不清的状态。你以为这批失败了,于是重跑一遍,可实际上大部分记录早已写入。如果写操作不是幂等的,重跑就会产生重复数据,你只好去帮客户清理数据,而不是讨论下一步。
独立记录要换一个工具
MDN 给出了清晰的界线:Promise.allSettled 通常用于任务彼此不依赖,或者你总想知道每个 promise 结果的场景;Promise.all 更适合任务相互依赖,或者希望一有失败就立即停止的场景。
大多数数据同步属于前一类:联系人 A 失败,与联系人 B 毫无关系。Promise.all 依然有用武之地,比如开始前必须同时拿到认证 token 和配置,缺了任何一个都无法继续。
Promise.all
- 遇到第一个错误就 reject
- 其余操作继续运行,无人跟踪
- 适合相互依赖的步骤:token、配置、schema
- 缺一部分,整批就必须停止
Promise.allSettled
- 等待所有任务结束
- 按输入顺序返回每个任务的 status、value 或 reason
- 适合同步中彼此独立的记录
- 可以只重跑失败项
根据 MDN,allSettled 按输入顺序返回结果数组。每个元素的 status 为 “fulfilled” 或 “rejected”。成功的结果带 value 字段,失败的结果带 reason 字段。由于顺序不变,你可以按下标把每个结果对应回源记录,直接得到逐条报告。
换成 allSettled 还不够
如果只把 all 换成 allSettled,你仍然会一次性发出 5,000 个请求。客户的 API 会返回大量 429 错误,报告里会出现成千上万条失败记录,原因仅仅是你发得太快。
处理这个问题的常用库是 Sindre Sorhus 的 p-limit,它以受限的并发数运行异步函数。把每个任务包进 limit(...),再照常用 Promise.all 或 allSettled 收集结果即可。
但 p-limit 的 README 说得很清楚:这个库只限制同时运行的任务数。如果 API 配额按每秒请求数计算,5 个并发请求只要每个都返回得很快,照样可能超限。
Anvil 关于 429 限制的文章也指出,许多 SDK(包括大型 API 提供商的 SDK)本身并不处理限流,这部分工作通常留给了你。
重写同步脚本
下面是重写后的版本,使用 p-limit,在 429 时重试,并逐条报告结果:
import pLimit from 'p-limit';
const limit = pLimit(5); // 最多同时运行 5 个请求
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
function retryDelayMs(retryAfter, attempt) {
if (retryAfter) {
const value = String(retryAfter).trim();
// 防御性处理:纯数字的值按秒处理,
// 绝不交给日期解析器
if (/^\d+$/.test(value)) return Number(value) * 1000;
// HTTP-date 格式(不是 ISO 8601),
// 例如 "Wed, 21 Oct 2026 07:28:00 GMT"
const at = Date.parse(value);
if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
}
return 2 ** attempt * 1000; // 请求头无法解析:退回指数退避
}
async function upsertWithRetry(contact, attempt = 0) {
try {
return await crm.upsertContact(contact);
} catch (err) {
if (err.status === 429 && attempt < 5) {
await sleep(retryDelayMs(err.headers?.['retry-after'], attempt));
return upsertWithRetry(contact, attempt + 1);
}
throw err; // 400 或数据错误:不重试,记入报告
}
}
const settled = await Promise.allSettled(
contacts.map((c) => limit(() => upsertWithRetry(c)))
);
const report = settled.map((r, i) => ({
id: contacts[i].id,
status: r.status,
reason: r.status === 'rejected' ? String(r.reason?.message ?? r.reason) : null,
}));
const failedIds = report.filter((x) => x.status === 'rejected').map((x) => x.id);
console.log(`成功:${report.length - failedIds.length},失败:${failedIds.length}`);
几个小细节撑起了这段脚本。allSettled 保持顺序,所以 contacts[i] 始终对应 settled[i]。429 会重试,数据错误则不会,因为格式错误的邮箱无论重发多少次都会失败。
retryDelayMs 函数采用了防御式写法。根据 Anvil 的说法,Retry-After 中的日期使用 HTTP-date 格式,而不是 ISO 8601。因此函数先排除看起来像数字的值,再去解析日期,并始终保留一个兜底的退避策略。
不要盲目相信日期解析器在异常输入下的输出:延迟算错了,客户端可能恰恰在 API 要求你放慢的时候,用重试把它打爆。
配额按秒计算时,加上令牌桶
如果配额按每秒请求数计算,Anvil 认为令牌桶是客户端限流的最佳方式。思路是一个按固定速率补充令牌的“桶”,每个请求发送前都必须先取走一个令牌。下面是一个最小示例:
// 令牌桶示意:每秒最多 `rate` 个请求
function createBucket(rate) {
let tokens = rate;
let last = Date.now();
return async function take() {
for (;;) {
const now = Date.now();
tokens = Math.min(rate, tokens + ((now - last) / 1000) * rate);
last = now;
if (tokens >= 1) { tokens -= 1; return; }
await sleep(((1 - tokens) / rate) * 1000); // 等待攒满一个令牌
}
};
}
const take = createBucket(10); // 示例:配额为每秒 10 个请求
在 upsertWithRetry 中,紧挨着 crm.upsertContact(contact) 之前调用 await take(),这样重试也得排队取令牌。p-limit 继续限制并发数,令牌桶控制速率:两层机制互为补充,而不是相互替代。
Anvil 还建议,理想的方案是把限制完全隐藏起来。把 take() 和重试逻辑封装进一个专门的客户端,同步代码只需调用 upsertContact,不必操心配额。
面对客户代码时的步骤
先给工作分类。相互依赖的步骤(认证、读取 schema)保留 Promise.all,逐条记录的同步改用 allSettled。接着询问客户或查阅文档,弄清配额统计的是并发请求数还是每秒请求数,再决定用 p-limit、令牌桶,还是两者都用。
然后确定哪些错误值得重试。429 要重试,限定重试次数,并遵守 Retry-After;数据错误记入报告。最后把报告写入文件,并准备一条只重跑 failedIds 的命令,确保重跑永远不会碰到已成功写入的记录。
常见错误
第一,给 Promise.all 套上 try/catch 就以为万事大吉。catch 拦不住已经发出的请求。第二,把 p-limit 当成速率限制器,然后对 429 感到意外。第三,什么错误都重试,包括 400,结果一条坏记录拖慢了整次同步。
最后一个最少被提及,危害却最大:只记录“sync failed”,没有逐条报告。客户并不关心你用了哪个 Promise 函数,他们关心的是哪 37 条记录没迁过去,以及原因。
练习:抢在客户之前复现故障
用 Express 或一个 mock 函数写一个假 API:每 100 条记录中有 1 条返回 400;并发请求超过 5 个时返回 429,并附带 Retry-After,有时是数字,有时是 HTTP-date。
先运行 Promise.all 版本,统计 catch 执行之后仍有多少次写入发生;再运行上面重写的版本,对比两份报告。
这个练习也很适合放进作品集。在 FDE 面试中,讲清楚你如何发现这个 bug、测量了什么、又是怎样修复的。
在简历上,具体描述这项工作,例如“带逐条报告、限流和 429 重试的数据同步”,而不是“精通 JavaScript”这类空泛的表述。
读到提及集成工作的岗位描述时,准备好讲这个故事。
在客户现场,信任并非来自从不失败的同步,而是来自这样的同步:一旦出错,你能准确说出哪些记录失败了、为什么失败。
这篇文章对你有帮助吗?
感谢你的反馈!