Promise.allSettled 怎麼用?多個 API 部分失敗時保留成功結果
儀表板同時讀取帳號、通知與推薦內容時,如果通知 API 失敗就把整頁換成錯誤畫面,成功取得的帳號資料也會被藏掉。當這些資料可以各自顯示,Promise.allSettled() 能讓程式拿到每一項成功或失敗的結果,再替不同區塊決定 fallback。
資料彼此獨立、需要保留部分成功結果時用 allSettled;必須全數成功才能繼續時用 Promise.all。 allSettled 不會替請求設定 timeout、限制並行數或取消其他工作,這些仍要在任務本身設計。
結果依輸入順序排列,先替工作命名
MDN 說明,每個結果都有 status:成功時是 fulfilled 並含 value,失敗時是 rejected 並含 reason。結果順序依輸入順序,不依完成速度。
只記住「第零項是帳號」很容易在新增 API 後拿錯資料。下面讓每個任務先有名稱,並在同一個索引上配回結果:
async function settleNamed(tasks) { const names = tasks.map((task) => task.name); if (new Set(names).size !== names.length) { throw new Error('task names must be unique'); }
const results = await Promise.allSettled( tasks.map((task) => Promise.resolve().then(() => task.run())), ); return Object.fromEntries(results.map((result, index) => [ names[index], result, ]));}這是文章自己的 wrapper,並非新的內建 API。Promise.resolve().then(...) 讓 run() 在 Promise 鏈中執行,即使它同步 throw,也會成為該任務的 rejected 結果;若直接寫 tasks.map(task => task.run()),同步例外可能在進入 allSettled 前就中斷整個 map。
範例拒絕重複名稱,避免 Object.fromEntries 讓後面的結果蓋掉前面的結果。正式專案可再用 TypeScript 定義各任務的資料型別;先有明確對應,才知道畫面上的錯誤屬於哪個來源。
fetch 要自己判斷 HTTP 錯誤與逾時
fetch 遇到 HTTP 404、500 不會自動 reject。若沒有檢查 response.ok,allSettled 可能把錯誤頁面當作成功資料。以下 helper 在每次呼叫時建立新的 timeout signal:
async function fetchJson(url, timeoutMs = 3_000) { const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); return await response.json();}
const sections = await settleNamed([ { name: 'profile', run: () => fetchJson('/api/profile') }, { name: 'notifications', run: () => fetchJson('/api/notifications') }, { name: 'recommendations', run: () => fetchJson('/api/recommendations') },]);
if (sections.profile.status === 'fulfilled') { console.log('帳號資料', sections.profile.value);} else { console.error('帳號區塊載入失敗', sections.profile.reason);}三個 /api/ 路徑是產品整合示意,請換成實際 endpoint。UI 可讓通知區顯示重試按鈕、推薦區顯示預設內容,帳號區則依產品需求決定是否為必要資料。
必要與選用資料不一定要放在同一組等待:如果帳號決定權限,先確認帳號,再載入依賴該權限的內容;若希望各區塊一完成就呈現,可以在個別任務完成時更新 UI。allSettled 的聚合 Promise 會等全部結束,並不提供逐項串流結果。
timeout 也包含回應本文讀取。詳細的取消原因與 signal 生命週期可看 fetch timeout 的處理方式。重試時要建立新請求與新 signal,不能重用已中止的物件。
用可控制的任務驗證順序與部分失敗
把 settleNamed 放入 settled-check.mjs,附上以下測試,再執行 node settled-check.mjs。本次維護流程已在 Node.js v24.13.0 執行:
import assert from 'node:assert/strict';
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));const completed = [];const data = await settleNamed([ { name: 'slow', run: async () => { await wait(20); completed.push('slow'); return 42; } }, { name: 'broken', run: () => { throw new Error('unavailable'); } }, { name: 'fast', run: async () => { completed.push('fast'); return 7; } },]);
assert.deepEqual(completed, ['fast', 'slow']);assert.deepEqual(Object.keys(data), ['slow', 'broken', 'fast']);assert.equal(data.slow.value, 42);assert.equal(data.broken.status, 'rejected');assert.equal(data.broken.reason.message, 'unavailable');assert.equal(data.fast.value, 7);assert.deepEqual(await settleNamed([]), {});await assert.rejects(settleNamed([ { name: 'same', run: () => 1 }, { name: 'same', run: () => 2 },]));console.log('allSettled checks passed');2026-10-03 維護流程另以本機 HTTP 伺服器確認了成功 JSON、HTTP 503 與慢回應 timeout 可以一起保留各自結果;本次沒有重跑這組 HTTP 測試。這些驗證處理的是 JavaScript 與請求邊界,沒有測試儀表板畫面、登入狀態或跨來源請求。
保留部分成功結果,也限制同時執行數
若通知來源從三個增加到數十個,原本的結果對應仍有用,但需要控制啟動時點。p-limit 官方 README 的介面是 limit(fn):名額可用時才呼叫函式。傳進去的是尚未開始的工作函式,不能先建立全部請求,再期待 limiter 倒回去限制它們。
這段延伸前面的 settleNamed,維持每個名稱的 fulfilled/rejected 結果。run() 必須回傳涵蓋完整操作的 Promise;若啟動背景請求後立刻回傳,名額會過早釋放。任務清單應是沒有空洞的陣列。
在獨立測試資料夾安裝本文查核的版本;p-limit 7.3.3 要求 Node.js 20 以上:
npm install p-limit@7.3.3把前面的 settleNamed 與以下 helper 放入 limited-check.mjs:
import pLimit from 'p-limit';
async function settleNamedLimited(tasks, concurrency) { const limit = pLimit(concurrency); return settleNamed(tasks.map(task => ({ name: task.name, run: () => limit(() => task.run()), })));}例如把原本的 settleNamed([...]) 換成 settleNamedLimited([...], 2),最多同時執行兩個 run()。原先的重複名稱檢查仍在工作啟動前進行。單項失敗會成為 rejected 結果,空出的名額仍可處理下一項;它不會因一項失敗而丟掉其餘結果。
下面測試用手動 gate 控制任務何時結束,不靠網路速度或固定等待時間猜測並行數。接在同一份檔案後執行 node limited-check.mjs:
import assert from 'node:assert/strict';
function deferred() { let resolve; const promise = new Promise(ok => { resolve = ok; }); return { promise, resolve };}
const gates = Array.from({ length: 4 }, deferred);const entered = Array.from({ length: 4 }, deferred);const started = [];let active = 0;let peak = 0;const failure = new Error('第三項失敗');const tasks = gates.map((gate, index) => ({ name: `section-${index}`, run: async () => { started.push(index); active += 1; peak = Math.max(peak, active); entered[index].resolve(); try { await gate.promise; if (index === 2) throw failure; return index * 10; } finally { active -= 1; } },}));
const batch = settleNamedLimited(tasks, 2);await Promise.all([entered[0].promise, entered[1].promise]);assert.deepEqual(started, [0, 1]);assert.equal(active, 2);gates[1].resolve();await entered[2].promise;assert.deepEqual(started, [0, 1, 2]);gates[2].resolve();await entered[3].promise;assert.equal(active, 2);gates[3].resolve();gates[0].resolve();const results = await batch;assert.equal(peak, 2);assert.equal(active, 0);assert.deepEqual(Object.keys(results), tasks.map(task => task.name));assert.equal(results['section-0'].value, 0);assert.equal(results['section-1'].value, 10);assert.equal(results['section-2'].status, 'rejected');assert.equal(results['section-2'].reason, failure);assert.equal(results['section-3'].value, 30);assert.deepEqual(await settleNamedLimited([], 2), {});await assert.rejects(settleNamedLimited([], 0), TypeError);console.log('並行上限、失敗後續處理與名稱對應檢查通過');本次 2026-10-12 維護流程在 macOS、Node.js v24.13.0 與 p-limit 7.3.3 執行上述組合,檢查通過;原本的同步拋錯與結果順序測試也重新執行。這次沒有呼叫真實 API 或測試瀏覽器 UI,先前本機 HTTP 測試的執行日期仍是 2026-10-03。
concurrency = 2 管的是同時未結束的工作數,不是每秒兩次請求。兩個工作很快結束時,一秒內仍可能啟動很多項;遇到 HTTP 429,需另外遵守 API 的速率配額與重試規則。這個 helper 每次建立自己的 limiter,同時呼叫兩批就可能各跑兩項;若多批共享同一個下游配額,應在它們共同的呼叫邊界重用同一個 limiter。
這份範例會為整個清單建立排隊項目,沒有處理無限來源或大量資料的記憶體背壓;也沒有新增取消功能。任務仍需自己的 timeout,否則卡住的工作會一直占著名額。若要在全部工作結束後才清理共享資源,可接著看 Promise.all 失敗後的等待與清理邊界。
allSettled 仍會卡住,也不會替你省請求
只要有一項 Promise 永遠 pending,聚合就會一直等待。因此 timeout 要放在會停滯的任務上;只在外面用 Promise.race 停止等待,底層工作仍可能繼續執行。
另外,tasks.map 會把所有工作建立出來。十項和一千項都不會因為 allSettled 自動變成每次五項;大量請求要另用批次或 concurrency limiter。也不要用這個 wrapper 把必須依序執行的資料庫寫入、建立訂單和付款改成並行。
Promise.all 在第一項 reject 時會較早回報錯誤,但沒有取消其他 Promise。選擇兩者的核心是結果處理方式,不能拿它們作為資源取消或併發控制機制。
要上線前,至少讓每個失敗結果都有對應的 UI 或紀錄。若只是把 rejected 全部濾掉,沒有說明缺了哪些資料,使用者看到的「成功畫面」仍可能是不完整的。
參考資料: