专栏：HarmonyOS 三方库适配实战（12/30）
核心问题：回调、Promise、异常和错误码混用时，调用方怎样稳定处理失败、取消与超时？

摘要

三方库能编译，不代表调用契约清楚。同步函数抛异常、异步函数返回错误码、回调又把错误放在字符串里，会迫使每个调用方重复猜测。本文把公开异步 API 统一为Promise<T>，把失败统一为带code的TextToolError，并用显式OperationContext表达取消和截止时间。相关代码已进入教学 HAR 并通过目标 SDK 编译；由于没有设备和真实耗时任务，本篇不声称验证了调度延迟或线程行为。

先固定四个问题

为每个公开异步接口写清：

1. 成功值是什么；
2. 失败通过throw/reject还是返回联合结果；
3. 调用方怎样取消；
4. 超时从何时开始计算，超时后底层任务是否真的停止。

图 1：输入校验、业务失败、取消和超时都映射到稳定错误码。

错误类型不要暴露底层偶然细节

教学库定义一个窄错误集合：

exportenumTextErrorCode{INVALID_INPUT='INVALID_INPUT',CANCELLED='CANCELLED',TIMEOUT='TIMEOUT'}exportclassTextToolErrorextendsError{readonlycode:TextErrorCodeconstructor(code:TextErrorCode,message:string){super(message)this.code=code}}

code供程序判断，message供日志和开发者阅读。不要让调用方匹配底层英文报错文本，也不要把本地绝对路径、系统句柄或上游堆栈直接变成公共协议。

用显式上下文表达取消与截止时间

exportclassOperationContext{readonlydeadlineMs:numbercancelled:boolean=falseconstructor(deadlineMs:number=0){this.deadlineMs=deadlineMs}cancel():void{this.cancelled=true}}

异步入口在关键边界检查状态：

exportasync