尧图网页设计 
大多数服务端资源泄漏都源于不完整的清理序列——当多个异步资源在生产环境中未能正确清理时。数据库连接关闭了但 Redis 锁从未释放。请求结束后文件句柄仍然存在因为一个上游错误短路了清理链。这些失败悄无声息地发生直到连接池耗尽或磁盘配额告警在数小时后触发。团队常用的手工模式看起来像是对每个资源嵌套 try-finally 块。这种方法在真实生产条件下会崩溃清理代码中的错误会阻止下游资源释放释放顺序变得隐式且脆弱而且资源超过三个时代码就变得不可读。TypeScript 的AsyncDisposableStack为多资源清理提供了显式协调具备手动链无法比拟的保证释放顺序和错误聚合能力。关键要点AsyncDisposableStack通过一个统一的释放点协调多个异步资源即使在单个操作失败时也能保证逆序清理。手工 try-finally 链在生产错误条件下会崩溃因为清理代码中的错误会阻止下游资源释放。adopt()方法注册任何带有清理函数的资源defer()将任意异步工作延迟到释放时执行move()在栈之间转移所有权。释放始终按注册的逆序执行LIFO错误会聚合进SuppressedError链保留每一个失败上下文。AsyncDisposableStack在请求作用域的资源管理中表现出色例如数据库连接、分布式锁和文件句柄无论请求结果如何都必须原子地释放。理解 AsyncDisposableStack协调多个 DisposableAsyncDisposableStack 实现了AsyncDisposable接口并提供三种注册方法团队可以用它们构建复杂的清理序列。理解这些方法的差异决定了哪种模式适合给定的生产场景。adopt()方法接收一个资源值和一个清理函数注册清理逻辑的同时原样返回资源。这种方法适用于没有原生实现Symbol.asyncDispose的资源。清理函数接收原始资源值作为参数从而支持连接池归还或锁释放这类需要原始引用的模式。const stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (conn) { await conn.release(); });use()方法直接注册一个已存在的AsyncDisposable对象委托给它的Symbol.asyncDispose实现。当资源已经实现了释放协议时这个方法创建最自然的集成。栈在自身的释放阶段会调用已注册对象的[Symbol.asyncDispose]()。class ManagedLock implements AsyncDisposable { async [Symbol.asyncDispose]() { await this.release(); } } const lock await acquireLock(); stack.use(lock); // 委托给 lock[Symbol.asyncDispose]()defer()方法把任意异步工作调度到释放阶段执行而不绑定到特定的资源值。这种模式处理依赖闭包状态、或无论资源分配是否成功都需要运行的清理操作。延迟函数与已采纳资源一起按注册逆序执行。let tempFile: string | null null; stack.defer(async () { if (tempFile) { await fs.unlink(tempFile); } }); tempFile await createTempFile();释放顺序严格遵循后进先出LIFO语义。一个栈先采纳数据库连接、再采纳 Redis 锁、最后采纳文件句柄那么释放时先关闭文件句柄其次释放锁最后归还连接。这个顺序很重要因为后面的资源往往依赖更早的资源在自己清理期间仍然可用。move()方法把全部已注册资源从一个栈转移到另一个栈使源栈进入已释放状态。这个操作支持这样的模式一个函数构建一组资源并把所有权返回给调用方。调用方的栈承担清理责任原始栈则变为惰性状态。async function setupResources() { const stack new AsyncDisposableStack(); stack.adopt(await openConnection(), closeConnection); stack.adopt(await acquireLock(), releaseLock); return stack.move(); // 转移所有权原始栈现在已释放 } await using resources await setupResources();disposed属性表示栈是否已经执行了释放序列。释放完成后任何尝试采纳新资源的操作都会抛出ReferenceError。这个守卫防止在清理已经开始后注册资源那会制造不可能实现的清理保证。真实服务端场景数据库连接、Redis 锁和文件句柄的清理一个处理文件上传的生产 API 端点展示了 AsyncDisposableStack 解决的协调问题。该操作需要数据库事务来写入元数据、需要 Redis 锁来防止同一文件的并发处理、需要一个临时文件句柄来暂存上传内容。这三个资源必须在请求完成或失败时原子地释放。手工方式串联 try-finally 块制造了嵌套的错误处理上下文这些上下文难以维护并且当中间操作出错时无法保证完整清理。async function processUpload(fileData: Buffer, metadata: UploadMetadata) { const connection await pool.connect(); try { await connection.query(BEGIN); const lockKey upload:${metadata.id}; const lock await redisClient.lock(lockKey, 30000); try { const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, fileData); try { // 处理文件... await connection.query(INSERT INTO uploads ..., [metadata]); await connection.query(COMMIT); } finally { await fs.unlink(tempPath); // 如果这里抛错锁永远不会释放 } } finally { await lock.release(); // 如果这里抛错连接永远不会归还 } } finally { connection.release(); } }这里的失败模式很隐蔽但代价高昂。fs.unlink()中的一个错误会阻止锁释放执行。锁会在其 30 秒 TTL 期间一直持有而连接已经归还到连接池。同一文件的并发上传会被阻塞直到锁过期。临时文件残留在磁盘上。所有这些失败都不会作为错误浮出水面因为外层的 finally 块从未执行。AsyncDisposableStack 消除了嵌套作用域并保证无论单个失败如何所有清理都会执行。async function processUpload(fileData: Buffer, metadata: UploadMetadata) { await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (conn) { await conn.query(ROLLBACK).catch(() {}); // 尽力回滚 conn.release(); }); await connection.query(BEGIN); const lockKey upload:${metadata.id}; const lock await redisClient.lock(lockKey, 30000); stack.adopt(lock, async (l) await l.release()); const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, fileData); stack.defer(async () { await fs.unlink(tempPath).catch(() {}); // 确保尝试删除 }); // 处理文件... await connection.query(INSERT INTO uploads ..., [metadata]); await connection.query(COMMIT); // 栈按逆序释放删除临时文件 - 释放锁 - 归还连接 }当函数作用域退出时栈先释放延迟的 unlink然后释放锁最后归还连接。任何清理操作中的错误都不会阻止其他操作执行。栈会把错误聚合进SuppressedError链为日志记录和调试保留每一个失败上下文。这种模式可以自然地扩展到更复杂的场景。一个打开多个文件句柄的批处理作业可以在每次打开后立即采纳它们确保即使后续打开失败也能清理。一个分布式事务协调器可以把补偿动作注册为 defer() 调用无论提交是否成功都保证尝试回滚。AsyncDisposableStack 与手工 try-finally 链错误处理与保证手工 try-finally 链与 AsyncDisposableStack 之间的对比揭示了错误传播和清理保证方面的根本差异这些差异会影响生产可靠性。手工链按照嵌套结构的相反顺序执行清理但前提是更早的清理没有抛错。内层 finally 块中的错误会阻止外层 finally 块执行导致上游资源泄漏。这种失败模式制造出静默的资源耗尽在触发错误数小时之后才显现。AsyncDisposableStack 保证每个已注册的清理都会执行无论其他清理是否失败。当某个释放操作抛错时栈会捕获该错误、继续释放其余资源并把所有错误聚合进一个SuppressedError实例。主错误成为被抛出的异常后续错误作为suppressed属性链挂接。async function demonstrateErrorAggregation() { await using stack new AsyncDisposableStack(); stack.defer(async () { throw new Error(First cleanup failed); }); stack.defer(async () { throw new Error(Second cleanup failed); }); // 作用域退出时两个错误都会聚合 // SuppressedError: Second cleanup failed // suppressed: Error: First cleanup failed }错误聚合模式保留了每一个失败上下文而不是把次要错误隐藏在第一个异常后面。日志基础设施可以遍历suppressed链捕获完整的清理失败序列。这种可见性在生产环境中很重要——数据库超时可能触发一连串下游清理失败每一个都需要单独调查。手工链要求在每个 finally 块中显式处理错误以防止错误传播中断清理。这种方法增加了样板代码而且仍然缺少 AsyncDisposableStack 自动提供的聚合语义。// 手工错误处理近似 AsyncDisposableStack 的行为 let connectionError: Error | null null; try { // ... 使用 connection } finally { try { connection.release(); } catch (error) { connectionError error as Error; } try { await lock.release(); } catch (error) { if (connectionError) { // 手工错误聚合——冗长且易错 } } }保证上的差异还延伸到释放顺序的可预测性。手工链只有在异常处理尊重嵌套顺序时才会按逆序执行清理。一次改变 try 块顺序的重构就会隐式改变清理语义。AsyncDisposableStack 通过注册顺序让释放顺序变得显式把清理序列从词法结构中解耦出来。生产模式adopt()、defer() 和 move() 处理复杂清理流程真实生产代码需要的模式超出了简单的资源采纳。条件资源获取、所有权转移、依赖操作结果的清理这些都会出现在服务端代码库中。AsyncDisposableStack 的三种注册方法通过组合处理这些场景。adopt()模式适用于来自工厂或连接池、需要自定义清理函数的资源。来自连接池的数据库连接、来自连接管理器的 Redis 客户端、具有特定关闭序列的 HTTP 客户端都符合这种模式。清理函数接收资源值从而能访问资源类型暴露的方法。async function withDatabaseTransactionT( fn: (client: PoolClient) PromiseT ): PromiseT { await using stack new AsyncDisposableStack(); const client await pool.connect(); stack.adopt(client, async (c) { await c.query(ROLLBACK).catch(() {}); c.release(); }); await client.query(BEGIN); const result await fn(client); await client.query(COMMIT); return result; }defer()模式处理依赖条件执行或闭包状态的清理。一个只在文件处理成功时才需要删除的临时目录可以使用 defer()因为决策逻辑发生在资源创建之后。作用域退出时的指标上报、缓存失效和 webhook 通知都符合 defer() 模式。async function processWithTempDir(files: File[]) { await using stack new AsyncDisposableStack(); const tempDir await fs.mkdtemp(/tmp/process-); let shouldKeep false; stack.defer(async () { if (!shouldKeep) { await fs.rm(tempDir, { recursive: true }); } }); // 处理文件... if (allFilesValid) { shouldKeep true; } }move()模式在函数构建一组资源并返回给调用方时转移所有权。这种模式出现在构建复杂资源图的工厂函数中其中清理责任必须原子地转移。没有 move()工厂要么在返回前释放资源阻止调用方使用要么泄漏清理责任。一个实际例子展示了 move() 在数据库迁移运行器中的用法为多个数据库打开连接并把协调好的清理返回给迁移编排器。async function setupMigrationEnvironment() { const stack new AsyncDisposableStack(); const primary await connectPrimary(); stack.adopt(primary, async (conn) await conn.close()); const replica await connectReplica(); stack.adopt(replica, async (conn) await conn.close()); const lockClient await redis.connect(); stack.adopt(lockClient, async (client) await client.quit()); return { primary, replica, lockClient, cleanup: stack.move(), // 调用方拥有清理权 }; } async function runMigrations() { const env await setupMigrationEnvironment(); await using cleanup env.cleanup; // 采纳转移过来的资源 // 使用 env.primary, env.replica, env.lockClient // 所有资源在 cleanup 作用域退出时释放 }组合这些模式可以处理请求作用域资源池这类场景中间件建立一个栈处理器在请求处理期间采纳资源中间件在响应完成时释放所有东西。栈提供了让这种模式可靠的协调点。常见陷阱释放顺序、异步时序以及 dispose() 实际返回什么采用 AsyncDisposableStack 的团队会遇到三种失败模式它们源于对释放语义的错误假设。理解这些陷阱可以避免生产 bug。释放顺序陷阱发生在代码假设注册顺序与清理需求一致、但后面的资源依赖更早资源保持可用时。一个向数据库连接写入的文件句柄必须在连接归还连接池之前关闭这就要求按与依赖关系相反的顺序采纳。解决方案是让采纳顺序与依赖顺序相反。先采纳连接再采纳依赖它的资源。释放按逆序执行在依赖的资源所依赖的连接被关闭之前先关闭依赖资源。// 错误——连接在文件释放需要它之前就被关闭了 await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (c) c.release()); const file await openFile(connection); stack.adopt(file, async (f) { await f.writeMetadata(connection); // 连接已经被释放了 await f.close(); }); // 正确——文件先于它所依赖的连接关闭 await using stack new AsyncDisposableStack(); const connection await pool.connect(); const file await openFile(connection); stack.adopt(file, async (f) { await f.writeMetadata(connection); // 连接仍然可用 await f.close(); }); stack.adopt(connection, async (c) c.release());异步时序陷阱源于期望await using的释放会在下一条语句执行前完成。释放发生在作用域退出时这意味着当前作用域中的所有代码都会在释放开始前运行。一个常见错误是采纳一个资源、使用它然后在它被采纳的那个作用域退出之后尝试访问它。let connection: PoolClient; { await using stack new AsyncDisposableStack(); connection await pool.connect(); stack.adopt(connection, async (c) c.release()); // 释放还没有发生 } // 释放在这里完成——连接已释放 await connection.query(SELECT 1); // 错误连接已经被释放正确的模式是让资源的使用与管理它的栈保持在同一个作用域内。需要活得比分配作用域更长的资源需要一个覆盖更长生命周期的父栈。释放返回值陷阱发生在代码期望await stack.dispose()返回一个表示成功或失败的值时。dispose() 方法返回void出错时抛出异常与Symbol.asyncDispose语义相同。需要区分成功释放与释放错误的代码必须用 try-catch 包裹调用。// 错误——dispose() 返回 void不是状态 const result await stack.dispose(); if (result.success) { /* ... */ } // 正确——通过异常处理释放错误 try { await stack.dispose(); // 所有清理都成功了 } catch (error) { if (error instanceof SuppressedError) { // 访问 error.suppressed 获取次要失败 } }一个相关的陷阱是把栈当作释放后仍可复用。一旦stack.dispose()完成栈进入已释放状态此时stack.disposed true。任何尝试采纳新资源的操作都会抛出ReferenceError。需要多个清理阶段的代码必须为每个阶段创建独立的栈。与 Express 中间件集成请求作用域的资源管理Express 中间件展示了 AsyncDisposableStack 在请求作用域资源协调中的价值多个资源必须在响应完成时释放无论成功还是失败。一个建立栈、在请求处理期间填充它、并在响应结束时保证释放的中间件解决了影响长驻服务器的资源泄漏问题。这种模式在早期中间件中把一个 AsyncDisposableStack 挂到请求对象上允许处理器在整个请求生命周期中采纳资源。一个收尾中间件或错误处理器确保在响应关闭时释放。import express from express; import { AsyncDisposableStack } from node:async_hooks; interface ResourceRequest extends express.Request { resources: AsyncDisposableStack; } function resourceMiddleware( req: express.Request, res: express.Response, next: express.NextFunction ) { const resourceReq req as ResourceRequest; resourceReq.resources new AsyncDisposableStack(); res.on(finish, async () { await resourceReq.resources.dispose().catch((error) { console.error(Resource cleanup failed:, error); }); }); next(); } app.use(resourceMiddleware); app.post(/api/upload, async (req: express.Request, res: express.Response) { const resourceReq req as ResourceRequest; // 采纳数据库连接 const connection await pool.connect(); resourceReq.resources.adopt(connection, async (c) c.release()); // 获取分布式锁 const lockKey upload:${req.body.id}; const lock await redisClient.lock(lockKey, 30000); resourceReq.resources.adopt(lock, async (l) await l.release()); // 创建临时文件 const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, req.body.data); resourceReq.resources.defer(async () { await fs.unlink(tempPath).catch(() {}); }); // 处理上传... await processUpload(connection, tempPath); res.json({ status: success }); // 响应结束时资源释放 });这种模式自动处理错误情况。processUpload()中的异常会触发 Express 错误处理它仍然会发出触发释放的finish事件。无论请求成功与否数据库连接都会归还连接池、锁会释放、临时文件会删除。这种方法可以扩展到 WebSocket 连接、流式响应和长轮询端点这些场景中资源必须在较长时间内保持存活。一个连接升级处理器可以把 socket 及相关资源采纳进一个栈在 socket 关闭时释放。import { WebSocketServer } from ws; wss.on(connection, async (ws) { await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (c) c.release()); const subscription await pubsub.subscribe(updates); stack.adopt(subscription, async (s) await s.unsubscribe()); ws.on(message, async (data) { const result await connection.query(INSERT INTO messages ..., [data]); await pubsub.publish(updates, result.rows[0]); }); subscription.on(message, (msg) { ws.send(JSON.stringify(msg)); }); ws.on(close, async () { await stack.dispose(); }); });WebSocket 处理器同时采纳了数据库连接和发布/订阅订阅。当客户端断开时close 事件触发栈释放。两个资源原子地释放防止手工清理链在一个操作失败时制造的泄漏。在中间件中使用 AsyncDisposableStack 的团队报告称此前需要重启服务器才能解决的资源泄漏事故被消除了。显式的释放点和有保证的清理执行解决了源于错误路径中不完整清理序列的那一类 bug。常见问题对同一个 AsyncDisposableStack 多次调用 dispose() 会发生什么第一次dispose()调用执行所有清理操作并设置stack.disposed为true。后续调用立即返回不执行任何清理。这种幂等性防止了双重释放错误但也意味着代码不能重置或复用已释放的栈。AsyncDisposableStack 能处理同步释放操作吗还是所有东西都必须异步AsyncDisposableStack 只支持异步释放函数。同步清理操作需要包装进异步函数或者改用DisposableStack。当前 API 不支持在同一栈中混用同步和异步释放。adopt()、use() 和 defer() 的调用顺序会影响释放顺序吗还是它们都按注册逆序一起执行所有注册方法adopt、use、defer都按注册顺序加入同一条释放序列。释放按这条序列的逆序执行与使用了哪种注册方法无关。一个先注册的 defer() 会在后注册的采纳资源之后释放。AsyncDisposableStack 与 TypeScript 的同步资源 using 关键字如何交互AsyncDisposableStack 需要await using因为它实现了Symbol.asyncDispose。同步的using关键字只适用于DisposableStack和Symbol.dispose。混用同步和异步释放需要为每种协议创建独立的栈。如果在 stack.move() 期间出错或者被移动的栈从未被释放资源会怎样move()操作原子地转移所有资源。如果源栈尚未释放返回的栈拥有所有资源。如果返回的栈从未释放资源就会泄漏。无论返回的栈后来怎样源栈在 move() 之后都会进入已释放状态。结论AsyncDisposableStack 何时胜过自定义清理逻辑AsyncDisposableStack 解决了手工 try-finally 链无法可靠处理的多资源协调问题。当一个代码库积累了必须原子释放的数据库连接、分布式锁、文件句柄和网络客户端时手工方式会制造在错误条件下失效的嵌套作用域。AsyncDisposableStack 提供了生产代码所需的保证释放顺序、错误聚合和显式协调。这种模式不止适用于简单的资源清理。Web 服务器中的请求作用域资源管理、微服务中的分布式事务协调、以及多数据源的批处理流水线都能从await using提供的退出即释放语义中获益。通过adopt()、defer()和move()的采纳模式可以处理真实生产代码每天遇到的条件清理、所有权转移和基于闭包的清理。以上就是用 AsyncDisposableStack 协调多资源清理的核心模式。把它们用在生产服务端代码中资源泄漏预防的差异会立竿见影。想了解更多 TypeScript 资源管理特性可参阅 TypeScript using显式资源管理以及 10 个 TypeScript 实用类型。构建 MCP 服务器的团队可以在用 TypeScript 和 Claude 构建 MCP 服务器中找到类似模式。相关阅读延伸外链以下为推荐的相关技术教程来自致知笔记如何将笔记本电脑连接到外接显示器如何检查 IP 地址是静态还是动态Static/Dynamic IP如何在 Windows 11/10 中创建密码重置盘 TypeScript using 与 AsyncDisposableStack：在真实服务端代码中协调多资源清理
大多数服务端资源泄漏都源于不完整的清理序列——当多个异步资源在生产环境中未能正确清理时。数据库连接关闭了但 Redis 锁从未释放。请求结束后文件句柄仍然存在因为一个上游错误短路了清理链。这些失败悄无声息地发生直到连接池耗尽或磁盘配额告警在数小时后触发。团队常用的手工模式看起来像是对每个资源嵌套 try-finally 块。这种方法在真实生产条件下会崩溃清理代码中的错误会阻止下游资源释放释放顺序变得隐式且脆弱而且资源超过三个时代码就变得不可读。TypeScript 的AsyncDisposableStack为多资源清理提供了显式协调具备手动链无法比拟的保证释放顺序和错误聚合能力。关键要点AsyncDisposableStack通过一个统一的释放点协调多个异步资源即使在单个操作失败时也能保证逆序清理。手工 try-finally 链在生产错误条件下会崩溃因为清理代码中的错误会阻止下游资源释放。adopt()方法注册任何带有清理函数的资源defer()将任意异步工作延迟到释放时执行move()在栈之间转移所有权。释放始终按注册的逆序执行LIFO错误会聚合进SuppressedError链保留每一个失败上下文。AsyncDisposableStack在请求作用域的资源管理中表现出色例如数据库连接、分布式锁和文件句柄无论请求结果如何都必须原子地释放。理解 AsyncDisposableStack协调多个 DisposableAsyncDisposableStack 实现了AsyncDisposable接口并提供三种注册方法团队可以用它们构建复杂的清理序列。理解这些方法的差异决定了哪种模式适合给定的生产场景。adopt()方法接收一个资源值和一个清理函数注册清理逻辑的同时原样返回资源。这种方法适用于没有原生实现Symbol.asyncDispose的资源。清理函数接收原始资源值作为参数从而支持连接池归还或锁释放这类需要原始引用的模式。const stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (conn) { await conn.release(); });use()方法直接注册一个已存在的AsyncDisposable对象委托给它的Symbol.asyncDispose实现。当资源已经实现了释放协议时这个方法创建最自然的集成。栈在自身的释放阶段会调用已注册对象的[Symbol.asyncDispose]()。class ManagedLock implements AsyncDisposable { async [Symbol.asyncDispose]() { await this.release(); } } const lock await acquireLock(); stack.use(lock); // 委托给 lock[Symbol.asyncDispose]()defer()方法把任意异步工作调度到释放阶段执行而不绑定到特定的资源值。这种模式处理依赖闭包状态、或无论资源分配是否成功都需要运行的清理操作。延迟函数与已采纳资源一起按注册逆序执行。let tempFile: string | null null; stack.defer(async () { if (tempFile) { await fs.unlink(tempFile); } }); tempFile await createTempFile();释放顺序严格遵循后进先出LIFO语义。一个栈先采纳数据库连接、再采纳 Redis 锁、最后采纳文件句柄那么释放时先关闭文件句柄其次释放锁最后归还连接。这个顺序很重要因为后面的资源往往依赖更早的资源在自己清理期间仍然可用。move()方法把全部已注册资源从一个栈转移到另一个栈使源栈进入已释放状态。这个操作支持这样的模式一个函数构建一组资源并把所有权返回给调用方。调用方的栈承担清理责任原始栈则变为惰性状态。async function setupResources() { const stack new AsyncDisposableStack(); stack.adopt(await openConnection(), closeConnection); stack.adopt(await acquireLock(), releaseLock); return stack.move(); // 转移所有权原始栈现在已释放 } await using resources await setupResources();disposed属性表示栈是否已经执行了释放序列。释放完成后任何尝试采纳新资源的操作都会抛出ReferenceError。这个守卫防止在清理已经开始后注册资源那会制造不可能实现的清理保证。真实服务端场景数据库连接、Redis 锁和文件句柄的清理一个处理文件上传的生产 API 端点展示了 AsyncDisposableStack 解决的协调问题。该操作需要数据库事务来写入元数据、需要 Redis 锁来防止同一文件的并发处理、需要一个临时文件句柄来暂存上传内容。这三个资源必须在请求完成或失败时原子地释放。手工方式串联 try-finally 块制造了嵌套的错误处理上下文这些上下文难以维护并且当中间操作出错时无法保证完整清理。async function processUpload(fileData: Buffer, metadata: UploadMetadata) { const connection await pool.connect(); try { await connection.query(BEGIN); const lockKey upload:${metadata.id}; const lock await redisClient.lock(lockKey, 30000); try { const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, fileData); try { // 处理文件... await connection.query(INSERT INTO uploads ..., [metadata]); await connection.query(COMMIT); } finally { await fs.unlink(tempPath); // 如果这里抛错锁永远不会释放 } } finally { await lock.release(); // 如果这里抛错连接永远不会归还 } } finally { connection.release(); } }这里的失败模式很隐蔽但代价高昂。fs.unlink()中的一个错误会阻止锁释放执行。锁会在其 30 秒 TTL 期间一直持有而连接已经归还到连接池。同一文件的并发上传会被阻塞直到锁过期。临时文件残留在磁盘上。所有这些失败都不会作为错误浮出水面因为外层的 finally 块从未执行。AsyncDisposableStack 消除了嵌套作用域并保证无论单个失败如何所有清理都会执行。async function processUpload(fileData: Buffer, metadata: UploadMetadata) { await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (conn) { await conn.query(ROLLBACK).catch(() {}); // 尽力回滚 conn.release(); }); await connection.query(BEGIN); const lockKey upload:${metadata.id}; const lock await redisClient.lock(lockKey, 30000); stack.adopt(lock, async (l) await l.release()); const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, fileData); stack.defer(async () { await fs.unlink(tempPath).catch(() {}); // 确保尝试删除 }); // 处理文件... await connection.query(INSERT INTO uploads ..., [metadata]); await connection.query(COMMIT); // 栈按逆序释放删除临时文件 - 释放锁 - 归还连接 }当函数作用域退出时栈先释放延迟的 unlink然后释放锁最后归还连接。任何清理操作中的错误都不会阻止其他操作执行。栈会把错误聚合进SuppressedError链为日志记录和调试保留每一个失败上下文。这种模式可以自然地扩展到更复杂的场景。一个打开多个文件句柄的批处理作业可以在每次打开后立即采纳它们确保即使后续打开失败也能清理。一个分布式事务协调器可以把补偿动作注册为 defer() 调用无论提交是否成功都保证尝试回滚。AsyncDisposableStack 与手工 try-finally 链错误处理与保证手工 try-finally 链与 AsyncDisposableStack 之间的对比揭示了错误传播和清理保证方面的根本差异这些差异会影响生产可靠性。手工链按照嵌套结构的相反顺序执行清理但前提是更早的清理没有抛错。内层 finally 块中的错误会阻止外层 finally 块执行导致上游资源泄漏。这种失败模式制造出静默的资源耗尽在触发错误数小时之后才显现。AsyncDisposableStack 保证每个已注册的清理都会执行无论其他清理是否失败。当某个释放操作抛错时栈会捕获该错误、继续释放其余资源并把所有错误聚合进一个SuppressedError实例。主错误成为被抛出的异常后续错误作为suppressed属性链挂接。async function demonstrateErrorAggregation() { await using stack new AsyncDisposableStack(); stack.defer(async () { throw new Error(First cleanup failed); }); stack.defer(async () { throw new Error(Second cleanup failed); }); // 作用域退出时两个错误都会聚合 // SuppressedError: Second cleanup failed // suppressed: Error: First cleanup failed }错误聚合模式保留了每一个失败上下文而不是把次要错误隐藏在第一个异常后面。日志基础设施可以遍历suppressed链捕获完整的清理失败序列。这种可见性在生产环境中很重要——数据库超时可能触发一连串下游清理失败每一个都需要单独调查。手工链要求在每个 finally 块中显式处理错误以防止错误传播中断清理。这种方法增加了样板代码而且仍然缺少 AsyncDisposableStack 自动提供的聚合语义。// 手工错误处理近似 AsyncDisposableStack 的行为 let connectionError: Error | null null; try { // ... 使用 connection } finally { try { connection.release(); } catch (error) { connectionError error as Error; } try { await lock.release(); } catch (error) { if (connectionError) { // 手工错误聚合——冗长且易错 } } }保证上的差异还延伸到释放顺序的可预测性。手工链只有在异常处理尊重嵌套顺序时才会按逆序执行清理。一次改变 try 块顺序的重构就会隐式改变清理语义。AsyncDisposableStack 通过注册顺序让释放顺序变得显式把清理序列从词法结构中解耦出来。生产模式adopt()、defer() 和 move() 处理复杂清理流程真实生产代码需要的模式超出了简单的资源采纳。条件资源获取、所有权转移、依赖操作结果的清理这些都会出现在服务端代码库中。AsyncDisposableStack 的三种注册方法通过组合处理这些场景。adopt()模式适用于来自工厂或连接池、需要自定义清理函数的资源。来自连接池的数据库连接、来自连接管理器的 Redis 客户端、具有特定关闭序列的 HTTP 客户端都符合这种模式。清理函数接收资源值从而能访问资源类型暴露的方法。async function withDatabaseTransactionT( fn: (client: PoolClient) PromiseT ): PromiseT { await using stack new AsyncDisposableStack(); const client await pool.connect(); stack.adopt(client, async (c) { await c.query(ROLLBACK).catch(() {}); c.release(); }); await client.query(BEGIN); const result await fn(client); await client.query(COMMIT); return result; }defer()模式处理依赖条件执行或闭包状态的清理。一个只在文件处理成功时才需要删除的临时目录可以使用 defer()因为决策逻辑发生在资源创建之后。作用域退出时的指标上报、缓存失效和 webhook 通知都符合 defer() 模式。async function processWithTempDir(files: File[]) { await using stack new AsyncDisposableStack(); const tempDir await fs.mkdtemp(/tmp/process-); let shouldKeep false; stack.defer(async () { if (!shouldKeep) { await fs.rm(tempDir, { recursive: true }); } }); // 处理文件... if (allFilesValid) { shouldKeep true; } }move()模式在函数构建一组资源并返回给调用方时转移所有权。这种模式出现在构建复杂资源图的工厂函数中其中清理责任必须原子地转移。没有 move()工厂要么在返回前释放资源阻止调用方使用要么泄漏清理责任。一个实际例子展示了 move() 在数据库迁移运行器中的用法为多个数据库打开连接并把协调好的清理返回给迁移编排器。async function setupMigrationEnvironment() { const stack new AsyncDisposableStack(); const primary await connectPrimary(); stack.adopt(primary, async (conn) await conn.close()); const replica await connectReplica(); stack.adopt(replica, async (conn) await conn.close()); const lockClient await redis.connect(); stack.adopt(lockClient, async (client) await client.quit()); return { primary, replica, lockClient, cleanup: stack.move(), // 调用方拥有清理权 }; } async function runMigrations() { const env await setupMigrationEnvironment(); await using cleanup env.cleanup; // 采纳转移过来的资源 // 使用 env.primary, env.replica, env.lockClient // 所有资源在 cleanup 作用域退出时释放 }组合这些模式可以处理请求作用域资源池这类场景中间件建立一个栈处理器在请求处理期间采纳资源中间件在响应完成时释放所有东西。栈提供了让这种模式可靠的协调点。常见陷阱释放顺序、异步时序以及 dispose() 实际返回什么采用 AsyncDisposableStack 的团队会遇到三种失败模式它们源于对释放语义的错误假设。理解这些陷阱可以避免生产 bug。释放顺序陷阱发生在代码假设注册顺序与清理需求一致、但后面的资源依赖更早资源保持可用时。一个向数据库连接写入的文件句柄必须在连接归还连接池之前关闭这就要求按与依赖关系相反的顺序采纳。解决方案是让采纳顺序与依赖顺序相反。先采纳连接再采纳依赖它的资源。释放按逆序执行在依赖的资源所依赖的连接被关闭之前先关闭依赖资源。// 错误——连接在文件释放需要它之前就被关闭了 await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (c) c.release()); const file await openFile(connection); stack.adopt(file, async (f) { await f.writeMetadata(connection); // 连接已经被释放了 await f.close(); }); // 正确——文件先于它所依赖的连接关闭 await using stack new AsyncDisposableStack(); const connection await pool.connect(); const file await openFile(connection); stack.adopt(file, async (f) { await f.writeMetadata(connection); // 连接仍然可用 await f.close(); }); stack.adopt(connection, async (c) c.release());异步时序陷阱源于期望await using的释放会在下一条语句执行前完成。释放发生在作用域退出时这意味着当前作用域中的所有代码都会在释放开始前运行。一个常见错误是采纳一个资源、使用它然后在它被采纳的那个作用域退出之后尝试访问它。let connection: PoolClient; { await using stack new AsyncDisposableStack(); connection await pool.connect(); stack.adopt(connection, async (c) c.release()); // 释放还没有发生 } // 释放在这里完成——连接已释放 await connection.query(SELECT 1); // 错误连接已经被释放正确的模式是让资源的使用与管理它的栈保持在同一个作用域内。需要活得比分配作用域更长的资源需要一个覆盖更长生命周期的父栈。释放返回值陷阱发生在代码期望await stack.dispose()返回一个表示成功或失败的值时。dispose() 方法返回void出错时抛出异常与Symbol.asyncDispose语义相同。需要区分成功释放与释放错误的代码必须用 try-catch 包裹调用。// 错误——dispose() 返回 void不是状态 const result await stack.dispose(); if (result.success) { /* ... */ } // 正确——通过异常处理释放错误 try { await stack.dispose(); // 所有清理都成功了 } catch (error) { if (error instanceof SuppressedError) { // 访问 error.suppressed 获取次要失败 } }一个相关的陷阱是把栈当作释放后仍可复用。一旦stack.dispose()完成栈进入已释放状态此时stack.disposed true。任何尝试采纳新资源的操作都会抛出ReferenceError。需要多个清理阶段的代码必须为每个阶段创建独立的栈。与 Express 中间件集成请求作用域的资源管理Express 中间件展示了 AsyncDisposableStack 在请求作用域资源协调中的价值多个资源必须在响应完成时释放无论成功还是失败。一个建立栈、在请求处理期间填充它、并在响应结束时保证释放的中间件解决了影响长驻服务器的资源泄漏问题。这种模式在早期中间件中把一个 AsyncDisposableStack 挂到请求对象上允许处理器在整个请求生命周期中采纳资源。一个收尾中间件或错误处理器确保在响应关闭时释放。import express from express; import { AsyncDisposableStack } from node:async_hooks; interface ResourceRequest extends express.Request { resources: AsyncDisposableStack; } function resourceMiddleware( req: express.Request, res: express.Response, next: express.NextFunction ) { const resourceReq req as ResourceRequest; resourceReq.resources new AsyncDisposableStack(); res.on(finish, async () { await resourceReq.resources.dispose().catch((error) { console.error(Resource cleanup failed:, error); }); }); next(); } app.use(resourceMiddleware); app.post(/api/upload, async (req: express.Request, res: express.Response) { const resourceReq req as ResourceRequest; // 采纳数据库连接 const connection await pool.connect(); resourceReq.resources.adopt(connection, async (c) c.release()); // 获取分布式锁 const lockKey upload:${req.body.id}; const lock await redisClient.lock(lockKey, 30000); resourceReq.resources.adopt(lock, async (l) await l.release()); // 创建临时文件 const tempPath /tmp/upload-${Date.now()}; await fs.writeFile(tempPath, req.body.data); resourceReq.resources.defer(async () { await fs.unlink(tempPath).catch(() {}); }); // 处理上传... await processUpload(connection, tempPath); res.json({ status: success }); // 响应结束时资源释放 });这种模式自动处理错误情况。processUpload()中的异常会触发 Express 错误处理它仍然会发出触发释放的finish事件。无论请求成功与否数据库连接都会归还连接池、锁会释放、临时文件会删除。这种方法可以扩展到 WebSocket 连接、流式响应和长轮询端点这些场景中资源必须在较长时间内保持存活。一个连接升级处理器可以把 socket 及相关资源采纳进一个栈在 socket 关闭时释放。import { WebSocketServer } from ws; wss.on(connection, async (ws) { await using stack new AsyncDisposableStack(); const connection await pool.connect(); stack.adopt(connection, async (c) c.release()); const subscription await pubsub.subscribe(updates); stack.adopt(subscription, async (s) await s.unsubscribe()); ws.on(message, async (data) { const result await connection.query(INSERT INTO messages ..., [data]); await pubsub.publish(updates, result.rows[0]); }); subscription.on(message, (msg) { ws.send(JSON.stringify(msg)); }); ws.on(close, async () { await stack.dispose(); }); });WebSocket 处理器同时采纳了数据库连接和发布/订阅订阅。当客户端断开时close 事件触发栈释放。两个资源原子地释放防止手工清理链在一个操作失败时制造的泄漏。在中间件中使用 AsyncDisposableStack 的团队报告称此前需要重启服务器才能解决的资源泄漏事故被消除了。显式的释放点和有保证的清理执行解决了源于错误路径中不完整清理序列的那一类 bug。常见问题对同一个 AsyncDisposableStack 多次调用 dispose() 会发生什么第一次dispose()调用执行所有清理操作并设置stack.disposed为true。后续调用立即返回不执行任何清理。这种幂等性防止了双重释放错误但也意味着代码不能重置或复用已释放的栈。AsyncDisposableStack 能处理同步释放操作吗还是所有东西都必须异步AsyncDisposableStack 只支持异步释放函数。同步清理操作需要包装进异步函数或者改用DisposableStack。当前 API 不支持在同一栈中混用同步和异步释放。adopt()、use() 和 defer() 的调用顺序会影响释放顺序吗还是它们都按注册逆序一起执行所有注册方法adopt、use、defer都按注册顺序加入同一条释放序列。释放按这条序列的逆序执行与使用了哪种注册方法无关。一个先注册的 defer() 会在后注册的采纳资源之后释放。AsyncDisposableStack 与 TypeScript 的同步资源 using 关键字如何交互AsyncDisposableStack 需要await using因为它实现了Symbol.asyncDispose。同步的using关键字只适用于DisposableStack和Symbol.dispose。混用同步和异步释放需要为每种协议创建独立的栈。如果在 stack.move() 期间出错或者被移动的栈从未被释放资源会怎样move()操作原子地转移所有资源。如果源栈尚未释放返回的栈拥有所有资源。如果返回的栈从未释放资源就会泄漏。无论返回的栈后来怎样源栈在 move() 之后都会进入已释放状态。结论AsyncDisposableStack 何时胜过自定义清理逻辑AsyncDisposableStack 解决了手工 try-finally 链无法可靠处理的多资源协调问题。当一个代码库积累了必须原子释放的数据库连接、分布式锁、文件句柄和网络客户端时手工方式会制造在错误条件下失效的嵌套作用域。AsyncDisposableStack 提供了生产代码所需的保证释放顺序、错误聚合和显式协调。这种模式不止适用于简单的资源清理。Web 服务器中的请求作用域资源管理、微服务中的分布式事务协调、以及多数据源的批处理流水线都能从await using提供的退出即释放语义中获益。通过adopt()、defer()和move()的采纳模式可以处理真实生产代码每天遇到的条件清理、所有权转移和基于闭包的清理。以上就是用 AsyncDisposableStack 协调多资源清理的核心模式。把它们用在生产服务端代码中资源泄漏预防的差异会立竿见影。想了解更多 TypeScript 资源管理特性可参阅 TypeScript using显式资源管理以及 10 个 TypeScript 实用类型。构建 MCP 服务器的团队可以在用 TypeScript 和 Claude 构建 MCP 服务器中找到类似模式。相关阅读延伸外链以下为推荐的相关技术教程来自致知笔记如何将笔记本电脑连接到外接显示器如何检查 IP 地址是静态还是动态Static/Dynamic IP如何在 Windows 11/10 中创建密码重置盘