大多数服务端资源泄漏都源于不完整的清理序列------当多个异步资源在生产环境中未能正确清理时。数据库连接关闭了，但 Redis 锁从未释放。请求结束后文件句柄仍然存在，因为一个上游错误短路了清理链。这些失败悄无声息地发生，直到连接池耗尽或磁盘配额告警在数小时后触发。
团队常用的手工模式看起来像是对每个资源嵌套 try-finally 块。这种方法在真实生产条件下会崩溃：清理代码中的错误会阻止下游资源释放，释放顺序变得隐式且脆弱，而且资源超过三个时代码就变得不可读。TypeScript 的 AsyncDisposableStack 为多资源清理提供了显式协调，具备手动链无法比拟的保证释放顺序和错误聚合能力。
关键要点
AsyncDisposableStack通过一个统一的释放点协调多个异步资源，即使在单个操作失败时也能保证逆序清理。- 手工 try-finally 链在生产错误条件下会崩溃，因为清理代码中的错误会阻止下游资源释放。
adopt()方法注册任何带有清理函数的资源，defer()将任意异步工作延迟到释放时执行，move()在栈之间转移所有权。- 释放始终按注册的逆序执行（LIFO），错误会聚合进
SuppressedError链，保留每一个失败上下文。 AsyncDisposableStack在请求作用域的资源管理中表现出色，例如数据库连接、分布式锁和文件句柄无论请求结果如何都必须原子地释放。
理解 AsyncDisposableStack：协调多个 Disposable
AsyncDisposableStack 实现了 AsyncDisposable 接口，并提供三种注册方法，团队可以用它们构建复杂的清理序列。理解这些方法的差异，决定了哪种模式适合给定的生产场景。
adopt() 方法接收一个资源值和一个清理函数，注册清理逻辑的同时原样返回资源。这种方法适用于没有原生实现 Symbol.asyncDispose 的资源。清理函数接收原始资源值作为参数，从而支持连接池归还或锁释放这类需要原始引用的模式。
bash
const stack = new AsyncDisposableStack();
const connection = await pool.connect();
stack.adopt(connection, async (conn) => {
await conn.release();
});use() 方法直接注册一个已存在的 AsyncDisposable 对象，委托给它的 Symbol.asyncDispose 实现。当资源已经实现了释放协议时，这个方法创建最自然的集成。栈在自身的释放阶段会调用已注册对象的 [Symbol.asyncDispose]()。
bash
class ManagedLock implements AsyncDisposable {
async [Symbol.asyncDispose]() {
await this.release();
}
}
const lock = await acquireLock();
stack.use(lock); // 委托给 lock[Symbol.asyncDispose]()defer() 方法把任意异步工作调度到释放阶段执行，而不绑定到特定的资源值。这种模式处理依赖闭包状态、或无论资源分配是否成功都需要运行的清理操作。延迟函数与已采纳资源一起按注册逆序执行。
bash
let tempFile: string | null = null;
stack.defer(async () => {
if (tempFile) {
await fs.unlink(tempFile);
}
});
tempFile = await createTempFile();释放顺序严格遵循后进先出（LIFO）语义。一个栈先采纳数据库连接、再采纳 Redis 锁、最后采纳文件句柄，那么释放时先关闭文件句柄，其次释放锁，最后归还连接。这个顺序很重要，因为后面的资源往往依赖更早的资源在自己清理期间仍然可用。
move() 方法把全部已注册资源从一个栈转移到另一个栈，使源栈进入已释放状态。这个操作支持这样的模式：一个函数构建一组资源并把所有权返回给调用方。调用方的栈承担清理责任，原始栈则变为惰性状态。
bash
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 块，制造了嵌套的错误处理上下文，这些上下文难以维护，并且当中间操作出错时无法保证完整清理。
bash
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 消除了嵌套作用域，并保证无论单个失败如何，所有清理都会执行。
bash
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 属性链挂接。
bash
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 自动提供的聚合语义。
bash
// 手工错误处理，近似 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 客户端，都符合这种模式。清理函数接收资源值，从而能访问资源类型暴露的方法。
bash
async function withDatabaseTransaction<T>(
fn: (client: PoolClient) => Promise<T>
): Promise<T> {
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() 模式。
bash
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() 在数据库迁移运行器中的用法：为多个数据库打开连接，并把协调好的清理返回给迁移编排器。
bash
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。
释放顺序陷阱发生在代码假设注册顺序与清理需求一致、但后面的资源依赖更早资源保持可用时。一个向数据库连接写入的文件句柄必须在连接归还连接池之前关闭，这就要求按与依赖关系相反的顺序采纳。
解决方案是让采纳顺序与依赖顺序相反。先采纳连接，再采纳依赖它的资源。释放按逆序执行，在依赖的资源所依赖的连接被关闭之前，先关闭依赖资源。
bash
// 错误------连接在文件释放需要它之前就被关闭了
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 的释放会在下一条语句执行前完成。释放发生在作用域退出时，这意味着当前作用域中的所有代码都会在释放开始前运行。一个常见错误是：采纳一个资源、使用它，然后在它被采纳的那个作用域退出之后尝试访问它。
bash
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 包裹调用。
bash
// 错误------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 挂到请求对象上，允许处理器在整个请求生命周期中采纳资源。一个收尾中间件或错误处理器确保在响应关闭时释放。
bash
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 关闭时释放。
bash
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 服务器中找到类似模式。
相关阅读（延伸外链）
以下为推荐的相关技术教程，来自致知笔记：