Node.js 异步钩子（Async Hooks）：实现分布式追踪中 AsyncLocalStorage 上下文自动传递的底层原理 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

在Node.js这个单线程、事件驱动的运行时环境中，管理请求或事务的上下文信息是一项独特的挑战。传统的同步编程模型中，上下文（如用户ID、请求ID、数据库事务）通常可以通过函数参数或线程局部存储（Thread-Local Storage, TLS）来隐式传递。然而，Node.js的异步特性，尤其是其基于回调、Promise和async/await的非阻塞I/O模型，使得这种上下文的自动传递变得复杂。当一个操作被挂起并等待I/O完成后再恢复时，原始的调用栈已经消失，上下文很容易丢失。

分布式追踪系统，如OpenTelemetry、Zipkin或Jaeger，需要能够在服务内部的各种异步操作中（HTTP请求、数据库查询、消息队列发布/订阅等）持续传递一个全局的追踪ID（Trace ID）和当前操作的跨度ID（Span ID）。如果不能自动传递这些上下文，开发者将不得不手动地将这些ID作为参数传递给每一个可能涉及异步操作的函数，这无疑会极大地增加代码的复杂性和维护成本。

Node.js的Async Hooks和基于其构建的AsyncLocalStorage正是为了解决这一核心问题而生，它们是实现Node.js异步上下文本地存储和自动传递的底层原理。

Node.js异步编程的挑战：上下文的丢失

让我们从一个简单的例子开始，说明在Node.js中上下文是如何容易丢失的。

// 场景：模拟一个处理用户请求的函数，需要记录请求ID
function processUserRequest(requestId) {
    console.log(`[${requestId}] 收到请求，开始处理...`);

    // 模拟一个异步操作，例如数据库查询
    setTimeout(() => {
        // 在异步回调中，如何访问到 requestId？
        // 如果 requestId 没有被显式传递，它将无法访问。
        // console.log(`[${requestId}] 异步操作完成。`); // 这里的 requestId 必须通过闭包捕获或者参数传递
        console.log(`异步操作完成，但原始请求ID无法直接获取。`);
    }, 100);

    // 模拟另一个异步操作，例如发送HTTP请求
    Promise.resolve().then(() => {
        // 同样，这里的 requestId 也需要显式传递
        console.log(`Promise异步操作完成，原始请求ID无法直接获取。`);
    });

    console.log(`[${requestId}] 请求处理流程继续，等待异步操作完成...`);
}

processUserRequest('req-101');
processUserRequest('req-102');

在这个例子中，requestId是当前请求的上下文。在同步代码中，requestId可以通过闭包访问。但是，如果我们在一个更复杂的调用链中，requestId可能需要经过多层函数调用和多个异步操作，手动传递它会非常繁琐：

function getUserData(requestId, userId, callback) {
    console.log(`[${requestId}] 获取用户 ${userId} 数据...`);
    setTimeout(() => {
        // 模拟数据库查询
        const userData = { id: userId, name: `User ${userId}`, email: `user${userId}@example.com` };
        callback(null, requestId, userData); // 必须传递 requestId
    }, 50);
}

function processOrder(requestId, orderId, callback) {
    console.log(`[${requestId}] 处理订单 ${orderId}...`);
    getUserData(requestId, 'user-abc', (err, reqId, userData) => { // 必须接收和传递 requestId
        if (err) return callback(err);
        console.log(`[${reqId}] 订单 ${orderId} 关联用户数据:`, userData.name);
        // 更多异步操作...
        callback(null, reqId, { orderId, status: 'processed' });
    });
}

// 入口点
function handleIncomingRequest(requestId) {
    console.log(`[${requestId}] 处理新的HTTP请求...`);
    processOrder(requestId, 'order-xyz', (err, reqId, result) => { // 必须接收和传递 requestId
        if (err) {
            console.error(`[${reqId}] 请求处理失败:`, err);
        } else {
            console.log(`[${reqId}] 请求处理成功:`, result);
        }
    });
}

handleIncomingRequest('http-req-A');
handleIncomingRequest('http-req-B');

想象一下，在一个大型应用中，如果每个异步操作都需要手动传递requestId，代码将变得难以阅读和维护。这就是“上下文丢失”问题，也是Async Hooks和AsyncLocalStorage旨在解决的核心痛点。

