发布于 由admin

JavaScript 异步上下文（AsyncContext）提案：实现分布式追踪中隐式 Context 传递的底层存储原语

JavaScript作为一门单线程、事件驱动的语言，其异步编程模型是其核心特性之一。从回调函数、Promise到async/await，JavaScript在处理I/O密集型操作和并发任务方面取得了显著进步。然而，随着应用复杂性的增加，尤其是分布式系统和微服务架构的兴起，一个长期存在的痛点浮现出来：如何在异步执行流中隐式地传递上下文信息。这就是JavaScript AsyncContext 提案所要解决的核心问题，它为分布式追踪中的隐式Context传递提供了底层的存储原语。

一、异步JavaScript中的上下文难题

在任何复杂的应用中，"上下文"（Context）都扮演着至关重要的角色。它指的是在特定执行路径或操作中所需的相关信息集合。例如：

  • 用户ID (User ID)：用于身份验证和授权。
  • 请求ID (Request ID)：用于跟踪单个HTTP请求的生命周期。
  • 事务ID (Transaction ID)：用于标识一系列相关的数据库操作。
  • 追踪ID (Trace ID) 和 跨度ID (Span ID)：在分布式追踪中用于关联跨服务、跨进程的请求。
  • 语言环境 (Locale)：影响日期、时间、数字和货币的格式化。
  • 租户ID (Tenant ID)：在多租户系统中隔离不同租户的数据和逻辑。

这些上下文信息通常需要在代码执行的整个过程中保持一致，无论代码是同步执行还是异步执行。

1.1 同步代码中的上下文传递

在传统的同步编程中，上下文的传递相对简单，通常通过以下方式：

  • 函数参数：最直接的方式，将上下文作为参数显式传递。
  • 类成员变量：在面向对象编程中，将上下文存储在类的实例中。
  • 全局变量/模块变量：适用于少数全局性、不随请求变化的上下文。

例如，一个同步的日志记录函数可能需要userId：

function processOrder(orderId, userId) {
    console.log(`[${userId}] Processing order: ${orderId}`);
    // ... 更多操作 ...
    recordAuditLog(orderId, userId, 'Order processed');
}

function recordAuditLog(orderId, userId, message) {
    console.log(`[AUDIT - ${userId}] Order ${orderId}: ${message}`);
}

processOrder('ORD-123', 'USER-A');

这种显式传递方式在同步代码中是清晰且易于理解的。

1.2 异步代码中的上下文挑战

然而，当JavaScript的异步特性介入时，上下文传递的复杂性急剧增加。JavaScript的事件循环机制使得代码的执行流不再是线性的，而是被异步操作（如定时器、网络请求、文件I/O、Promise链）打断和恢复。在这些异步边界上，显式传递上下文变得异常繁琐和脆弱。

考虑一个典型的Web服务器场景：当一个HTTP请求到达时，我们希望为这个请求生成一个唯一的requestId。这个requestId需要在处理这个请求的所有异步操作中（例如，数据库查询、外部API调用、日志记录）都可用，以便于调试和追踪。

问题示例：上下文丢失

假设我们有一个处理用户请求的函数，它包含异步操作：

// 假设这是我们的请求处理入口
function handleRequest(request) {
    const requestId = generateUniqueId(); // 为当前请求生成一个唯一的ID
    console.log(`[${requestId}] Request started.`);

    // 模拟一个异步操作，例如数据库查询
    setTimeout(() => {
        // 在这里，如何获取到上面的 requestId？
        // 如果没有显式传递，requestId 将无法访问，除非它是全局的。
        // 但如果是全局的，又会与同时进行的另一个请求的 requestId 混淆。
        console.log(`[???] Database operation completed.`);

        // 模拟另一个异步操作，例如外部API调用
        fetch('https://some.api/data')
            .then(response => response.json())
            .then(data => {
                // 在这里，如何获取到 requestId？
                console.log(`[???] API call completed. Data:`, data);
                logFinalStatus(requestId); // 如果 requestId 无法获取，这里会报错或记录错误信息
            });
    }, 100);

    function logFinalStatus(currentRequestId) {
        console.log(`[${currentRequestId}] Request finished.`);
    }
}

// 模拟两个并发请求
handleRequest({}); // 请求 A
handleRequest({}); // 请求 B

