鴻蒙異步處理從入門到實戰：Promise、async/await、并發池、超時重試全套攻略

在這里插入圖片描述

摘要（介紹目前的背景和現狀）

在鴻蒙（HarmonyOS）里，網絡請求、文件操作、數據庫訪問這類 I/O 都是異步的。主流寫法跟前端類似：Promise、async/await、回調。想把 app 做得“流暢且不阻塞”，核心在于：合理用 async/await、把錯誤兜住、并發別亂開、遇到慢接口要有“超時/取消/重試”機制。

引言（介紹目前的發展情況和場景應用）

從 API 設計上看，鴻蒙的系統能力（比如 @ohos.net.http、@ohos.file.fs、@ohos.webSocket 等）都提供了 Promise 風格的方法。我們在實際項目里，通常會封一層“請求工具模塊”，加上統一的超時、重試、攔截日志，然后在頁面中以 async/await 的寫法去調用。本文用一個小 Demo 把這些串起來：頁面里點幾個按鈕，分別觸發請求、并發、取消、文件讀寫等操作，看得到結果和錯誤提示。

異步基礎與風格選型

Promise 鏈式 vs. async/await

鏈式寫法好處是可控的組合（then/catch/finally），缺點是可讀性差。
async/await 寫起來更像同步代碼，可讀性強，但別忘了 try/catch。
兩者可以混用：底層工具用 Promise 封裝，業務層面用 async/await 調用。

代碼示例：Promise 鏈式 & async/await 對比

import http from '@ohos.net.http';// 鏈式寫法
function fetchTodoByIdChained(id: number) {const client = http.createHttp();return client.request(`https://jsonplaceholder.typicode.com/todos/${id}`, {method: http.RequestMethod.GET,connectTimeout: 5000,readTimeout: 5000,}).then(res => JSON.parse(res.result as string)).finally(() => client.destroy());
}// async/await 寫法
async function fetchTodoByIdAsync(id: number) {const client = http.createHttp();try {const res = await client.request(`https://jsonplaceholder.typicode.com/todos/${id}`, {method: http.RequestMethod.GET,connectTimeout: 5000,readTimeout: 5000,});return JSON.parse(res.result as string);} finally {client.destroy();}
}

一個可運行的 Demo（頁面 + 工具模塊）

結構建議：
features/async/AsyncDemoPage.ets（頁面）
features/async/asyncKit.ts（工具模塊：超時、取消、重試、并發池、文件讀寫）

工具模塊：`asyncKit.ts`