Async Hooks：Node.js异步资源的生命周期跟踪器

Async Hooks是Node.js提供的一个低级API，用于跟踪Node.js进程中异步资源的完整生命周期。它允许我们注册回调函数，在每个异步操作（如setTimeout、Promise、网络请求、文件I/O等）的特定生命周期事件发生时得到通知。

异步资源与`async_id`

在Node.js中，任何一个会产生异步回调或影响事件循环的内部或用户定义的对象，都可以被视为一个“异步资源”。每个异步资源在创建时都会被赋予一个唯一的async_id。这个async_id在资源的整个生命周期中保持不变。

Async Hooks API的核心是async_hooks.createHook(callbacks)方法，它接受一个包含多个事件回调的字典：

事件回调	描述
`init(asyncId, type, triggerAsyncId, resource)`	在一个异步资源被创建时调用。`asyncId`是新资源的唯一ID，`type`是资源的类型（如`Timeout`、`Promise`、`TCPWRAP`等），`triggerAsyncId`是导致这个新资源被创建的父异步资源的ID，`resource`是新资源的实际对象引用。
`before(asyncId)`	在异步资源的回调函数即将执行之前调用。例如，`setTimeout`的回调即将被调用前，或者`Promise.then()`中的回调即将被调用前。
`after(asyncId)`	在异步资源的回调函数执行完毕之后调用。
`destroy(asyncId)`	在异步资源被销毁时调用。当资源不再被引用，或其生命周期结束时（例如`setTimeout`定时器触发一次后），会触发此事件。
`promiseResolve(asyncId)`	仅针对`Promise`资源。当一个`Promise`被`resolve`或`reject`时调用。这个事件发生在`Promise`的回调（`then`/`catch`/`finally`）被调度到事件循环之前，但表示`Promise`的状态已改变。它不是`before`或`after`的替代品，而是`Promise`特有的状态转换通知。

通过这些钩子，我们可以追踪一个请求或一个事务从开始到结束的完整异步调用链。triggerAsyncId是理解上下文传递的关键：它指明了当前异步操作是由哪个父异步操作触发的，从而构建出异步操作的父子关系。

`Async Hooks`示例：追踪异步流

让我们用一个简单的Async Hooks来观察Node.js内部的异步活动。为了方便输出，我们使用fs.writeSync避免自身创建异步资源导致无限循环。

const async_hooks = require('async_hooks');
const fs = require('fs');
const util = require('util');

// 用于同步日志输出，避免日志本身创建异步资源
const log = (...args) => fs.writeSync(1, `${util.format(...args)}n`);

// 获取当前异步资源的ID
function getCurrentAsyncId() {
    return async_hooks.executionAsyncId();
}

// 获取触发当前异步资源的父资源的ID
function getTriggerAsyncId() {
    return async_hooks.triggerAsyncId();
}

const hook = async_hooks.createHook({
    init(asyncId, type, triggerAsyncId, resource) {
        log(`INIT:   [${asyncId}] type=${type}, trigger=${triggerAsyncId}, current=${getCurrentAsyncId()}`);
    },
    before(asyncId) {
        log(`BEFORE: [${asyncId}] current=${getCurrentAsyncId()}`);
    },
    after(asyncId) {
        log(`AFTER:  [${asyncId}] current=${getCurrentAsyncId()}`);
    },
    destroy(asyncId) {
        log(`DESTROY:[${asyncId}]`);
    },
    promiseResolve(asyncId) {
        log(`PROMISE_RESOLVE: [${asyncId}]`);
    }
});

// 启用钩子
hook.enable();

log(`---------- 开始主执行流 ----------`);
const mainAsyncId = getCurrentAsyncId(); // 主执行流的 asyncId

// 1. setTimeout
log(`创建 setTimeout... (当前 asyncId: ${mainAsyncId})`);
setTimeout(() => {
    log(`  [setTimeout回调] 执行中... (当前 asyncId: ${getCurrentAsyncId()})`);
}, 100);