在上面的例子中，setTimeout的回调函数和fetch的.then()回调函数默认无法直接访问handleRequest作用域中的requestId。如果我们将requestId作为参数显式传递，那么每个异步回调都需要接受这个参数，并且每次调用异步函数时也需要传递它。这被称为"参数钻取"（prop drilling），它会：

  • 污染函数签名：许多函数会因为追踪上下文而增加不必要的参数。
  • 增加代码复杂性：每增加一个异步层级，都需要手动传递。
  • 易于出错：一旦忘记传递，上下文就会丢失。
  • 难以维护：修改上下文结构会影响大量函数签名。

1.3 现有解决方案及其局限性

为了解决异步上下文传递的问题，开发者们尝试了多种方案，但每种方案都有其局限性：

  1. 显式参数传递 (Parameter Drilling)：

    • 优点：最清晰，没有隐式行为。
    • 缺点：如前所述，代码冗余，易错，难以维护。不适用于第三方库。
    function handleRequest(request) {
    const requestId = generateUniqueId();
    console.log(`[${requestId}] Request started.`);

    setTimeout(() => {
        handleDatabaseOperation(requestId);
    }, 100);

    function handleDatabaseOperation(currentRequestId) {
        console.log(`[${currentRequestId}] Database operation completed.`);
        fetch('https://some.api/data')
            .then(response => response.json())
            .then(data => {
                handleApiCallResult(currentRequestId, data);
            });
    }

    function handleApiCallResult(currentRequestId, data) {
        console.log(`[${currentRequestId}] API call completed. Data:`, data);
        logFinalStatus(currentRequestId);
    }

    function logFinalStatus(currentRequestId) {
        console.log(`[${currentRequestId}] Request finished.`);
    }
}

    显然，这大大增加了代码的复杂性。

  2. 闭包 (Closures)：
    如果异步操作是在定义它们的函数内部触发的，闭包可以捕获其父作用域的变量。

    function handleRequest(request) {
    const requestId = generateUniqueId();
    console.log(`[${requestId}] Request started.`);

    setTimeout(() => {
        // 闭包捕获了 requestId
        console.log(`[${requestId}] Database operation completed.`);
        fetch('https://some.api/data')
            .then(response => response.json())
            .then(data => {
                // 闭包捕获了 requestId
                console.log(`[${requestId}] API call completed. Data:`, data);
                logFinalStatus(); // 调用内部函数，它也能访问 requestId
            });
    }, 100);

    function logFinalStatus() {
        console.log(`[${requestId}] Request finished.`);
    }
}
    • 优点：在某些情况下非常有效，避免了参数钻取。
    • 缺点：
      • 不适用于上下文需要跨越多个模块、多个函数、或由第三方库调用的情况。
      • 如果异步回调在其父函数作用域之外定义，闭包将失效。
      • 可能导致内存泄漏，如果闭包捕获了大对象且生命周期过长。
      • 无法处理用户定义的事件监听器，例如eventEmitter.on('myEvent', handler)，handler无法直接访问emit时的上下文。

  3. 全局变量/模块变量 (Global/Module Variables)：
    在单线程JavaScript中，全局变量在概念上与线程局部存储（Thread-Local Storage, TLS）有些相似，但它无法区分并发请求。

    // 危险的做法，无法区分并发请求
let currentRequestId = null;

function handleRequest(request) {
    currentRequestId = generateUniqueId(); // 设置全局变量
    console.log(`[${currentRequestId}] Request started.`);

    setTimeout(() => {
        console.log(`[${currentRequestId}] Database operation completed.`); // 可能会获取到错误的 requestId
    }, 100);
}

// 请求 A
handleRequest({}); // currentRequestId = 'REQ-A'

// 请求 B (几乎同时到达)
handleRequest({}); // currentRequestId 被覆盖为 'REQ-B'

// 此时 'REQ-A' 相关的 setTimeout 回调触发，它会错误地读取到 'REQ-B'
    • 优点：简单粗暴。
    • 缺点：严重缺陷。无法处理并发请求，会导致上下文混淆，数据污染。在实际应用中几乎不可用。

  4. Node.js async_hooks 和 AsyncLocalStorage：
    Node.js提供了一个底层的API async_hooks，它允许开发者追踪异步资源的生命周期。在此基础上，Node.js v13.10.0 引入了 AsyncLocalStorage 类，它提供了一种在异步操作之间存储和检索数据的机制，类似于线程局部存储。

    // Node.js 示例
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();

function generateUniqueId() {
    return `REQ-${Math.random().toString(36).substr(2, 9)}`;
}