// features/async/asyncKit.ts
import http from '@ohos.net.http';
import fs from '@ohos.file.fs';/** 一次 HTTP 請求，帶超時控制 */
export async function httpGet<T = unknown>(url: string, timeoutMs = 6000): Promise<T> {const client = http.createHttp();try {const req = client.request(url, {method: http.RequestMethod.GET,connectTimeout: timeoutMs,readTimeout: timeoutMs,});// 雙保險：用 Promise.race 再做一層超時const res = await Promise.race([req,delayReject(timeoutMs, new Error(`Timeout after ${timeoutMs}ms`))]);const txt = (res as http.HttpResponse).result as string;return JSON.parse(txt) as T;} finally {client.destroy();}
}/** 延遲 resolve/reject */
export function delay(ms: number): Promise<void> {return new Promise(resolve => setTimeout(resolve, ms));
}
export function delayReject<T = never>(ms: number, err: Error): Promise<T> {return new Promise((_, reject) => setTimeout(() => reject(err), ms));
}/** 重試：指數退避 */
export async function withRetry<T>(fn: () => Promise<T>,attempts = 3,baseDelayMs = 300
): Promise<T> {let lastErr: unknown;for (let i = 0; i < attempts; i++) {try {return await fn();} catch (e) {lastErr = e;if (i < attempts - 1) {const backoff = baseDelayMs * Math.pow(2, i); // 300, 600, 1200...await delay(backoff);}}}throw lastErr;
}/** 并發池：限制并發數量，避免把網絡或設備打滿 */
export async function runWithPool<T>(tasks: Array<() => Promise<T>>,concurrency = 3
): Promise<T[]> {const results: T[] = [];let index = 0;const workers: Promise<void>[] = [];async function worker() {while (index < tasks.length) {const cur = index++;try {const r = await tasks[cur]();results[cur] = r;} catch (e) {// 不中斷整體：把錯誤拋出去給上層處理也可results[cur] = e as any;}}}for (let i = 0; i < Math.min(concurrency, tasks.length); i++) {workers.push(worker());}await Promise.all(workers);return results;
}/** 取消控制（簡版）：通過外部標記與自定義取消邏輯 */
export class CancelToken {private _cancelled = false;cancel() { this._cancelled = true; }get cancelled() { return this._cancelled; }
}/** 支持“軟取消”的 GET：每步檢查 token，早停 */
export async function httpGetCancellable<T = unknown>(url: string,token: CancelToken,timeoutMs = 6000
): Promise<T> {if (token.cancelled) throw new Error('Cancelled before start');const client = http.createHttp();try {const req = client.request(url, {method: http.RequestMethod.GET,connectTimeout: timeoutMs,readTimeout: timeoutMs,});const res = await Promise.race([req,delayReject(timeoutMs, new Error(`Timeout after ${timeoutMs}ms`))]);if (token.cancelled) throw new Error('Cancelled after response');const txt = (res as http.HttpResponse).result as string;return JSON.parse(txt) as T;} finally {client.destroy();}
}/** 文件讀寫示例（Promise 風格） */
export async function writeTextFile(path: string, content: string): Promise<void> {const file = await fs.open(path, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);try {await fs.write(file.fd, content);} finally {await fs.close(file.fd);}
}export async function readTextFile(path: string): Promise<string> {const file = await fs.open(path, fs.OpenMode.READ_ONLY);try {const stat = await fs.stat(path);const buf = new ArrayBuffer(stat.size);await fs.read(file.fd, buf);return String.fromCharCode(...new Uint8Array(buf));} finally {await fs.close(file.fd);}
}

頁面：`AsyncDemoPage.ets`

// features/async/AsyncDemoPage.ets
import promptAction from '@ohos.promptAction';
import { httpGet, withRetry, runWithPool, CancelToken, httpGetCancellable, writeTextFile, readTextFile } from './asyncKit';@Entry
@Component
struct AsyncDemoPage {@State log: string = '';token: CancelToken = new CancelToken();private append(msg: string) {this.log = `[${new Date().toLocaleTimeString()}] ${msg}\n` + this.log;}async onFetchOnce() {try {const data = await httpGet<any>('https://jsonplaceholder.typicode.com/todos/1', 4000);this.append(`單次請求成功：${JSON.stringify(data)}`);promptAction.showToast({ message: '請求成功' });} catch (e) {this.append(`單次請求失敗：${(e as Error).message}`);promptAction.showToast({ message: '請求失敗' });}}async onFetchWithRetry() {try {const data = await withRetry(() => httpGet<any>('https://jsonplaceholder.typicode.com/todos/2', 2000), 3, 300);this.append(`重試成功：${JSON.stringify(data)}`);} catch (e) {this.append(`重試最終失敗：${(e as Error).message}`);}}async onParallelLimited() {const ids = Array.from({ length: 8 }, (_, i) => i + 1);const tasks = ids.map(id => () => httpGet<any>(`https://jsonplaceholder.typicode.com/todos/${id}`, 5000));const results = await runWithPool(tasks, 3);const ok = results.filter(r => !(r instanceof Error)).length;this.append(`并發池完成：成功 ${ok}/${results.length}`);}async onCancellable() {this.token = new CancelToken();const p = httpGetCancellable<any>('https://jsonplaceholder.typicode.com/todos/3', this.token, 6000);setTimeout(() => {this.token.cancel();this.append('已發出取消信號');}, 200); // 模擬用戶取消try {const data = await p;this.append(`取消示例返回：${JSON.stringify(data)}`);} catch (e) {this.append(`取消示例結束：${(e as Error).message}`);}}async onFileReadWrite() {try {const path = `/data/storage/el2/base/files/async_demo.txt`;await writeTextFile(path, `hello @ ${Date.now()}`);const text = await readTextFile(path);this.append(`文件讀寫成功：${text}`);} catch (e) {this.append(`文件讀寫失敗：${(e as Error).message}`);}}build() {Column() {Text('異步請求 Demo').fontSize(22).fontWeight(FontWeight.Bold).margin({ bottom: 8 })Row({ space: 8 }) {Button('單次請求').onClick(() => this.onFetchOnce())Button('重試請求').onClick(() => this.onFetchWithRetry())Button('并發池').onClick(() => this.onParallelLimited())}Row({ space: 8 }) {Button('可取消請求').onClick(() => this.onCancellable())Button('文件讀寫').onClick(() => this.onFileReadWrite())}.margin({ top: 8 })Scroll() {Text(this.log).fontSize(14).maxLines(1000)}.margin({ top: 12 }).height('60%').width('100%')}.padding(16).backgroundColor('#FFFFFF').width('100%').height('100%')}
}

說明：

頁面按鈕觸發不同的異步策略：單次請求、帶重試、并發池、軟取消、文件讀寫。
promptAction.showToast 做輕提示；日志區能看到詳細過程。
“可取消請求”里用自定義 CancelToken 做軟取消，避開直接中斷底層請求可能帶來的不一致。

典型模式與落地細節

超時與取消

代碼示例：超時包裝 + 軟取消要點

超時：Promise.race([真實請求, delayReject(...)])
取消：在關鍵點檢查 token.cancelled，拋錯早停，外層統一善后

// 見 asyncKit.ts -> httpGet / httpGetCancellable

并發與限流

Promise.all 一把梭容易把對端打掛；建議并發池控制并發數（如 3~5 個）。
對失敗任務可以部分重試，同時采用 allSettled 匯總成功/失敗。

// 見 asyncKit.ts -> runWithPool

重試與指數退避

固定重試間隔會形成“重試風暴”；指數退避（300ms、600ms、1200ms…）更溫和。
重試只針對冪等操作（GET/查詢），避免對寫操作造成重復副作用。

// 見 asyncKit.ts -> withRetry

應用場景舉例（2~3 個）

場景一：列表頁首屏并發加載（配置 + 資源 + 推薦）

需求：首屏要同時拉 3 個接口，但又不希望對端被瞬時壓垮。
做法：把 3 個任務丟給并發池，限制并發為 2；任一失敗也不要阻塞頁面，可先部分渲染。

import { runWithPool } from './asyncKit';
import { httpGet } from './asyncKit';async function loadHomeFirstScreen() {const tasks = [() => httpGet('/api/config'),() => httpGet('/api/resources'),() => httpGet('/api/recommend'),];const results = await runWithPool(tasks, 2); // 并發 2const [config, resources, recommend] = results;// 容錯：失敗的部分用降級數據或空態return {config: config instanceof Error ? {} : config,resources: resources instanceof Error ? [] : resources,recommend: recommend instanceof Error ? [] : recommend,};
}

要點：

“先出結果的先渲染”，把首屏時間做好；失敗項做降級。
后續滾動或次要模塊慢慢補齊。

場景二：慢接口 + 超時 + 重試 + 兜底緩存

需求：某接口偶發超時，需要給用戶“盡量穩”的體驗。
做法：請求超時后進行指數退避重試；重試多次失敗，回退到本地緩存。

import { withRetry, httpGet } from './asyncKit';async function fetchUserProfile() {try {const data = await withRetry(() => httpGet('/api/user/profile', 2500),3, // 3 次機會400 // 初始退避);// 成功更新本地緩存await saveCache('user_profile', data);return data;} catch {// 失敗則讀取兜底緩存const cached = await loadCache('user_profile');if (cached) return cached;throw new Error('用戶信息獲取失敗且無緩存');}
}// 這里用文件做個簡單緩存示意
import { writeTextFile, readTextFile } from './asyncKit';
async function saveCache(key: string, data: any) {await writeTextFile(`/data/storage/el2/base/files/${key}.json`, JSON.stringify(data));
}
async function loadCache(key: string) {try {const txt = await readTextFile(`/data/storage/el2/base/files/${key}.json`);return JSON.parse(txt);} catch {return null;}
}

要點：

重試要有上限，并且冪等。
緩存是兜底，不保證新鮮，但能穩住體驗。

場景三：搜索輸入節流 + 可取消的后端查詢

需求：用戶在搜索框頻繁輸入，我們只想發“最后一次”的請求，之前的要取消。
做法：輸入變化時創建新的 CancelToken，舊的 token 取消；配合小延遲做節流。

import { CancelToken, httpGetCancellable, delay } from './asyncKit';let currentToken: CancelToken | null = null;export async function searchSmart(q: string) {// 簡單節流/防抖：等待 200ms 看輸入是否穩定await delay(200);// 取消上一次if (currentToken) currentToken.cancel();currentToken = new CancelToken();try {const res = await httpGetCancellable(`/api/search?q=${encodeURIComponent(q)}`, currentToken, 5000);return res;} catch (e) {if ((e as Error).message.includes('Cancelled')) {// 被取消視為正常流程，不提示return null;}throw e;}
}