// 2. Promise
log(`创建 Promise... (当前 asyncId: ${mainAsyncId})`);
Promise.resolve()
    .then(() => {
        log(`  [Promise.then回调] 执行中... (当前 asyncId: ${getCurrentAsyncId()})`);
        return new Promise(resolve => {
            setTimeout(() => {
                log(`    [嵌套 setTimeout in Promise] 执行中... (当前 asyncId: ${getCurrentAsyncId()})`);
                resolve();
            }, 50);
        });
    })
    .then(() => {
        log(`  [第二个 Promise.then回调] 执行中... (当前 asyncId: ${getCurrentAsyncId()})`);
    });

// 3. 立即执行的异步操作 (setImmediate)
log(`创建 setImmediate... (当前 asyncId: ${mainAsyncId})`);
setImmediate(() => {
    log(`  [setImmediate回调] 执行中... (当前 asyncId: ${getCurrentAsyncId()})`);
});

log(`---------- 主执行流结束 ----------`);

// 禁用钩子 (可选，但对于长时间运行的进程建议在不再需要时禁用)
// setTimeout(() => {
//     hook.disable();
//     log('Async Hooks Disabled.');
// }, 500);

运行上述代码，你将看到大量的日志输出，详细记录了setTimeout、Promise和setImmediate等异步资源的创建、执行和销毁过程。triggerAsyncId字段会显示这些异步操作是由哪个父操作触发的，从而形成一个异步调用链。

Async Hooks的局限性：

尽管Async Hooks提供了强大的底层追踪能力，但它是一个非常低级的API。直接使用它来存储和检索上下文信息非常复杂：

手动映射： 你需要维护一个从async_id到上下文对象的映射（例如一个Map）。
上下文继承： 在init事件中，你需要根据triggerAsyncId找到父上下文，并将其复制或继承给新的async_id。
内存管理： 你需要在destroy事件中清理不再需要的上下文，以避免内存泄漏。
性能开销： 频繁的Map操作和上下文复制可能带来性能开销，尤其是在高并发场景下。
复杂性： 开发者需要处理各种异步资源的类型和它们的生命周期差异。

因此，Async Hooks更多地是作为Node.js运行时内部工具或构建更高层抽象的基石，而不是直接用于应用层业务上下文管理。

AsyncLocalStorage：基于Async Hooks的上下文自动传递

为了解决Async Hooks的复杂性，Node.js在v13.0.0中引入了AsyncLocalStorage（在v12.x中作为实验性API提供），它正是构建在Async Hooks之上的一个高级抽象，提供了一种类似“线程局部存储”的机制，但在Node.js的异步上下文中自动传递数据。

AsyncLocalStorage的关键在于它将一个Store对象与当前的异步执行流绑定。无论异步操作如何被调度，只要它们属于同一个逻辑执行流，AsyncLocalStorage就能自动访问到最初设置的Store。

`AsyncLocalStorage`的核心API

new AsyncLocalStorage(): 创建一个AsyncLocalStorage实例。
als.run(store, callback, ...args): 这是一个核心方法。它将store对象与当前异步执行流关联起来，并在新的上下文中执行callback函数。store可以是任何类型的值（对象、字符串、数字等）。在callback及其内部的所有异步操作中，都可以通过als.getStore()获取到这个store。
als.getStore(): 获取当前异步执行流关联的store对象。如果在als.run的上下文之外调用，将返回undefined。
als.enterWith(store): 显式设置当前异步执行流的store。这通常用于将外部上下文（例如来自另一个AsyncLocalStorage实例的store）注入到当前流中。它返回一个用于恢复之前上下文的函数。
als.disable(): 禁用AsyncLocalStorage实例。一旦禁用，als.getStore()将始终返回undefined，并且不会再追踪异步上下文。

`AsyncLocalStorage`工作原理简述

当调用als.run(store, callback)时：

AsyncLocalStorage利用Async Hooks在内部记录当前的async_id和store对象之间的映射关系。
callback函数被调用。在callback内部，任何新的异步资源被创建时（例如setTimeout、Promise等），AsyncLocalStorage会通过Async Hooks的init事件捕获到新资源的async_id及其triggerAsyncId。
AsyncLocalStorage根据triggerAsyncId找到父异步资源的store，并将其自动关联到新创建的异步资源的async_id上。
当这些异步资源的回调被执行时，AsyncLocalStorage会通过Async Hooks的before事件将对应的store设置为当前执行上下文的store。
当回调执行完毕，AsyncLocalStorage通过Async Hooks的after事件恢复到之前的上下文。