function handleRequest(request) {
    const requestId = generateUniqueId();

    // 使用 run 方法在当前异步上下文中设置 requestId
    asyncLocalStorage.run({ requestId }, () => {
        console.log(`[${asyncLocalStorage.getStore().requestId}] Request started.`);

        setTimeout(() => {
            // 在 setTimeout 的回调中，上下文会自动恢复
            console.log(`[${asyncLocalStorage.getStore().requestId}] Database operation completed.`);
            fetch('https://some.api/data')
                .then(response => response.json())
                .then(data => {
                    console.log(`[${asyncLocalStorage.getStore().requestId}] API call completed. Data:`, data);
                    logFinalStatus();
                });
        }, 100);

        function logFinalStatus() {
            console.log(`[${asyncLocalStorage.getStore().requestId}] Request finished.`);
        }
    });
}

// 模拟两个并发请求
handleRequest({});
handleRequest({});
    • 优点：解决了并发请求的上下文隔离问题，实现了隐式传递。
    • 缺点：
      • Node.js 专属：不适用于浏览器环境。
      • 性能开销：async_hooks是一个底层API，启用它会增加一定的运行时开销，因为它需要追踪所有异步资源的创建、执行和销毁。虽然AsyncLocalStorage比直接使用async_hooks更优化，但仍然存在开销。
      • API相对复杂：虽然AsyncLocalStorage简化了，但其底层机制仍然需要理解。

上述的局限性，尤其是在浏览器端缺乏一个标准化的、高性能的解决方案，催生了 AsyncContext 提案。

二、AsyncContext：异步上下文的底层存储原语

AsyncContext 提案旨在为JavaScript提供一个标准化的、高效的、跨平台的异步上下文管理机制。它允许开发者在异步操作中隐式地传递数据，而无需手动修改函数签名或担心并发问题。它的核心思想是：在异步操作开始时“捕获”当前的上下文状态，并在异步操作恢复时“恢复”这个上下文状态。这类似于线程局部存储（Thread-Local Storage, TLS），但适用于JavaScript的异步执行模型。

2.1 AsyncContext 的核心概念和API

AsyncContext 提案引入了两个主要构造器：AsyncContext 和 AsyncContextSnapshot。

  1. new AsyncContext()：
    创建一个AsyncContext实例。每个AsyncContext实例代表一个独立的上下文键，它可以存储一个值。你可以创建多个AsyncContext实例来存储不同类型的上下文信息（例如，一个用于traceId，一个用于spanId，一个用于userId）。

    const traceIdContext = new AsyncContext();
const spanIdContext = new AsyncContext();
const userIdContext = new AsyncContext();

  2. AsyncContext.prototype.run(callback, contextData)：
    这是AsyncContext最核心的方法。它在执行callback函数时，会创建一个新的上下文栈帧（或称之为“作用域”），并将contextData（一个Map对象或AsyncContext实例到值的映射）应用到这个栈帧上。在callback及其内部触发的所有异步操作中，这个contextData都是可用的。当callback执行完毕，或者抛出错误时，这个上下文栈帧会被移除，之前的上下文状态会被恢复。

    • callback: 一个函数，其内部执行的所有异步代码都将在这个新的上下文中运行。
    • contextData: 一个Map对象，将AsyncContext实例映射到它们的值。
    const myContext = new AsyncContext();

async function fetchData() {
    // 在这里，myContext.get() 将返回 'value-from-run'
    const data = await fetch('/api/data');
    console.log(`Data fetched with context: ${myContext.get()}`);
}

asyncContext.run(new Map([[myContext, 'value-from-run']]), async () => {
    console.log(`Initial context: ${myContext.get()}`); // 'value-from-run'
    await fetchData();
    console.log(`After fetchData, context still: ${myContext.get()}`); // 'value-from-run'
});

console.log(`Outside run, context: ${myContext.get()}`); // undefined

  3. AsyncContext.prototype.get()：
    获取当前活动上下文栈中，最近一次为该AsyncContext实例设置的值。如果没有设置，则返回undefined。

    const myContext = new AsyncContext();

function logContext() {
    console.log(`Current context value: ${myContext.get()}`);
}

logContext(); // Current context value: undefined

asyncContext.run(new Map([[myContext, 'first-value']]), () => {
    logContext(); // Current context value: first-value

    asyncContext.run(new Map([[myContext, 'second-value']]), () => {
        logContext(); // Current context value: second-value
    });

    logContext(); // Current context value: first-value (second-value 的 run 块已结束)
});

logContext(); // Current context value: undefined (first-value 的 run 块已结束)

  4. new AsyncContextSnapshot()：
    AsyncContextSnapshot 用于捕获当前的所有AsyncContext实例及其对应的值。它返回一个不可变的对象，代表了某个时间点的上下文状态。

    const traceIdContext = new AsyncContext();
const spanIdContext = new AsyncContext();

