JavaScript Async Local Storage：精通请求范围的上下文管理

在异步 JavaScript 的世界中，跨各种操作管理上下文可能成为一项复杂的挑战。像通过函数调用传递上下文对象的传统方法，通常会导致代码冗长和笨拙。幸运的是，JavaScript 异步本地存储 (Async Local Storage, ALS) 为在异步环境中管理请求范围的上下文提供了一种优雅的解决方案。本文深入探讨了 ALS 的复杂性，探索了其优势、实现和实际用例。

什么是异步本地存储 (Async Local Storage)？

异步本地存储 (ALS) 是一种机制，允许您存储特定于异步执行上下文的本地数据。此上下文通常与一个请求或事务相关联。可以把它看作是为像 Node.js 这样的异步 JavaScript 环境创建一种等同于线程本地存储的方式。与传统的线程本地存储（不直接适用于单线程 JavaScript）不同，ALS 利用异步原语在异步调用之间传播上下文，而无需显式地将其作为参数传递。

ALS 背后的核心思想是，在给定的异步操作（例如，处理一个 Web 请求）中，您可以存储和检索与该特定操作相关的数据，从而确保隔离并防止不同并发异步任务之间的上下文污染。

为什么使用异步本地存储？

在现代 JavaScript 应用程序中，采用异步本地存储有几个令人信服的理由：

• 简化的上下文管理：避免通过多个函数调用传递上下文对象，减少代码冗余并提高可读性。
• 提高代码可维护性：集中管理上下文逻辑，使其更易于修改和维护应用程序上下文。
• 增强的调试和追踪：传播特定于请求的信息，以便在应用程序的各个层中追踪请求。
• 与中间件无缝集成：ALS 与 Express.js 等框架中的中间件模式很好地集成，使您能够在请求生命周期的早期捕获和传播上下文。
• 减少样板代码：无需在每个需要上下文的函数中显式管理上下文，从而使代码更简洁、更专注。

核心概念与 API

异步本地存储 API 在 Node.js (版本 13.10.0 及更高版本) 中通过 `async_hooks` 模块提供，包含以下关键组件：

• `AsyncLocalStorage` 类：用于创建和管理异步存储实例的核心类。
• `run(store, callback, ...args)` 方法：在特定的异步上下文中执行一个函数。`store` 参数代表与该上下文关联的数据，`callback` 是要执行的函数。
• `getStore()` 方法：检索与当前异步上下文关联的数据。如果没有活动的上下文，则返回 `undefined`。
• `enterWith(store)` 方法：使用提供的 store 显式进入一个上下文。请谨慎使用，因为它可能使代码更难理解。
• `disable()` 方法：禁用 AsyncLocalStorage 实例。

实践示例与代码片段

让我们来探索一些如何在 JavaScript 应用程序中使用异步本地存储的实践示例。

基本用法

此示例演示了一个简单的场景，我们在一个异步上下文中存储和检索请求 ID。

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

const asyncLocalStorage = new AsyncLocalStorage();

function processRequest(req, res) {
  const requestId = Math.random().toString(36).substring(2, 15);

  asyncLocalStorage.run({ requestId }, () => {
    // 模拟异步操作
    setTimeout(() => {
      const currentContext = asyncLocalStorage.getStore();
      console.log(`Request ID: ${currentContext.requestId}`);
      res.end(`Request processed with ID: ${currentContext.requestId}`);
    }, 100);
  });
}

// 模拟传入的请求
const http = require('http');

const server = http.createServer((req, res) => {
  processRequest(req, res);
});

server.listen(3000, () => {
  console.log('Server listening on port 3000');
});

在 Express.js 中间件中使用 ALS

此示例展示了如何将 ALS 与 Express.js 中间件集成，以捕获特定于请求的信息，并使其在整个请求生命周期中可用。

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

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();

// 用于捕获请求 ID 的中间件
app.use((req, res, next) => {
  const requestId = Math.random().toString(36).substring(2, 15);
  asyncLocalStorage.run({ requestId }, () => {
    next();
  });
});

// 路由处理器
app.get('/', (req, res) => {
  const currentContext = asyncLocalStorage.getStore();
  const requestId = currentContext.requestId;
  console.log(`Handling request with ID: ${requestId}`);
  res.send(`Request processed with ID: ${requestId}`);
});

app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

高级用例：分布式追踪

ALS 在分布式追踪场景中特别有用，您需要在多个服务和异步操作之间传播追踪 ID。此示例演示了如何使用 ALS 生成和传播追踪 ID。

const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const asyncLocalStorage = new AsyncLocalStorage();

function generateTraceId() {
  return uuidv4();
}

function withTrace(callback) {
  const traceId = generateTraceId();
  asyncLocalStorage.run({ traceId }, callback);
}

function getTraceId() {
  const store = asyncLocalStorage.getStore();
  return store ? store.traceId : null;
}