这个过程是完全自动和透明的，开发者无需手动管理async_id到store的映射，也无需担心上下文的继承和清理。

`AsyncLocalStorage`示例：解决上下文丢失问题

回到我们最初的例子，现在使用AsyncLocalStorage来自动传递requestId：

const { AsyncLocalStorage } = require('async_hooks');

// 创建一个 AsyncLocalStorage 实例
const als = new AsyncLocalStorage();

function logWithContext(message) {
    const store = als.getStore();
    const requestId = store ? store.requestId : '未知请求';
    console.log(`[${requestId}] ${message}`);
}

function getUserData(userId) {
    return new Promise(resolve => {
        logWithContext(`获取用户 ${userId} 数据...`);
        setTimeout(() => {
            // 模拟数据库查询
            const userData = { id: userId, name: `User ${userId}`, email: `user${userId}@example.com` };
            resolve(userData);
        }, 50);
    });
}

async function processOrder(orderId) {
    logWithContext(`处理订单 ${orderId}...`);
    const userData = await getUserData('user-abc'); // 无需传递 requestId
    logWithContext(`订单 ${orderId} 关联用户数据: ${userData.name}`);

    // 模拟另一个异步操作
    await new Promise(resolve => setTimeout(resolve, 20));
    logWithContext(`订单 ${orderId} 异步操作完成。`);

    return { orderId, status: 'processed' };
}

// 入口点
function handleIncomingRequest(requestId) {
    // 使用 als.run 建立一个上下文作用域
    als.run({ requestId: requestId }, async () => {
        logWithContext(`处理新的HTTP请求...`);
        try {
            const result = await processOrder('order-xyz'); // 无需传递 requestId
            logWithContext(`请求处理成功: ${JSON.stringify(result)}`);
        } catch (err) {
            logWithContext(`请求处理失败: ${err.message}`);
        }
    });
}

console.log('--- 开始处理第一个请求 ---');
handleIncomingRequest('http-req-A');

// 模拟第二个请求，它将拥有完全独立的上下文
setTimeout(() => {
    console.log('n--- 开始处理第二个请求 ---');
    handleIncomingRequest('http-req-B');
}, 150);

// 在 als.run 作用域之外，als.getStore() 将返回 undefined
setTimeout(() => {
    console.log('n--- 在独立作用域之外 ---');
    logWithContext('这里应该看不到请求ID');
}, 200);

运行这个示例，你会发现所有的日志输出都带上了正确的requestId，而我们在getUserData和processOrder函数中并没有显式地传递requestId参数。AsyncLocalStorage在后台默默地完成了上下文的传递。

AsyncLocalStorage在分布式追踪中的应用

分布式追踪的核心目标是记录一个请求在跨越多个服务、多个组件时所经历的完整路径。这通常通过一个Trace ID（标识整个请求流）和Span ID（标识请求流中的单个操作或服务调用）来实现。AsyncLocalStorage在这里发挥了至关重要的作用，它能够自动在服务内部的异步操作中传递这些追踪上下文。

分布式追踪上下文的结构

一个典型的追踪上下文可能包含以下信息：

traceId: 全局唯一的追踪标识符，贯穿整个分布式事务。
spanId: 当前操作的唯一标识符，是traceId下的一个子操作。
parentSpanId: 当前操作的父操作的spanId。
sampled: 是否对这个追踪进行采样（即是否发送到追踪系统）。
baggage: 额外的、需要跨服务传递的用户定义键值对。

实现分布式追踪的通用模式

中央上下文管理器： 创建一个封装AsyncLocalStorage的模块，提供方便的方法来设置、获取和更新追踪上下文。
入口点拦截： 在服务接收到外部请求（如HTTP请求、消息队列消息）的入口点，从请求头或消息中提取追踪上下文。如果不存在，则生成一个新的traceId和根spanId。然后，使用AsyncLocalStorage.run()建立当前请求的追踪上下文。
内部操作访问： 在服务内部的任何函数中，通过上下文管理器获取当前的traceId和spanId，用于日志记录、性能监控或创建子Span。
出口点注入： 在服务发起对外部服务的调用（如HTTP客户端请求、数据库查询、消息队列发布）时，从当前的AsyncLocalStorage上下文中获取traceId和spanId，生成一个新的子spanId，并将这些信息注入到传出请求的头部或消息中，以便下游服务能够继续追踪。