let snapshot = null;

asyncContext.run(new Map([[traceIdContext, 'trace-1'], [spanIdContext, 'span-A']]), () => {
    console.log(`Inside run 1: Trace=${traceIdContext.get()}, Span=${spanIdContext.get()}`);
    snapshot = new AsyncContextSnapshot(); // 捕获当前上下文
});

// 此时 traceIdContext 和 spanIdContext 已经没有值了
console.log(`Outside run 1: Trace=${traceIdContext.get()}, Span=${spanIdContext.get()}`); // undefined, undefined

// 可以在任何时候使用这个快照来恢复上下文
snapshot.run(() => {
    console.log(`Inside snapshot run: Trace=${traceIdContext.get()}, Span=${spanIdContext.get()}`); // trace-1, span-A
});

    AsyncContextSnapshot的用例包括：

    • 在事件监听器中恢复上下文：当事件被触发时，通常会丢失原始的上下文。通过在注册监听器时捕获快照，可以在事件处理函数中恢复它。
    • 跨postMessage边界：在Web Workers或iframe之间传递上下文。

  5. AsyncContextSnapshot.prototype.run(callback)：
    执行callback函数，并在此期间应用快照捕获的上下文。

2.2 AsyncContext 如何解决上下文丢失问题

AsyncContext的强大之处在于它与JavaScript的异步原语（如Promise、setTimeout、queueMicrotask等）深度集成。当一个异步操作被调度时（例如，调用setTimeout或返回一个Promise），当前的AsyncContext栈会被“记住”。当异步操作的回调函数被执行时，AsyncContext栈会自动恢复到调度时的状态。

这种隐式传播机制是其核心价值：

  • 无缝集成：开发者无需修改现有异步代码结构。
  • 自动传播：上下文在Promise链、async/await、定时器、事件监听器等异步边界上自动传递。
  • 隔离性：不同请求或操作的上下文彼此隔离，避免了全局变量的冲突。

三、分布式追踪中的隐式Context传递

分布式追踪是微服务架构中不可或缺的工具。它允许开发者可视化一个请求在多个服务之间流动的路径，从而识别性能瓶颈、诊断错误和理解系统行为。一个完整的分布式追踪通常由以下核心组件构成：

  • 追踪ID (Trace ID)：一个全局唯一的标识符，用于识别整个请求的端到端旅程。从请求进入系统的第一个服务开始，直到它完成。
  • 跨度ID (Span ID)：一个局部唯一的标识符，用于标识追踪中的单个操作（例如，一个函数调用、一个HTTP请求、一个数据库查询）。每个Span都有一个父Span，形成一个树状结构。
  • 父跨度ID (Parent Span ID)：指向当前Span的父Span的ID，用于建立Span之间的层级关系。
  • 追踪上下文 (Trace Context)：包含了Trace ID、Span ID以及其他可能需要在服务之间传递的元数据（如采样决策）。通常通过HTTP头部进行跨服务传播。
  • Baggage (行李)：键值对的集合，可以在整个追踪中传递的业务相关或调试相关的数据，例如用户ID、功能标志等。

3.1 分布式追踪中的传播挑战

分布式追踪面临两大传播挑战：

  1. 跨服务传播 (Inter-service Propagation)：
    当一个服务调用另一个服务时，Trace Context必须通过网络协议（通常是HTTP头部）从调用方传递到被调用方。例如，W3C Trace Context标准定义了traceparent和tracestate等HTTP头部来承载这些信息。

    Request -> Service A (extracts context, starts new span) -> Call Service B (injects context into HTTP headers) -> Service B (extracts context, starts new child span)

  2. 服务内部传播 (Intra-service Propagation)：
    在一个服务内部，当请求经过多个异步操作时，Trace Context（特别是当前的Trace ID和Span ID）必须在这些操作之间隐式传递。这正是AsyncContext所要解决的核心问题。例如，在一个Node.js服务中，一个HTTP请求可能触发数据库查询、缓存访问、外部API调用，所有这些操作都应该关联到同一个Trace ID和当前活跃的Span ID。

AsyncContext为服务内部传播提供了一个理想的解决方案，因为它能够以一种标准、高性能的方式，在所有异步边界上自动维护和恢复上下文。

四、使用 AsyncContext 实现分布式追踪 (代码示例)

我们将通过一系列代码示例来演示如何使用 AsyncContext 来构建一个基本的分布式追踪系统。

4.1 基础设置：定义上下文实例

首先，我们需要为追踪ID、当前活跃的Span ID和Baggage定义 AsyncContext 实例。

