# 一条坏记录，Promise.all 让客户数据同步陷入未知

> reject 不会取消剩余写入，只有 allSettled 的逐条结果能说明同步了什么、能否安全重跑。

原文: https://fdetimes.net/zh/guides/promise-all-vs-allsettled-data-sync/

设想你正坐在客户办公室里跑第一次同步：把 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 和配置，缺了任何一个都无法继续。

根据 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 时重试，并逐条报告结果：

```js
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 认为令牌桶是客户端限流的最佳方式。思路是一个按固定速率补充令牌的“桶”，每个请求发送前都必须先取走一个令牌。下面是一个最小示例：

```js
// 令牌桶示意：每秒最多 `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”这类空泛的表述。

读到提及集成工作的岗位描述时，准备好讲这个故事。

在客户现场，信任并非来自从不失败的同步，而是来自这样的同步：一旦出错，你能准确说出哪些记录失败了、为什么失败。

**本周动手试试:**

- 在你的集成代码库中搜索所有 Promise.all(items.map(...))。逐个自问：这些任务相互依赖吗？其中一个失败时，整批是否应该停下？
- 为现有的同步脚本加上逐条报告文件（id、status、reason），以及一条只重跑失败记录的命令。
- 阅读客户所用 API 的限流文档，记下配额统计的是并发请求数还是每秒请求数，以及 API 是否返回 Retry-After 响应头。

## 信源

- [Promise.all() - JavaScript | MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)

- [Promise.allSettled() - JavaScript | MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled)

- [sindresorhus/p-limit: Run multiple promise-returning & async functions with limited concurrency](https://github.com/sindresorhus/p-limit)

- [Throttling and consuming APIs with 429 rate limits (Anvil)](https://www.useanvil.com/blog/2021-03-29-throttling-and-consuming-apis-with-429-rate-limits)