详细代码示例：一个简单的分布式追踪框架

我们来构建一个简化的分布式追踪框架，包含两个服务UserService和PaymentService，以及一个中央追踪管理器。

1. traceManager.js – 追踪上下文管理器

// traceManager.js
const { AsyncLocalStorage } = require('async_hooks');
const crypto = require('crypto');

class TraceContextManager {
    constructor() {
        this.als = new AsyncLocalStorage();
    }

    // 生成一个随机的ID
    generateId() {
        return crypto.randomBytes(8).toString('hex'); // 16字符的hex字符串
    }

    /**
     * 在给定 store 的上下文中执行回调函数。
     * @param {object} store - 要存储的上下文对象 (e.g., { traceId, spanId })
     * @param {function} callback - 要执行的函数
     * @param {any[]} args - 传递给回调函数的额外参数
     */
    run(store, callback, ...args) {
        return this.als.run(store, callback, ...args);
    }

    /**
     * 获取当前异步执行流的上下文 store。
     * @returns {object | undefined}
     */
    getStore() {
        return this.als.getStore();
    }

    /**
     * 获取当前 traceId。
     * @returns {string | undefined}
     */
    getTraceId() {
        const store = this.getStore();
        return store ? store.traceId : undefined;
    }

    /**
     * 获取当前 spanId。
     * @returns {string | undefined}
     */
    getSpanId() {
        const store = this.getStore();
        return store ? store.spanId : undefined;
    }

    /**
     * 创建一个新的子 span。
     * @param {string | undefined} parentSpanId - 父 span ID
     * @returns {string} 新的子 span ID
     */
    createChildSpanId(parentSpanId) {
        return parentSpanId ? `${parentSpanId}-${this.generateId()}` : this.generateId();
    }

    // 模拟日志记录器，自动添加追踪ID
    log(level, message, ...args) {
        const traceId = this.getTraceId();
        const spanId = this.getSpanId();
        const prefix = traceId ? `[Trace: ${traceId} | Span: ${spanId || 'N/A'}]` : '[No Trace]';
        console[level](`${prefix} ${message}`, ...args);
    }
}

module.exports = new TraceContextManager();

2. userService.js – 用户服务（提供用户数据，并调用支付服务）

// userService.js
const express = require('express');
const axios = require('axios');
const traceManager = require('./traceManager'); // 引入追踪管理器

const app = express();
const PORT = 3000;

// 模拟数据库操作
function simulateDbQuery(userId) {
    return new Promise(resolve => {
        traceManager.log('info', `DB: 正在查询用户 ${userId} 的信息...`);
        setTimeout(() => {
            resolve({ id: userId, name: `User ${userId}`, email: `user${userId}@example.com` });
        }, 50);
    });
}

// 路由中间件：处理追踪上下文
app.use((req, res, next) => {
    // 从请求头获取或生成 traceId 和 spanId
    const traceId = req.headers['x-trace-id'] || traceManager.generateId();
    const parentSpanId = req.headers['x-span-id']; // 父服务传递过来的 spanId
    const spanId = traceManager.createChildSpanId(parentSpanId); // 当前服务的入口 spanId

    // 使用 traceManager.run 建立当前请求的追踪上下文
    traceManager.run({ traceId, spanId, parentSpanId }, () => {
        traceManager.log('info', `Incoming request: ${req.method} ${req.path}`);
        next();
    });
});

app.get('/users/:id', async (req, res) => {
    const userId = req.params.id;
    const { traceId, spanId } = traceManager.getStore(); // 获取当前上下文

    try {
        // 1. 模拟数据库操作
        const user = await simulateDbQuery(userId);
        traceManager.log('info', `Fetched user: ${user.name}`);

        // 2. 调用 PaymentService 获取用户支付信息
        const paymentSpanId = traceManager.createChildSpanId(spanId); // 为外部调用创建子 span
        traceManager.log('info', `Calling PaymentService for user ${userId} with new span: ${paymentSpanId}`);

        const paymentResponse = await axios.get(`http://localhost:3001/payments/${userId}`, {
            headers: {
                'X-Trace-Id': traceId,          // 注入 traceId
                'X-Span-Id': paymentSpanId      // 注入新的 spanId
            }
        });
        const payments = paymentResponse.data;
        traceManager.log('info', `Received payments for user ${userId}`);

        res.json({ user, payments });
    } catch (error) {
        traceManager.log('error', `Error processing user request: ${error.message}`);
        res.status(500).json({ error: error.message });
    }
});