// traceContext.js
const traceIdContext = new AsyncContext();
const spanIdContext = new AsyncContext();
const baggageContext = new AsyncContext(); // 用于传递额外的数据

function getTraceId() {
    return traceIdContext.get();
}

function getSpanId() {
    return spanIdContext.get();
}

function getBaggage() {
    return baggageContext.get() || {}; // 默认为空对象
}

function setBaggage(key, value) {
    const currentBaggage = getBaggage();
    baggageContext.run(new Map([[baggageContext, { ...currentBaggage, [key]: value }]]), () => {
        // Baggage is updated for this scope
    });
}

// 导出一个对象，方便管理
const trace = {
    traceIdContext,
    spanIdContext,
    baggageContext,
    getTraceId,
    getSpanId,
    getBaggage,
    setBaggage,
};

// 模拟 AsyncContext API，直到它被广泛支持
// 实际生产环境应使用浏览器或Node.js内置的 AsyncContext
if (typeof AsyncContext === 'undefined') {
    // 这是一个极简的 polyfill 模拟，不具备 AsyncContext 完整的性能和异步传播能力
    // 仅用于演示 API 形状。实际 polyfill 需要复杂的 hook 机制。
    class MockAsyncContext {
        constructor() {
            this._value = undefined;
        }
        run(contextMap, callback) {
            const oldValue = this._value;
            const entry = contextMap.get(this);
            if (entry !== undefined) {
                this._value = entry;
            }
            try {
                return callback();
            } finally {
                this._value = oldValue;
            }
        }
        get() {
            return this._value;
        }
    }
    class MockAsyncContextSnapshot {
        constructor() {
            this._snapshot = new Map();
            // 捕获所有已注册的 MockAsyncContext 实例的值
            // 这是一个简化版本，实际 AsyncContextSnapshot 会自动知道所有上下文
            if (globalThis._mockAsyncContexts) {
                for (const ctx of globalThis._mockAsyncContexts) {
                    this._snapshot.set(ctx, ctx.get());
                }
            }
        }
        run(callback) {
            // 这里需要一个更复杂的机制来恢复所有的上下文
            // 暂时忽略，因为 MockAsyncContext 无法在异步边界上自动传播
            console.warn("MockAsyncContextSnapshot.run is highly simplified and won't work across true async boundaries.");
            return callback();
        }
    }

    // 注册 MockAsyncContexts
    globalThis._mockAsyncContexts = globalThis._mockAsyncContexts || new Set();
    const originalAsyncContext = globalThis.AsyncContext;
    globalThis.AsyncContext = function() {
        const instance = new MockAsyncContext();
        globalThis._mockAsyncContexts.add(instance);
        return instance;
    };
    globalThis.AsyncContextSnapshot = MockAsyncContextSnapshot;
    console.warn("Using MockAsyncContext - this is a simplified emulation and does NOT provide true async propagation.");
}

export { traceIdContext, spanIdContext, baggageContext, getTraceId, getSpanId, getBaggage, setBaggage };

为了方便演示，我们将其封装在一个trace.js文件中。请注意，上面的AsyncContext模拟是一个非常简化的版本，它无法在真正的异步边界上自动传播上下文。它仅用于演示API的形状和同步调用时的行为。在实际支持AsyncContext的环境中，这些模拟代码是不需要的。

4.2 示例1：Web服务器中的请求处理

假设我们有一个简单的Web服务器（例如，使用Express框架），我们需要在每个请求的生命周期内追踪上下文。

// server.js
import express from 'express';
import { traceIdContext, spanIdContext, getTraceId, getSpanId, getBaggage, setBaggage } from './trace.js';
import { v4 as uuidv4 } from 'uuid'; // 用于生成唯一的ID

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

// 模拟一个数据库服务
const db = {
    query: async (sql, params) => {
        const traceId = getTraceId();
        const spanId = getSpanId();
        console.log(`[${traceId}:${spanId}] DB Query: ${sql} with params ${JSON.stringify(params)}`);
        await new Promise(resolve => setTimeout(resolve, 50)); // 模拟数据库延迟
        return [{ id: 1, name: 'Item A' }];
    }
};

// 模拟一个外部API服务
const externalApi = {
    call: async (url, data) => {
        const traceId = getTraceId();
        const spanId = getSpanId();
        const baggage = getBaggage();
        console.log(`[${traceId}:${spanId}] Calling External API: ${url} with data ${JSON.stringify(data)} and baggage ${JSON.stringify(baggage)}`);
        await new Promise(resolve => setTimeout(resolve, 100)); // 模拟API延迟
        return { status: 'success', externalData: 'some_info' };
    }
};

