鸿蒙异步处理从入门到实战：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;}
}