app.listen(PORT, () => {
    console.log(`User Service running on port ${PORT}`);
});

3. paymentService.js – 支付服务（提供支付数据）

// paymentService.js
const express = require('express');
const traceManager = require('./traceManager'); // 引入追踪管理器

const app = express();
const PORT = 3001;

// 模拟数据库操作
function simulatePaymentDbQuery(userId) {
    return new Promise(resolve => {
        traceManager.log('info', `DB: 正在查询用户 ${userId} 的支付信息...`);
        setTimeout(() => {
            resolve([
                { id: 'pay-001', amount: 100, currency: 'USD' },
                { id: 'pay-002', amount: 50, currency: 'USD' }
            ]);
        }, 70);
    });
}

// 路由中间件：处理追踪上下文 (与 UserService 类似)
app.use((req, res, next) => {
    const traceId = req.headers['x-trace-id'] || traceManager.generateId();
    const parentSpanId = req.headers['x-span-id'];
    const spanId = traceManager.createChildSpanId(parentSpanId);

    traceManager.run({ traceId, spanId, parentSpanId }, () => {
        traceManager.log('info', `Incoming request: ${req.method} ${req.path}`);
        next();
    });
});

app.get('/payments/:userId', async (req, res) => {
    const userId = req.params.userId;
    try {
        const payments = await simulatePaymentDbQuery(userId);
        traceManager.log('info', `Fetched payments for user ${userId}`);
        res.json(payments);
    } catch (error) {
        traceManager.log('error', `Error fetching payments: ${error.message}`);
        res.status(500).json({ error: error.message });
    }
});

app.listen(PORT, () => {
    console.log(`Payment Service running on port ${PORT}`);
});

运行步骤：

分别启动两个服务：node userService.js 和 node paymentService.js。
使用 curl 或浏览器访问用户服务：curl http://localhost:3000/users/123。

你将看到两个服务的控制台输出中都包含了正确的traceId和层层递进的spanId，实现了跨服务的上下文自动传递。

userService.js 的部分输出示例：

User Service running on port 3000
[Trace: 3f6b9c... | Span: 4e1a0d...] Incoming request: GET /users/123
[Trace: 3f6b9c... | Span: 4e1a0d...] DB: 正在查询用户 123 的信息...
[Trace: 3f6b9c... | Span: 4e1a0d...] Fetched user: User 123
[Trace: 3f6b9c... | Span: 4e1a0d...] Calling PaymentService for user 123 with new span: 4e1a0d...-5f7c3b...
[Trace: 3f6b9c... | Span: 4e1a0d...] Received payments for user 123

paymentService.js 的部分输出示例：

Payment Service running on port 3001
[Trace: 3f6b9c... | Span: 4e1a0d...-5f7c3b...] Incoming request: GET /payments/123
[Trace: 3f6b9c... | Span: 4e1a0d...-5f7c3b...] DB: 正在查询用户 123 的支付信息...
[Trace: 3f6b9c... | Span: 4e1a0d...-5f7c3b...] Fetched payments for user 123

可以看到，traceId (3f6b9c...) 在两个服务中保持一致，而spanId则在UserService调用PaymentService时从4e1a0d...更新为4e1a0d...-5f7c3b...，清楚地展示了请求的调用链。

深入理解与注意事项

`AsyncResource`：`AsyncLocalStorage`的基石

AsyncLocalStorage内部也使用了async_hooks.AsyncResource。AsyncResource是一个抽象类，允许开发者手动创建自定义的异步资源，并将其与特定的执行上下文关联。当一个自定义的异步操作完成后，可以通过asyncResource.runInAsyncScope(callback, ...)来确保callback在创建该AsyncResource时的异步上下文中执行。