// 路由处理函数
async function processOrder(req, res) {
    const traceId = getTraceId(); // 获取当前请求的 Trace ID
    const parentSpanId = getSpanId(); // 获取当前请求的 Span ID (作为子 Span 的父 Span)

    // 为订单处理逻辑创建一个新的 Span
    const orderSpanId = uuidv4().substring(0, 8);

    await spanIdContext.run(new Map([[spanIdContext, orderSpanId]]), async () => {
        console.log(`[${traceId}:${getSpanId()}] Processing order for user: ${req.params.userId}`);

        // 设置一些 baggage 数据
        setBaggage('userId', req.params.userId);
        setBaggage('userRole', 'admin'); // 假设通过认证获取

        try {
            // 模拟数据库操作
            const dbResult = await db.query('SELECT * FROM orders WHERE user_id = ?', [req.params.userId]);
            console.log(`[${traceId}:${getSpanId()}] Database result:`, dbResult);

            // 模拟外部API调用
            const apiResult = await externalApi.call('/payments/process', { userId: req.params.userId, amount: 100 });
            console.log(`[${traceId}:${getSpanId()}] API call result:`, apiResult);

            // 读取 baggage
            const currentBaggage = getBaggage();
            console.log(`[${traceId}:${getSpanId()}] Current baggage:`, currentBaggage);

            res.json({
                message: `Order processed for ${req.params.userId}`,
                traceId,
                spanId: getSpanId(),
                baggage: currentBaggage
            });
        } catch (error) {
            console.error(`[${traceId}:${getSpanId()}] Error processing order:`, error);
            res.status(500).json({ error: 'Internal Server Error', traceId });
        }
    });
}

// 中间件：为每个传入请求设置追踪上下文
app.use((req, res, next) => {
    // 尝试从请求头中获取 Trace ID 和 Span ID (模拟 W3C Trace Context)
    // 如果没有，则生成新的
    const existingTraceId = req.headers['x-trace-id'] || uuidv4().substring(0, 8);
    const existingSpanId = req.headers['x-span-id'] || uuidv4().substring(0, 8);

    // 使用 AsyncContext.run 来设置当前请求的 Trace ID 和 Span ID
    // 所有的后续异步操作都会自动继承这个上下文
    const contextMap = new Map([
        [traceIdContext, existingTraceId],
        [spanIdContext, existingSpanId]
    ]);

    traceIdContext.run(contextMap, () => {
        console.log(`------------------------------------------------------`);
        console.log(`[${getTraceId()}:${getSpanId()}] Incoming Request: ${req.method} ${req.url}`);
        next(); // 继续处理请求
    });
});

app.get('/order/:userId', processOrder);

app.listen(port, () => {
    console.log(`Server listening on http://localhost:${port}`);
});

运行方式：

  1. 保存 trace.js 和 server.js。
  2. 安装依赖：npm install express uuid
  3. 运行 node server.js
  4. 在浏览器或使用curl访问：http://localhost:3000/order/user123
    或者带上追踪头：curl -H "x-trace-id:abc" -H "x-span-id:def" http://localhost:3000/order/user456

观察输出：
你会看到所有的日志消息都带有正确的traceId和spanId，即使它们是在setTimeout、Promise或async/await中执行的。db.query和externalApi.call这些模拟函数能够隐式地访问到由中间件设置的上下文。Baggage也成功地在整个请求链路中传递。

4.3 示例2：复杂异步流中的上下文传播

让我们更细致地观察 AsyncContext 如何在 Promise、async/await 和 setTimeout 中工作。

// complex_async_flow.js
import { traceIdContext, spanIdContext, getTraceId, getSpanId, getBaggage, setBaggage } from './trace.js';
import { v4 as uuidv4 } from 'uuid';

async function performDeeplyNestedOperation(depth) {
    const traceId = getTraceId();
    const spanId = getSpanId();
    const baggage = getBaggage();

    console.log(`[${traceId}:${spanId}] Depth ${depth}: Starting operation. Baggage: ${JSON.stringify(baggage)}`);

    if (depth > 0) {
        // 模拟一个 Promise 链
        await new Promise(resolve => setTimeout(resolve, 20 * depth)); // 模拟异步延迟
        console.log(`[${getTraceId()}:${getSpanId()}] Depth ${depth}: After Promise/setTimeout.`);

        // 在新的 Span 中执行下一层操作
        const newSpanId = uuidv4().substring(0, 8);
        await spanIdContext.run(new Map([[spanIdContext, newSpanId]]), async () => {
            await performDeeplyNestedOperation(depth - 1);
        });
    }

    console.log(`[${getTraceId()}:${getSpanId()}] Depth ${depth}: Finishing operation.`);
}