// 用法示例
withTrace(() => {
  const traceId = getTraceId();
  console.log(`Trace ID: ${traceId}`);

  // 模拟异步操作
  setTimeout(() => {
    const nestedTraceId = getTraceId();
    console.log(`Nested Trace ID: ${nestedTraceId}`); // 应该是同一个追踪 ID
  }, 50);
});

真实世界的用例

异步本地存储是一个多功能工具，可应用于各种场景：

• 日志记录：使用请求 ID、用户 ID 或追踪 ID 等特定于请求的信息来丰富日志消息。
• 身份验证和授权：存储用户身份验证上下文，并在整个请求生命周期中访问它。
• 数据库事务：将数据库事务与特定请求关联，确保数据一致性和隔离性。
• 错误处理：捕获特定于请求的错误上下文，并将其用于详细的错误报告和调试。
• A/B 测试：存储实验分配，并在整个用户会话中一致地应用它们。

注意事项和最佳实践

虽然异步本地存储带来了显著的好处，但审慎使用并遵守最佳实践至关重要：

• 性能开销：由于异步上下文的创建和管理，ALS 会引入少量性能开销。衡量其对您应用程序的影响并进行相应优化。
• 上下文污染：避免在 ALS 中存储过多的数据，以防止内存泄漏和性能下降。
• 显式上下文管理：在某些情况下，显式传递上下文对象可能更合适，特别是对于复杂或深度嵌套的操作。
• 框架集成：利用现有的框架集成和库，这些库为日志记录和追踪等常见任务提供了 ALS 支持。
• 错误处理：实施适当的错误处理，以防止上下文泄漏，并确保 ALS 上下文得到正确清理。

异步本地存储的替代方案

虽然 ALS 是一个强大的工具，但它并非总是适用于所有情况。以下是一些可以考虑的替代方案：

• 显式上下文传递：将上下文对象作为参数传递的传统方法。这种方式可能更明确、更容易理解，但也可能导致代码冗长。
• 依赖注入：使用依赖注入框架来管理上下文和依赖项。这可以提高代码的模块化和可测试性。
• 上下文变量 (TC39 提案)：一项提议中的 ECMAScript 功能，它提供了一种更标准化的方式来管理上下文。目前仍在开发中，尚未得到广泛支持。
• 自定义上下文管理解决方案：根据您的特定应用程序需求，开发自定义的上下文管理解决方案。

AsyncLocalStorage.enterWith() 方法

`enterWith()` 方法是设置 ALS 上下文的一种更直接的方式，它绕过了 `run()` 提供的自动传播。但是，应谨慎使用。通常建议使用 `run()` 来管理上下文，因为它会自动处理跨异步操作的上下文传播。如果使用不当，`enterWith()` 可能会导致意外行为。

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

const asyncLocalStorage = new AsyncLocalStorage();

const store = { data: 'Some Data' };

// 使用 enterWith 设置 store
asyncLocalStorage.enterWith(store);

// 访问 store (在 enterWith 后应立即生效)
console.log(asyncLocalStorage.getStore());

// 执行一个不会自动继承上下文的异步函数
setTimeout(() => {
  // 上下文在这里仍然是活动的，因为我们是用 enterWith 手动设置的。
  console.log(asyncLocalStorage.getStore());
}, 1000);

// 要正确清除上下文，您需要一个 try...finally 块
// 这说明了为什么通常首选 run()，因为它会自动处理清理工作。

常见陷阱及如何避免

• 忘记使用 `run()`：如果您初始化了 AsyncLocalStorage，但忘记将您的请求处理逻辑包装在 `asyncLocalStorage.run()` 中，上下文将不会被正确传播，导致调用 `getStore()` 时返回 `undefined`。
• Promises 的上下文传播不正确：使用 Promises 时，请确保在 `run()` 回调中等待 (await) 异步操作。如果您不等待，上下文可能无法正确传播。
• 内存泄漏：避免在 AsyncLocalStorage 上下文中存储大对象，因为如果上下文没有被正确清理，可能会导致内存泄漏。
• 过度依赖 AsyncLocalStorage：不要将 AsyncLocalStorage 用作全局状态管理解决方案。它最适合用于请求范围的上下文管理。

JavaScript 上下文管理的未来

JavaScript 生态系统在不断发展，新的上下文管理方法也在不断涌现。提议中的上下文变量功能 (TC39 提案) 旨在为管理上下文提供一个更标准化、更语言化的解决方案。随着这些功能的成熟和广泛采用，它们可能会为处理 JavaScript 应用程序中的上下文提供更优雅、更高效的方式。

结论

JavaScript 异步本地存储为在异步环境中管理请求范围的上下文提供了一个强大而优雅的解决方案。通过简化上下文管理、提高代码可维护性和增强调试能力，ALS 可以显著改善 Node.js 应用程序的开发体验。然而，在您的项目中采用 ALS 之前，了解其核心概念、遵守最佳实践并考虑潜在的性能开销是至关重要的。随着 JavaScript 生态系统的不断发展，可能会出现新的、更完善的上下文管理方法，为处理复杂的异步场景提供更复杂的解决方案。