5 种方式设置 CLS 上下文nestjs-cls 中间件、Guard、拦截器与 UseCls 装饰器终极对比【免费下载链接】nestjs-clsA continuation-local storage (async context) module compatible with NestJSs dependency injection.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-clsnestjs-cls 是一个与 NestJS 依赖注入无缝兼容的 continuation-local storage异步上下文模块。本文带你用一张对比表 5 分钟彻底搞懂它的 5 种 CLS 上下文设置方式——中间件、Guard、拦截器、UseCls 装饰器与手动 ClsService.run()帮你选对方案、少走弯路。为什么需要设置 CLS 上下文CLScontinuation-local storage让你在一次请求的生命周期内跨回调、跨 Promise、跨服务共享数据——请求 ID、当前用户、多租户数据库连接、事务统统不用层层传参。它类似其他语言的线程本地存储thread-local storage但专为 JavaScript 的异步模型设计。核心原理一句话先在某处调用一次上下文初始化cls.run()或cls.enter()之后同一条调用链上的所有代码都能通过cls.set()/cls.get()读写同一份存储。详细说明见 docs/docs/01_introduction/03_how-it-works.md而 nestjs-cls 官方提供了5 种初始化上下文的方式各自适用于不同传输层REST / GraphQL / WebSocket / 微服务和非 Web 场景。5 种 CLS 上下文设置方式一张表看懂差异方式适用传输层底层机制安全性上下文可用范围1. ClsMiddleware 中间件REST ✔ / GQL ✔ / WS ✖ / 微服务 ✖run⭐⭐⭐全链路Guard、拦截器、控制器、服务、过滤器2. ClsGuardREST ✔ / GQL ✔ / WS ✔ / 微服务 ✔enterWith⭐⭐全链路3. ClsInterceptor 拦截器REST ✔ / GQL ✔ / WS ✔ / 微服务 ✔run⭐⭐⭐拦截器之后Guard 中不可用REST 下异常过滤器也不可用4. UseCls 装饰器非 Web 请求队列、定时任务等run⭐⭐⭐装饰的方法及其调用链5. ClsService.run() 手动调用任意场景run⭐⭐⭐你包裹的代码块 关键点中间件是 HTTP 请求最先经过的环节所以REST/GraphQL 首选中间件Guard 和拦截器是全能选手支持所有传输层后两种则面向 Web 请求之外的场景。方式一ClsMiddleware 中间件——REST 与 GraphQL 的最优解NestJS 中 HTTP 中间件是请求到达后最先执行的代码因此初始化 CLS 上下文的理想位置。官方提供ClsMiddleware可在挂载路由的next()调用前完成上下文建立。自动挂载最省事在ClsModule.forRoot()中传middleware: { mount: true }中间件会自动挂到所有路由。手动挂载要精细控制时在模块的configure(consumer)里用consumer.apply(ClsMiddleware).forRoutes(自定义路由)只挂到指定路由若与其他中间件有顺序冲突例如 API 版本化可直接在main.ts中app.use(new ClsMiddleware({...}).use)手动挂载。⚠️ 注意通过app.use()挂载时不会继承forRoot()里的中间件配置需要在构造函数中自行提供。实现源码packages/core/src/lib/cls-initializers/cls.middleware.ts方式二ClsGuard——全传输层的第二选择ClsGuard严格说不是守卫但它初始化上下文后是请求命中的第二早的代码仅次于中间件。它通过AsyncLocalStorage#enterWith工作因此WebSocket 网关、微服务等中间件无法触及的场景都能用。自动挂载guard: { mount: true }手动挂载在根模块通过APP_GUARD提供ClsGuard作为全局守卫或直接UseGuards(ClsGuard)挂到控制器/Resolver 上。⚠️ 安全提示因为使用enterWith方法ClsGuard存在一些 安全性考虑例如上下文可能在await挂起期间被其他请求污染生产环境建议评估后使用。实现源码packages/core/src/lib/cls-initializers/cls.guard.ts方式三ClsInterceptor 拦截器——用 run 机制的更稳替代ClsInterceptor与 Guard 的差别在于它使用AsyncLocalStorage#run包裹后续代码而不是enterWith——run 是官方公认更安全的模式上下文生命周期被严格限制在包裹范围内。自动挂载interceptor: { mount: true }手动挂载通过APP_INTERCEPTOR提供ClsInterceptor或UseInterceptors(ClsInterceptor)挂到具体控制器/ResolverWebSocket 网关必须手动挂。⚠️ 代价NestJS 的拦截器运行在守卫之后所以这种方式下Guard 中拿不到 CLS 上下文REST 控制器中异常过滤器也不行。实现源码packages/core/src/lib/cls-initializers/cls.interceptor.ts方式四UseCls 装饰器——Web 请求之外的场景当你的代码运行在Web 请求上下文之外队列消费者、定时任务、后台工作流没有req对象可用UseCls()就是为你准备的它声明式地把一个 async 方法包裹进cls.run()。UseCls[string]({ generateId: true, setup: function (this: SomeService, cls: ClsService, value: string) { cls.set(some-key, some-value); }, }) async startContextualWorkflow(value: string) { return this.otherService.doSomething(value); }使用要点 只能用于async 方法返回 Promise因为上下文初始化可以是异步的 没有请求对象setup收到的是this实例、ClsService引用和方法参数setup与idGenerator必须写成function而非箭头函数否则this绑定失效实现源码packages/core/src/lib/cls-initializers/use-cls.decorator.ts方式五ClsService.run()——终极手动控制前 4 种方式最终都是对ClsService#run或#enter的封装。当你需要最细粒度的控制——只包裹某一段代码、或者前面所有方式都不适用时直接注入ClsService实例await this.cls.run({ id: crypto.randomUUID() }, async () { this.cls.set(user, user); // 这段调用链内所有代码都能读到 user return this.orderService.create(); });这是万能兜底方案也是理解前面 4 种方式如何工作的钥匙。ClsService核心接口packages/core/src/cls.service.ts如何选择30 秒决策清单REST / GraphQLNest ≥ 10 的 GQL→ 用ClsMiddlewaremount: true最标准 ✅WebSocket、微服务或其他传输层→ 用ClsGuard方便或ClsInterceptor更安全Guard 里必须用 CLS 吗→ 是中间件或ClsGuard否优先ClsInterceptor队列 / 定时任务 / 脚本等非请求场景→UseCls()装饰器只想包裹一段逻辑 / 以上都不合适→cls.run()手动包裹⚠️ GraphQL 额外提醒一个 GQL 请求可能包含多个查询拦截器/Guard 可能多次触发请确保setup里的操作是幂等的推荐setIfUndefined()。参考官方文档设置上下文章节docs/docs/02_setting-up-cls-context/index.md各方式详解中间件 · Guard · 拦截器 · 装饰器 · 手动实例兼容性矩阵docs/docs/05_considerations/02_compatibility.md核心实现packages/core/src/lib/cls-initializers/、packages/core/src/cls.service.ts【免费下载链接】nestjs-clsA continuation-local storage (async context) module compatible with NestJSs dependency injection.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-cls创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考