TypeScript using 声明管理异步资源的释放

TypeScript 中，如果资源的关闭动作需要异步等待，应使用 await using 并提供 Symbol.asyncDispose 方法。普通 using 管理同步释放，不能仅因初始化表达式里出现 await，就认为离开作用域时也会等待异步关闭。

TypeScript 官方地址：https://www.typescriptlang.org/

基线指标：先定义“资源释放完成”

假设导出任务拿到一个会话，写入内容后需要等待 flush 完成。如果函数先返回、flush 仍悬空，调用方可能误以为任务已经完成。这里关注的是完成契约与资源占用，不预设改用新语法会提高吞吐。

比较前可定义三个指标：业务任务结束后的未释放资源数量、从开始关闭到关闭 Promise 落定的耗时、业务失败和清理失败的独立记录数。本文没有执行压测，也没有真实服务的基线数值；下面给出可供项目采用的代码与测量口径。

假设：获取资源与释放资源是两次不同的等待

await using 可用于允许 await 的位置，例如 async 函数内部。它优先使用 Symbol.asyncDispose，缺少该方法时可退回 Symbol.dispose；不过若同步 dispose 错误地返回 Promise，不能依靠这种退回来等待其中的异步工作。需要异步清理时就明确实现异步协议。

改动点：为现有关闭方法提供适配器

以下示例使用原创 ExportSession 模型，flush 由调用方注入。它不依赖某个导出 SDK，也不创建真实文件。项目可把实际关闭函数传给适配器，同时确认该函数返回的 Promise 能准确表达完成或失败。

// flush 是外部资源的异步关闭动作；缓存 Promise 防止重复调用。
class ExportSession implements AsyncDisposable {
  private closePromise?: Promise;
  private records: string[] = [];

  constructor(private readonly flush: (rows: readonly string[]) => Promise) {}

  append(row: string): void {
    if (this.closePromise) throw new Error("会话正在关闭");
    this.records.push(row);
  }

  [Symbol.asyncDispose](): Promise {
    if (!this.closePromise) {
      // 先冻结本次快照，再将同步抛错也转换成被拒绝的 Promise。
      const snapshot = this.records.slice();
      this.closePromise = Promise.resolve().then(() => this.flush(snapshot));
    }
    return this.closePromise;
  }
}

async function exportRows(
  rows: readonly string[],
  flush: (rows: readonly string[]) => Promise
): Promise {
  await using session = new ExportSession(flush);
  for (const row of rows) session.append(row);
  // 离开作用域要等待释放；关闭失败会使此函数拒绝，而非成功返回数量。
  return rows.length;
}

async function demonstrate(): Promise {
  // 教学替身不写真实文件，只模拟一个可以异步完成的关闭入口。
  return await exportRows(["alpha", "beta"], async (rows) => {
    await Promise.resolve();
    if (rows.length === 0) throw new Error("没有可提交内容");
  });
}
// 上层应 await demonstrate() 并捕获拒绝，不要留下无人处理的 Promise。

这里的 Promise 缓存是一项适配器设计选择，不是语法自动提供的幂等能力。一次关闭失败后再调用，返回的仍是失败的 Promise；不能把它理解为自动重试。是否允许重试、是否还保留外部资源，应由实际服务契约决定。

同一作用域中登记多个资源时，清理按登记的相反顺序进行。依赖另一个资源的对象通常应后创建，使它先释放。不要在 using 声明之后把资源传给仍在后台运行的未等待任务，也不要把资源自身返回给调用方继续使用；作用域退出后它应已被释放。

异常处理：同时保留业务失败和清理失败

业务代码抛错后仍会进入释放；如果释放也抛错，错误信息可能以 SuppressedError 组合。其 error 表达新的清理错误，suppressed 保存先前错误，多个释放失败还可能形成嵌套结构。只打印最外层 message 容易丢失原业务故障。

// 递归展示组合异常；实际日志系统应另行做脱敏与结构化字段记录。
function describeFailure(error: unknown): string[] {
  if (typeof SuppressedError !== "undefined" && error instanceof SuppressedError) {
    return [
      "清理错误：" + String(error.error),
      ...describeFailure(error.suppressed)
    ];
  }
  return ["原始错误：" + String(error)];
}

该检查针对当前运行时的 SuppressedError。若编译辅助代码在缺少原生构造器时生成替代错误对象，instanceof 未必识别它，应按所用兼容层的错误模型记录字段。不要为恢复“成功”而无条件吞掉关闭错误。获取函数如果在返回资源前失败，其内部部分初始化资源仍需要由获取函数自己回收，await using 不能释放尚未成功登记的对象。

对比方法：衡量占用与完成时间，而不是语法长度

项目比较手写 try/finally 与 await using 时，使用相同的输入、并发量、资源实现和故障注入条件。至少覆盖正常完成、业务抛错、关闭抛错以及两者同时失败；在资源获取和释放入口记录占用计数，在关闭 Promise 完成后扣减。关闭失败时是否扣减还应依赖底层资源是否实际释放，不能只根据函数已退出推断。

能够下的结论是：释放责任从散落的 finally 调用收束到作用域与协议。是否降低泄漏率、是否影响尾延迟，需要项目数据支持，本文不提供未经测量的提升百分比。

环境条件：类型声明和运行时能力分别准备

TypeScript 5.2 引入相关支持，但类型通过不表示目标环境天然具备所有运行时能力。以输出到 ES2022 的项目为例，可以在现有 tsconfig 中合并以下选项；若项目已有 DOM 或其他 lib，请保留需要的项。

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true
  }
}

target 控制输出目标，ESNext.Disposable 提供资源协议的类型声明，strict 用于类型约束。JSON 不支持注释，字段含义在这里说明。运行时还要具备或预先补齐 Symbol.dispose、Symbol.asyncDispose 以及所用错误处理能力；lib 不会安装 polyfill。转译 using 语法也不能替代底层 SDK 的真实关闭实现。

写了 using 后垃圾回收会更快吗？

不能这样保证。资源协议用于明确关闭动作，JavaScript 对象内存仍由垃圾回收管理。

在块内提前 return 会跳过释放吗？

不会跳过该作用域的正常释放机制；异步关闭失败时，调用方收到的可能是拒绝，而不是原本要返回的值。

可选资源是 null 怎么办？

null 或 undefined 可作为空资源，不调用释放方法。不要因此忽略获取失败和部分初始化的回收责任。

参考：TypeScript 资源管理说明、await using 语义、SuppressedError 字段。