async function startTrace() {
    const initialTraceId = uuidv4().substring(0, 8);
    const initialSpanId = uuidv4().substring(0, 8);

    await traceIdContext.run(new Map([
        [traceIdContext, initialTraceId],
        [spanIdContext, initialSpanId]
    ]), async () => {
        console.log(`--- Starting new trace: ${getTraceId()} ---`);
        setBaggage('initialUser', 'Alice'); // 设置初始 Baggage

        await performDeeplyNestedOperation(3); // 启动深度嵌套操作

        console.log(`--- Trace ${getTraceId()} finished. Final Baggage: ${JSON.stringify(getBaggage())} ---`);
    });
}

// 模拟两个并发的追踪
startTrace();
setTimeout(startTrace, 50); // 稍微延迟，以便观察并行输出

运行方式：

  1. 保存 trace.js 和 complex_async_flow.js。
  2. 安装依赖：npm install uuid
  3. 运行 node complex_async_flow.js

观察输出：
你会看到两个独立的追踪流，它们的traceId和spanId是完全隔离的。performDeeplyNestedOperation函数在每次递归调用时都会创建一个新的子Span，并且traceId和baggage在整个异步调用栈中都被正确地传递和访问。

4.4 表格：AsyncContext、手动传递和 AsyncLocalStorage 比较

特性/方法 手动参数传递 Node.js AsyncLocalStorage AsyncContext (提案)
隐式传播 否 是 是
跨异步边界 需手动传递 自动 自动
并发隔离 需手动管理 是 是
API 复杂性 低（但代码复杂性高） 中等 简单
性能开销 低（仅参数传递） 中等（基于 async_hooks） 低（引擎原生支持，优化空间大）
平台支持 所有 JavaScript 环境 Node.js 专属 Web 平台（浏览器、Node.js 等）通用
代码侵入性 高（污染函数签名） 低（仅在入口点和上下文更新时） 低（仅在入口点和上下文更新时）
第三方库兼容性 差（库通常不接受额外上下文参数） 良好（库无需修改即可获取上下文） 良好（库无需修改即可获取上下文）
主要用例 简单同步流程 Node.js 服务端追踪、日志等 统一的异步上下文管理，如分布式追踪、认证等

五、高级话题与考量

5.1 性能影响

AsyncContext的性能是其设计时的重要考量。与Node.js的async_hooks相比，AsyncContext被设计为拥有更低的性能开销，原因如下：

  • 引擎原生支持：AsyncContext是JavaScript引擎内部实现的原语，可以进行高度优化。它不需要像async_hooks那样通过JavaScript层面的回调来追踪所有异步资源的生命周期。
  • 按需激活：AsyncContext只在run方法被调用时才激活上下文管理，并且只管理明确创建的AsyncContext实例。而async_hooks会追踪所有异步操作，无论你是否需要它们的上下文。
  • 更细粒度的控制：开发者可以根据需要创建少量的AsyncContext实例，而不是无差别地追踪所有。

尽管如此，任何隐式机制都会带来一定的运行时开销。过度频繁地调用AsyncContext.run或存储大量数据可能会影响性能。最佳实践是只存储必要的、少量且不变的上下文信息。

5.2 浏览器与 Node.js 环境

AsyncContext是一个Web平台提案，这意味着它旨在成为浏览器和Node.js等所有JavaScript运行时环境的通用标准。一旦被广泛实现，它将结束目前Node.js独有的AsyncLocalStorage的局面，为前端和后端JS应用提供统一的上下文管理方案。

  • 浏览器：对于浏览器应用，目前缺乏类似AsyncLocalStorage的强大工具。AsyncContext的引入将极大地简化复杂前端应用（如单页应用、Web Workers）中的状态管理、性能监控和调试。
  • Node.js：AsyncContext将成为AsyncLocalStorage的标准化替代品，可能具有更好的性能和更简洁的API。

5.3 与其他API的交互

AsyncContext旨在与现有的和未来的异步API无缝集成：

  • Web Workers：上下文默认不跨越Web Worker边界。要将上下文从主线程传递到Worker，或反之，需要使用AsyncContextSnapshot手动捕获上下文，并通过postMessage序列化传递，然后在Worker中使用snapshot.run()恢复。
  • Streams：AsyncContext应该能够通过Node.js的Stream API和Web Streams API的异步操作进行传播。
  • Event Emitters：当一个事件监听器被调用时，它应该能够访问到触发该事件时的上下文。AsyncContext正是为此设计的。