AsyncLocalStorage正是通过在内部创建和管理AsyncResource实例来绑定和切换上下文的。每次als.run都会隐式地创建一个新的上下文环境。

`AsyncLocalStorage`与`Promise`和`async/await`

AsyncLocalStorage与Promise和async/await完美集成。当一个Promise被创建、链式调用或await等待时，AsyncLocalStorage会自动通过Async Hooks追踪这些异步资源的生命周期，并确保上下文的正确传递。你不需要为Promise.then()或async函数做任何特殊处理。

`AsyncLocalStorage`与`Worker Threads`

重要提示： AsyncLocalStorage的上下文不会自动跨越Worker Threads边界。每个Worker线程都有自己独立的事件循环和Async Hooks实例。如果你需要在Worker Thread中传递主线程的上下文，你需要显式地通过postMessage传递序列化的上下文数据，并在Worker线程内部使用一个新的AsyncLocalStorage.run()来重新建立上下文。

// main.js
const { Worker } = require('worker_threads');
const { AsyncLocalStorage } = require('async_hooks');
const als = new AsyncLocalStorage();

als.run({ requestId: 'main-thread-req-123' }, () => {
    console.log('Main thread context:', als.getStore());

    const worker = new Worker(__filename, { workerData: { context: als.getStore() } });

    worker.on('message', msg => {
        console.log('Main thread received message from worker:', msg);
    });
});

// worker.js (同一个文件，通过 isMainThread 判断)
const { isMainThread, parentPort, workerData } = require('worker_threads');

if (!isMainThread) {
    const workerAls = new AsyncLocalStorage(); // Worker 线程有自己的 AsyncLocalStorage 实例

    // 在 Worker 线程中重新建立上下文
    workerAls.run(workerData.context, () => {
        console.log('Worker thread context:', workerAls.getStore());
        parentPort.postMessage('Hello from worker!');
    });

    // 尝试在 Worker 线程中创建新的异步操作
    workerAls.run({ workerId: 'worker-op-456', ...workerData.context }, () => {
        setTimeout(() => {
            console.log('Worker thread setTimeout context:', workerAls.getStore());
        }, 10);
    });
}

性能开销

Async Hooks是底层API，其事件回调在Node.js内部的每个异步资源生命周期事件时都会被触发，理论上会带来一定的性能开销。然而，AsyncLocalStorage在设计时已经考虑了性能，它只在需要时（即als.run被调用时）才激活内部的Async Hooks机制，并且进行了优化，其性能开销通常是可接受的，尤其是在大部分应用场景中。对于需要极致性能的应用，应进行基准测试以评估其影响。

第三方库的兼容性

大多数现代的Node.js库和框架都已经与AsyncLocalStorage兼容，因为它们内部的异步操作最终都依赖于Node.js的核心异步原语。然而，一些使用自定义异步实现或在早期Node.js版本中编写的库可能需要额外的兼容性检查或猴子补丁。OpenTelemetry等标准库已经提供了对AsyncLocalStorage的良好支持。

总结

Node.js的Async Hooks和AsyncLocalStorage是解决异步上下文中状态丢失问题的强大工具。Async Hooks提供了对异步资源生命周期的底层可见性，而AsyncLocalStorage则在此基础上构建了一个易于使用的抽象，实现了类似线程局部存储的功能，但适用于Node.js的事件驱动、非阻塞模型。

在分布式追踪领域，AsyncLocalStorage是实现上下文自动传递的核心，它极大地简化了Trace ID和Span ID在服务内部跨越各种异步操作的传递。通过在服务入口点建立上下文、在内部操作中访问上下文、并在服务出口点注入上下文，开发者可以构建出健壮且易于维护的分布式追踪系统，从而提升微服务架构的可观测性和调试能力。理解并掌握AsyncLocalStorage，对于构建现代、可维护的Node.js应用至关重要。

Node.js异步编程的挑战：上下文的丢失

Async Hooks：Node.js异步资源的生命周期跟踪器

异步资源与async_id

Async Hooks示例：追踪异步流

AsyncLocalStorage：基于Async Hooks的上下文自动传递

AsyncLocalStorage的核心API

AsyncLocalStorage工作原理简述

AsyncLocalStorage示例：解决上下文丢失问题