NestJS中AsyncLocalStorage无法为每个请求正常工作的问题排查

核心问题原因 #

1. AsyncLocalStorage(ALS)初始化时机错误：如果在NestJS模块初始化前就创建ALS实例，会和NestJS的依赖注入生命周期冲突，导致上下文绑定失效。
2. 请求链路未被完整包裹：中间件/拦截器中没有用ALS.run()包裹整个请求处理流程，异步操作（如数据库查询、服务调用）跑出上下文范围，导致后续请求丢失用户信息。
3. 上下文绑定逻辑缺失：未在请求入口（全局中间件/拦截器）将用户信息注入ALS上下文，或注入逻辑仅覆盖部分请求流程。

正确实现方案 #

1. 封装UserStorage服务（内部管理ALS） #

确保ALS在NestJS模块生命周期内初始化，避免提前创建导致的冲突：

import { Injectable, OnModuleInit } from '@nestjs/common';
import { AsyncLocalStorage } from 'async_hooks';

@Injectable()
export class UserStorage implements OnModuleInit {
  private als: AsyncLocalStorage<{ user: any }>;

  // 在模块初始化完成后创建ALS实例
  onModuleInit() {
    this.als = new AsyncLocalStorage();
  }

  // 用用户信息包裹请求处理流程
  runWithUser(user: any, callback: () => void) {
    return this.als.run({ user }, callback);
  }

  // 获取当前上下文的用户
  getCurrentUser() {
    const store = this.als.getStore();
    return store?.user;
  }
}

2. 全局中间件绑定请求上下文 #

用中间件在请求最早期包裹整个链路，确保所有异步操作都在ALS上下文内：

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { UserStorage } from './user-storage.service';

@Injectable()
export class UserContextMiddleware implements NestMiddleware {
  constructor(private readonly userStorage: UserStorage) {}

  use(req: Request, res: Response, next: NextFunction) {
    // 假设已通过AuthGuard将用户信息挂载到req.user
    const user = req.user;
    // 用ALS包裹后续所有请求处理逻辑
    this.userStorage.runWithUser(user, next);
  }
}

3. 注册中间件与服务 #

在AppModule中注册全局中间件和UserStorage：

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { UserStorage } from './user-storage.service';
import { UserContextMiddleware } from './user-context.middleware';

@Module({
  providers: [UserStorage],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    // 对所有路由应用上下文中间件
    consumer.apply(UserContextMiddleware).forRoutes('*');
  }
}

4. 业务服务中使用用户上下文 #

保持业务服务为单例，直接通过UserStorage获取当前用户：

import { Injectable } from '@nestjs/common';
import { UserStorage } from './user-storage.service';

@Injectable()
export class ResourceService {
  constructor(private readonly userStorage: UserStorage) {}

  hasUserAccessToResource(resourceId: string): boolean {
    const currentUser = this.userStorage.getCurrentUser();
    if (!currentUser) {
      throw new Error('用户上下文未找到');
    }
    // 自定义业务权限判断逻辑
    return currentUser.allowedResources.includes(resourceId);
  }
}

关键注意事项 #

• 禁止在模块外提前创建ALS实例：必须通过OnModuleInit钩子在NestJS模块初始化后创建，避免生命周期冲突。
• 确保完整包裹请求链路：中间件是最适合的入口点，能覆盖所有请求阶段，包括后续的异步操作。
• 避免请求作用域服务：此方案保持所有服务为单例，既解决了用户上下文传递问题，又避免了请求作用域导致的重复实例化性能损耗。

内容的提问来源于stack exchange，提问作者SeekanDestroy