5.4 潜在陷阱与最佳实践

  1. 避免滥用：AsyncContext适用于隐式、环境性的上下文，而不是显式数据流。不要将所有数据都塞进AsyncContext，它不是替代函数参数或状态管理库的方案。
  2. 数据不可变性：存储在AsyncContext中的数据应被视为不可变的。如果需要修改，请创建一个新的Map或对象并重新调用run来设置新的上下文。直接修改通过get()获取的对象可能会导致意外的行为，因为它可能在多个run作用域中共享。
  3. 正确划分作用域：AsyncContext.run创建了一个临时的上下文作用域。确保你的run块覆盖了所有需要该上下文的异步操作。
  4. 初始化与清理：在请求或事务的入口点设置上下文，并在其结束时（或通过run的自动清理）确保上下文被正确移除或恢复。

六、AsyncContext 与 async_hooks 的对比

虽然Node.js的async_hooks和AsyncLocalStorage已经为Node.js环境提供了异步上下文管理的能力，但AsyncContext提案代表了JavaScript生态系统向前迈出的重要一步。

特性/方案 async_hooks (Node.js) AsyncLocalStorage (Node.js, 基于 async_hooks) AsyncContext (Web 平台提案)
级别 低级 API，追踪所有异步资源生命周期 高级 API，专注于异步上下文存储和检索 高级 API，专注于异步上下文存储和检索
目的 调试、分析、自定义诊断工具 异步上下文管理，如追踪、日志 异步上下文管理，如追踪、日志
性能 较高开销，因为追踪所有异步资源 较低 async_hooks 直接使用，但仍有开销 预计最低开销，引擎原生支持，按需激活
使用难度 复杂，需要深入理解事件循环和异步资源 相对简单 简单直观，类似 AsyncLocalStorage 但更标准化
平台 Node.js 专属 Node.js 专属 Web 平台（浏览器、Node.js、Deno 等）通用
核心机制 依赖于对异步资源创建、初始化、执行、销毁的回调注册 内部使用 async_hooks 来关联上下文到异步执行流 引擎内部直接集成，将上下文栈与异步任务调度关联
适用场景 需要对异步运行时进行深度监控和干预的场景 Node.js 服务端应用中的隐式上下文传递 所有 JavaScript 运行时中统一、高性能的隐式上下文传递

总结：

  • async_hooks 是Node.js的底层工具箱，适用于构建更高级别的异步工具（如性能分析器、自定义调试器）。
  • AsyncLocalStorage 是构建在async_hooks之上的一个便捷层，专为Node.js环境下的异步上下文传播而设计。
  • AsyncContext 是一个更通用、更标准、更高效的解决方案，旨在取代AsyncLocalStorage并将其功能扩展到整个JavaScript生态系统。对于绝大多数需要隐式上下文传播的应用场景，AsyncContext将是首选。

七、未来影响与生态系统

AsyncContext提案的引入将对JavaScript生态系统产生深远影响：

  1. 简化库开发：
    库开发者不再需要考虑如何显式传递上下文，或者要求用户提供复杂的上下文管理机制。他们的代码可以变得更简洁，更专注于核心逻辑。例如，一个日志库可以直接从AsyncContext中获取traceId，而无需将其作为参数传递。

  2. 标准化分布式追踪：
    AsyncContext将成为实现OpenTelemetry等分布式追踪标准在JavaScript运行时中的理想底层机制。无论是前端（如Web SDK）还是后端（如Node.js SDK），追踪代理都可以利用AsyncContext来自动捕获和传播追踪上下文，大大降低了集成难度。

  3. 提升可观测性：
    通过统一的上下文管理，应用程序的日志、指标和追踪将更容易关联起来，从而提供更全面的可观测性。开发者可以更轻松地理解用户请求在复杂系统中的行为，快速定位问题。

  4. 减少样板代码：
    告别参数钻取和手动上下文管理，开发者可以编写更干净、更易读、更健壮的代码。这将显著提高开发效率和代码质量。

八、结语

AsyncContext提案是JavaScript异步编程领域的一个重要里程碑，它填补了长期以来在异步上下文管理方面的空白。通过提供一个标准化的、高性能的底层原语，AsyncContext极大地简化了分布式追踪、日志记录、认证授权等复杂场景下的隐式上下文传递。它不仅将提升开发者体验，还将推动JavaScript生态系统在构建可观测、可维护的现代应用方面迈向新的高度。随着这一提案的最终定稿和广泛实现，我们有理由期待一个更加强大和高效的JavaScript开发体验。

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注