@keq-request/nestjs 5.0.0-beta.11 → 5.0.0-beta.13

package/.turbo/turbo-build.log

@@ -1,10 +1,10 @@
 
-> @keq-request/nestjs@5.0.0-beta.11 build /home/runner/work/keq/keq/packages/nestjs
+> @keq-request/nestjs@5.0.0-beta.13 build /home/runner/work/keq/keq/packages/nestjs
 > tsdown
 
 ℹ tsdown v0.21.10 powered by rolldown v1.0.0-rc.17
 ℹ config file: /home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts 
-(node:2746) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts?no-cache=0efd33bf-1c41-465a-8588-1641d5aab98c is not specified and it doesn't parse as CommonJS.
+(node:2744) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/keq/keq/packages/nestjs/tsdown.config.ts?no-cache=63d674a9-ded8-4584-ad0b-ff9b06a87e93 is not specified and it doesn't parse as CommonJS.
 Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
 To eliminate this warning, add "type": "module" to /home/runner/work/keq/keq/packages/nestjs/package.json.
 (Use `node --trace-warnings ...` to show where the warning was created)
@@ -12,25 +12,25 @@ To eliminate this warning, add "type": "module" to /home/runner/work/keq/keq/pac
 ℹ target: node20
 ℹ tsconfig: tsconfig.lib.json
 ℹ Build start
-ℹ [CJS] dist/index.js      5.83 kB │ gzip: 2.01 kB
-ℹ [CJS] dist/index.js.map  7.28 kB │ gzip: 2.38 kB
-ℹ [CJS] 2 files, total: 13.11 kB
+ℹ [CJS] dist/index.js      10.52 kB │ gzip: 3.95 kB
+ℹ [CJS] dist/index.js.map  15.05 kB │ gzip: 5.17 kB
+ℹ [CJS] 2 files, total: 25.57 kB
 [PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `tsdown:deps`. See https://rolldown.rs/options/checks#plugintimings for more details.
 
-ℹ [CJS] dist/index.d.ts.map  0.99 kB │ gzip: 0.43 kB
-ℹ [CJS] dist/index.d.ts      1.86 kB │ gzip: 0.65 kB
-ℹ [CJS] 2 files, total: 2.85 kB
+ℹ [ESM] dist/index.mjs         9.19 kB │ gzip: 3.46 kB
+ℹ [ESM] dist/index.mjs.map    14.98 kB │ gzip: 5.14 kB
+ℹ [ESM] dist/index.d.mts.map   1.08 kB │ gzip: 0.47 kB
+ℹ [ESM] dist/index.d.mts       2.96 kB │ gzip: 1.38 kB
+ℹ [ESM] 4 files, total: 28.22 kB
+[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `rolldown-plugin-dts:generate`. See https://rolldown.rs/options/checks#plugintimings for more details.
+
+✔ Build complete in 5612ms
+ℹ [CJS] dist/index.d.ts.map  1.08 kB │ gzip: 0.47 kB
+ℹ [CJS] dist/index.d.ts      2.96 kB │ gzip: 1.37 kB
+ℹ [CJS] 2 files, total: 4.04 kB
 [PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
   - rolldown-plugin-dts:generate (48%)
-  - tsdown:deps (46%)
+  - tsdown:deps (43%)
 See https://rolldown.rs/options/checks#plugintimings for more details.
 
-✔ Build complete in 5198ms
-[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugin `rolldown-plugin-dts:generate`. See https://rolldown.rs/options/checks#plugintimings for more details.
-ℹ [ESM] dist/index.mjs        4.54 kB │ gzip: 1.57 kB
-
-ℹ [ESM] dist/index.mjs.map    7.21 kB │ gzip: 2.36 kB
-ℹ [ESM] dist/index.d.mts.map  0.99 kB │ gzip: 0.43 kB
-ℹ [ESM] dist/index.d.mts      1.86 kB │ gzip: 0.66 kB
-ℹ [ESM] 4 files, total: 14.60 kB
-✔ Build complete in 5201ms
+✔ Build complete in 5614ms

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @keq-request/nestjs
 
+## 5.0.0-beta.13
+
+### Patch Changes
+
+- 59f4773: **Fix:** ensure `configureKeqMiddleware()` works correctly in pnpm monorepos and validate module imports at startup.
+
+  - Fix middleware not being applied when pnpm creates multiple `@keq-request/nestjs` instances due to peerDependency version differences.
+  - Detect missing `KeqModule` imports in modules that implement `configureKeqMiddleware()` at startup, throwing a clear error instead of silently skipping middleware.
+  - Prevent middleware from being applied more than once when multiple `KeqModule` instances exist.
+  - Throw a descriptive error when a NestJS middleware class passed to `consumer.apply()` is not registered as a provider.
+  - keq@5.0.0-beta.13
+
+## 5.0.0-beta.12
+
+### Minor Changes
+
+- fbc851f: **Feat:** Add `exclude()` method to `KeqMiddlewareConfigProxy`, allowing middleware to skip specific routes. Supports `KeqRouteInfo` with `host`, `method`, and `pathname` patterns, following the NestJS `MiddlewareConfigProxy.exclude()` convention.
+
+### Patch Changes
+
+- keq@5.0.0-beta.12
+
 ## 5.0.0-beta.11
 
 ### Patch Changes

package/__tests__/keq-module.spec.ts

@@ -0,0 +1,155 @@
+import 'reflect-metadata'
+import { expect, test } from '@jest/globals'
+import { Module } from '@nestjs/common'
+import type { ModulesContainer } from '@nestjs/core'
+import { KeqModule, validateConfigureKeqMiddlewareImports } from '../src/keq.module.js'
+
+/**
+ * 模拟 NestJS Module wrapper 的运行时结构。
+ * NestJS 在扫描阶段会将 DynamicModule 的 imports 解析为 Set<Module>，
+ * 因此使用 imports Set 而非静态 Reflect.getMetadata 来校验。
+ */
+function createMockModule(metatype: unknown, importsModules: Array<{ metatype: unknown }> = []) {
+  return {
+    metatype,
+    imports: new Set(importsModules),
+  }
+}
+
+function mockModulesContainer(
+  modules: Array<ReturnType<typeof createMockModule>>,
+): ModulesContainer {
+  const map = new Map()
+  for (const mod of modules) {
+    map.set(Symbol('module'), mod)
+  }
+  return map as unknown as ModulesContainer
+}
+
+
+test('throws when configureKeqMiddleware is declared without KeqModule in imports', () => {
+  @Module({ imports: [] })
+  class BadModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  const container = mockModulesContainer([
+    createMockModule(KeqModule),
+    createMockModule(BadModule),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
+    /\[KeqModule\] 'BadModule' implements configureKeqMiddleware\(\)/,
+  )
+})
+
+test('passes when configureKeqMiddleware is declared with KeqModule in imports', () => {
+  @Module({ imports: [KeqModule] })
+  class GoodModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  const keqModuleWrapper = createMockModule(KeqModule)
+
+  const container = mockModulesContainer([
+    keqModuleWrapper,
+    createMockModule(GoodModule, [keqModuleWrapper]),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+})
+
+test('passes when module does not implement configureKeqMiddleware', () => {
+  @Module({ imports: [] })
+  class PlainModule {}
+
+  const container = mockModulesContainer([
+    createMockModule(PlainModule),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+})
+
+test('passes when KeqModule is imported as DynamicModule', () => {
+  @Module({ imports: [{ module: KeqModule }] })
+  class DynamicImportModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  // NestJS 在扫描阶段解析 DynamicModule，将 KeqModule wrapper 加入 imports Set
+  const keqModuleWrapper = createMockModule(KeqModule)
+
+  const container = mockModulesContainer([
+    keqModuleWrapper,
+    createMockModule(DynamicImportModule, [keqModuleWrapper]),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+})
+
+test('passes when KeqModule is imported via forwardRef', () => {
+  const { forwardRef } = require('@nestjs/common')
+  @Module({ imports: [forwardRef(() => KeqModule)] })
+  class ForwardRefModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  // NestJS 在扫描阶段解析 forwardRef，将 KeqModule wrapper 加入 imports Set
+  const keqModuleWrapper = createMockModule(KeqModule)
+
+  const container = mockModulesContainer([
+    keqModuleWrapper,
+    createMockModule(ForwardRefModule, [keqModuleWrapper]),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+})
+
+test('passes when metatype is null', () => {
+  const container = mockModulesContainer([
+    createMockModule(null as unknown as undefined),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).not.toThrow()
+})
+
+test('throws when module has configureKeqMiddleware but KeqModule is not in container', () => {
+  // KeqModule 未在 ModulesContainer 中注册时，任何实现了 configureKeqMiddleware
+  // 的模块都无法通过校验，因为缺少 KeqModule 来注册中间件
+  @Module({ imports: [] })
+  class SomeModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  const container = mockModulesContainer([
+    createMockModule(SomeModule),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
+    /\[KeqModule\] 'SomeModule'/,
+  )
+})
+
+test('throws for one module while another is valid', () => {
+  @Module({ imports: [] })
+  class BadModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  @Module({ imports: [KeqModule] })
+  class GoodModule {
+    configureKeqMiddleware(): void {}
+  }
+
+  const keqModuleWrapper = createMockModule(KeqModule)
+
+  const container = mockModulesContainer([
+    keqModuleWrapper,
+    createMockModule(GoodModule, [keqModuleWrapper]),
+    createMockModule(BadModule),
+  ])
+
+  expect(() => validateConfigureKeqMiddlewareImports(container)).toThrow(
+    /'BadModule'/,
+  )
+})

package/dist/index.d.mts

@@ -1,13 +1,29 @@
 import { OnModuleInit, Type } from "@nestjs/common";
-import { ModuleRef, ModulesContainer } from "@nestjs/core";
+import { ModulesContainer } from "@nestjs/core";
 import { KeqExecutionContext, KeqMiddleware, KeqNext, KeqRequest } from "keq";
 
 //#region src/keq.module.d.ts
+/**
+ * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
+ * 是否显式导入了 `KeqModule`。
+ *
+ * NestJS 初始化分为两个严格串行的阶段：
+ * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
+ *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
+ * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
+ *
+ * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
+ * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
+ *
+ * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
+ * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
+ * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
+ */
+declare function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void;
 declare class KeqModule implements OnModuleInit {
   private readonly modulesContainer;
-  private readonly moduleRef;
   private readonly keqRequest;
-  constructor(modulesContainer: ModulesContainer, moduleRef: ModuleRef, keqRequest: KeqRequest);
+  constructor(modulesContainer: ModulesContainer, keqRequest: KeqRequest);
   onModuleInit(): void;
 }
 //#endregion
@@ -27,10 +43,11 @@ interface KeqRouteInfo {
   method?: string;
   pathname?: string;
 }
-interface KeqModuleClass {
+interface KeqModuleClass extends Type<any> {
   readonly KEQ_REQUEST: symbol;
 }
 interface KeqMiddlewareConfigProxy {
+  exclude(...routes: KeqRouteInfo[]): KeqMiddlewareConfigProxy;
   forRoutes(...routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>): KeqMiddlewareConsumer;
 }
 interface KeqMiddlewareConsumer {
@@ -48,5 +65,5 @@ interface KeqModuleOptions {
   isolate?: boolean;
 }
 //#endregion
-export { KEQ_ROUTES, type KeqMiddlewareConfigProxy, type KeqMiddlewareConsumer, type KeqMiddlewareModule, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo };
+export { KEQ_ROUTES, type KeqMiddlewareConfigProxy, type KeqMiddlewareConsumer, type KeqMiddlewareModule, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo, validateConfigureKeqMiddlewareImports };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/interfaces/keq-middleware-module.interface.ts","../src/interfaces/keq-module-options.interface.ts"],"mappings":";;;;;cAYa,SAAA,YAAqB,YAAA;EAAA,iBAEb,gBAAA;EAAA,iBACA,SAAA;EAAA,iBACA,UAAA;cAFA,gBAAA,EAAkB,gBAAA,EAClB,SAAA,EAAW,SAAA,EACX,UAAA,EAAY,UAAA;EAG/B,YAAA,CAAA;AAAA;;;cCnBW,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;UCEtC,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA;EAAA,SACN,WAAA;AAAA;AAAA,UAGM,wBAAA;EACf,SAAA,IAAa,MAAA,EAAQ,KAAA,QAAa,UAAA,CAAW,GAAA,GAAM,YAAA,GAAe,cAAA,IAAkB,qBAAA;AAAA;AAAA,UAGrE,qBAAA;EACf,KAAA,IAAS,WAAA,EAAa,KAAA,CAAM,IAAA,CAAK,iBAAA,IAAqB,aAAA,IAAiB,wBAAA;AAAA;;;UClBxD,mBAAA;EACf,sBAAA,CAAuB,QAAA,EAAU,qBAAA;AAAA;;;UCDlB,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/interfaces/keq-middleware-module.interface.ts","../src/interfaces/keq-module-options.interface.ts"],"mappings":";;;;;;;AAoCA;;;;;AAkCA;;;;;;;;;iBAlCgB,qCAAA,CAAsC,gBAAA,EAAkB,gBAAA;AAAA,cAuC3D,SAAA,YAAqB,YAAA;EAAA,iBAEb,gBAAA;EAAA,iBACA,UAAA;cADA,gBAAA,EAAkB,gBAAA,EAClB,UAAA,EAAY,UAAA;EAK/B,YAAA,CAAA;AAAA;;;cCnFW,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;UCEtC,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA,SAAuB,IAAA;EAAA,SAC7B,WAAA;AAAA;AAAA,UAGM,wBAAA;EACf,OAAA,IAAW,MAAA,EAAQ,YAAA,KAAiB,wBAAA;EACpC,SAAA,IAAa,MAAA,EAAQ,KAAA,QAAa,UAAA,CAAW,GAAA,GAAM,YAAA,GAAe,cAAA,IAAkB,qBAAA;AAAA;AAAA,UAGrE,qBAAA;EACf,KAAA,IAAS,WAAA,EAAa,KAAA,CAAM,IAAA,CAAK,iBAAA,IAAqB,aAAA,IAAiB,wBAAA;AAAA;;;UCnBxD,mBAAA;EACf,sBAAA,CAAuB,QAAA,EAAU,qBAAA;AAAA;;;UCDlB,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA"}

package/dist/index.d.ts

@@ -1,13 +1,29 @@
 import { OnModuleInit, Type } from "@nestjs/common";
-import { ModuleRef, ModulesContainer } from "@nestjs/core";
+import { ModulesContainer } from "@nestjs/core";
 import { KeqExecutionContext, KeqMiddleware, KeqNext, KeqRequest } from "keq";
 
 //#region src/keq.module.d.ts
+/**
+ * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
+ * 是否显式导入了 `KeqModule`。
+ *
+ * NestJS 初始化分为两个严格串行的阶段：
+ * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
+ *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
+ * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
+ *
+ * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
+ * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
+ *
+ * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
+ * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
+ * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
+ */
+declare function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void;
 declare class KeqModule implements OnModuleInit {
   private readonly modulesContainer;
-  private readonly moduleRef;
   private readonly keqRequest;
-  constructor(modulesContainer: ModulesContainer, moduleRef: ModuleRef, keqRequest: KeqRequest);
+  constructor(modulesContainer: ModulesContainer, keqRequest: KeqRequest);
   onModuleInit(): void;
 }
 //#endregion
@@ -27,10 +43,11 @@ interface KeqRouteInfo {
   method?: string;
   pathname?: string;
 }
-interface KeqModuleClass {
+interface KeqModuleClass extends Type<any> {
   readonly KEQ_REQUEST: symbol;
 }
 interface KeqMiddlewareConfigProxy {
+  exclude(...routes: KeqRouteInfo[]): KeqMiddlewareConfigProxy;
   forRoutes(...routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>): KeqMiddlewareConsumer;
 }
 interface KeqMiddlewareConsumer {
@@ -48,5 +65,5 @@ interface KeqModuleOptions {
   isolate?: boolean;
 }
 //#endregion
-export { KEQ_ROUTES, type KeqMiddlewareConfigProxy, type KeqMiddlewareConsumer, type KeqMiddlewareModule, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo };
+export { KEQ_ROUTES, type KeqMiddlewareConfigProxy, type KeqMiddlewareConsumer, type KeqMiddlewareModule, KeqModule, type KeqModuleClass, type KeqModuleOptions, type KeqNestMiddleware, type KeqRouteInfo, validateConfigureKeqMiddlewareImports };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/interfaces/keq-middleware-module.interface.ts","../src/interfaces/keq-module-options.interface.ts"],"mappings":";;;;;cAYa,SAAA,YAAqB,YAAA;EAAA,iBAEb,gBAAA;EAAA,iBACA,SAAA;EAAA,iBACA,UAAA;cAFA,gBAAA,EAAkB,gBAAA,EAClB,SAAA,EAAW,SAAA,EACX,UAAA,EAAY,UAAA;EAG/B,YAAA,CAAA;AAAA;;;cCnBW,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;UCEtC,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA;EAAA,SACN,WAAA;AAAA;AAAA,UAGM,wBAAA;EACf,SAAA,IAAa,MAAA,EAAQ,KAAA,QAAa,UAAA,CAAW,GAAA,GAAM,YAAA,GAAe,cAAA,IAAkB,qBAAA;AAAA;AAAA,UAGrE,qBAAA;EACf,KAAA,IAAS,WAAA,EAAa,KAAA,CAAM,IAAA,CAAK,iBAAA,IAAqB,aAAA,IAAiB,wBAAA;AAAA;;;UClBxD,mBAAA;EACf,sBAAA,CAAuB,QAAA,EAAU,qBAAA;AAAA;;;UCDlB,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/keq.module.ts","../src/constants.ts","../src/interfaces/keq-nest-middleware.interface.ts","../src/interfaces/keq-middleware-consumer.interface.ts","../src/interfaces/keq-middleware-module.interface.ts","../src/interfaces/keq-module-options.interface.ts"],"mappings":";;;;;;;AAoCA;;;;;AAkCA;;;;;;;;;iBAlCgB,qCAAA,CAAsC,gBAAA,EAAkB,gBAAA;AAAA,cAuC3D,SAAA,YAAqB,YAAA;EAAA,iBAEb,gBAAA;EAAA,iBACA,UAAA;cADA,gBAAA,EAAkB,gBAAA,EAClB,UAAA,EAAY,UAAA;EAK/B,YAAA,CAAA;AAAA;;;cCnFW,UAAA;EAAA,SAEH,GAAA;AAAA;;;UCCO,iBAAA;EACf,GAAA,CAAI,GAAA,EAAK,mBAAA,EAAqB,IAAA,EAAM,OAAA,UAAiB,WAAA;AAAA;;;UCEtC,YAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,UAGe,cAAA,SAAuB,IAAA;EAAA,SAC7B,WAAA;AAAA;AAAA,UAGM,wBAAA;EACf,OAAA,IAAW,MAAA,EAAQ,YAAA,KAAiB,wBAAA;EACpC,SAAA,IAAa,MAAA,EAAQ,KAAA,QAAa,UAAA,CAAW,GAAA,GAAM,YAAA,GAAe,cAAA,IAAkB,qBAAA;AAAA;AAAA,UAGrE,qBAAA;EACf,KAAA,IAAS,WAAA,EAAa,KAAA,CAAM,IAAA,CAAK,iBAAA,IAAqB,aAAA,IAAiB,wBAAA;AAAA;;;UCnBxD,mBAAA;EACf,sBAAA,CAAuB,QAAA,EAAU,qBAAA;AAAA;;;UCDlB,gBAAA;EACf,WAAA,GAAc,aAAA;EACd,OAAA;AAAA"}

package/dist/index.js

@@ -37,20 +37,33 @@ var KeqMiddlewareConsumerImpl = class {
 			middlewares,
 			routes: []
 		};
+		const excludedRouteInfos = [];
 		this.entries.push(entry);
-		return { forRoutes: (...routes) => {
-			entry.routes = routes;
-			return this;
-		} };
+		const proxy = {
+			exclude: (...routes) => {
+				excludedRouteInfos.push(...routes);
+				return proxy;
+			},
+			forRoutes: (...routes) => {
+				entry.routes = routes;
+				if (excludedRouteInfos.length > 0) entry.excludedRouteInfos = excludedRouteInfos;
+				return this;
+			}
+		};
+		return proxy;
 	}
-	applyTo(keqRequest, moduleRef) {
+	applyTo(keqRequest, modulesContainer) {
 		for (const entry of this.entries) {
-			const resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef));
+			let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, modulesContainer));
+			if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {
+				const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info));
+				resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes));
+			}
 			if (entry.routes.length === 0 || entry.routes.some((r) => r === KEQ_ROUTES.ALL)) for (const mw of resolved) keqRequest.use(mw);
 			else for (const routeTarget of entry.routes) {
 				if (routeTarget === KEQ_ROUTES.ALL) continue;
 				if (this.isKeqModuleClass(routeTarget)) {
-					const targetRequest = moduleRef.get(routeTarget.KEQ_REQUEST, { strict: false });
+					const targetRequest = this.findInModulesContainer(routeTarget, modulesContainer);
 					if (targetRequest) for (const mw of resolved) targetRequest.use(mw);
 				} else {
 					const route = this.buildRoute(routeTarget);
@@ -65,15 +78,41 @@ var KeqMiddlewareConsumerImpl = class {
 	isNestMiddlewareClass(m) {
 		return typeof m === "function" && m.prototype !== void 0 && "use" in m.prototype;
 	}
-	resolveMiddleware(m, moduleRef) {
+	findMiddlewareInstance(middlewareClass, modulesContainer) {
+		for (const [, moduleWrapper] of modulesContainer) {
+			const provider = moduleWrapper.providers.get(middlewareClass);
+			if (provider?.instance) return provider.instance;
+		}
+	}
+	resolveMiddleware(m, modulesContainer) {
 		if (this.isNestMiddlewareClass(m)) {
-			const instance = moduleRef.get(m, { strict: false });
+			const instance = this.findMiddlewareInstance(m, modulesContainer);
+			if (!instance) throw new Error(`[KeqModule] Nest middleware class '${m.name}' is not registered as a provider in any module. Ensure the middleware class is added to the providers array of a @Module() decorator.`);
 			return async (ctx, next) => {
 				await instance.use(ctx, next);
 			};
 		}
 		return m;
 	}
+	/**
+	* 从 ModulesContainer 中查找目标 KeqModule 的 KeqRequest 实例
+	*
+	* 通过 metatype 精确匹配模块，从模块 providers 中直接获取 KeqRequest。
+	* 不依赖 ModuleRef 的作用域机制，直接从 NestJS 全局模块容器中查找。
+	*
+	* @param routeTarget - 目标 KeqModule 类，必须具有 KEQ_REQUEST symbol 属性
+	* @param modulesContainer - NestJS 全局模块容器
+	* @returns KeqRequest 实例，未找到时返回 undefined
+	*/
+	findInModulesContainer(routeTarget, modulesContainer) {
+		const token = routeTarget.KEQ_REQUEST;
+		for (const [, moduleWrapper] of modulesContainer) {
+			if (moduleWrapper.metatype !== routeTarget) continue;
+			const provider = moduleWrapper.providers.get(token);
+			if (!provider) continue;
+			if (provider.instance) return provider.instance;
+		}
+	}
 	buildRoute(info) {
 		const routes = [];
 		if (info.host) {
@@ -91,6 +130,17 @@ var KeqMiddlewareConsumerImpl = class {
 		if (routes.length === 1) return routes[0];
 		return (0, keq.composeRoute)(routes);
 	}
+	wrapWithExclusion(middleware, excludedRoutes) {
+		const excluded = async (ctx, next) => {
+			if (await this.checkExcluded(ctx, excludedRoutes)) return next();
+			return middleware(ctx, next);
+		};
+		return excluded;
+	}
+	async checkExcluded(ctx, excludedRoutes) {
+		for (const route of excludedRoutes) if (await route(ctx)) return true;
+		return false;
+	}
 };
 //#endregion
 //#region src/utils/has-configure-keq-middleware.ts
@@ -112,21 +162,63 @@ function __decorate(decorators, target, key, desc) {
 }
 //#endregion
 //#region src/keq.module.ts
-var _ref, _ref2, _ref3;
+var _ref, _ref2;
+/**
+* 全局标记，用于跨 KeqModule 实例去重
+*
+* 当 pnpm 等包管理器因为 peerDependencies 版本差异生成多个
+* `@keq-request/nestjs` 的 `.pnpm` 目录时，Node.js 会将它们视为不同模块，
+* 产生多个 `KeqModule` 类引用，导致 NestJS 创建多个 `KeqModule` 实例。
+*
+* 每个实例的 `onModuleInit()` 都会遍历 `ModulesContainer` 并调用所有
+* 实现了 `configureKeqMiddleware` 的模块。通过 `Symbol.for()`（全局 Symbol
+* 注册表）在 `moduleWrapper.metatype` 上做标记，确保同一个模块类
+* 只被处理一次，无论有多少个 `KeqModule` 实例。
+*/
+const CONFIGURED_SYMBOL = Symbol.for("__keq_middleware_configured__");
+/**
+* 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
+* 是否显式导入了 `KeqModule`。
+*
+* NestJS 初始化分为两个严格串行的阶段：
+* 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
+*    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
+* 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
+*
+* 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
+* 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
+*
+* 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
+* - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
+* - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
+*/
+function validateConfigureKeqMiddlewareImports(modulesContainer) {
+	let keqModuleMetatype;
+	for (const [, moduleWrapper] of modulesContainer) if (moduleWrapper.metatype?.name === "KeqModule") {
+		keqModuleMetatype = moduleWrapper.metatype;
+		break;
+	}
+	for (const [, moduleWrapper] of modulesContainer) {
+		const metatype = moduleWrapper.metatype;
+		if (typeof metatype?.prototype?.configureKeqMiddleware !== "function") continue;
+		if (![...moduleWrapper.imports].some((importedModule) => importedModule.metatype === keqModuleMetatype)) throw new Error(`[KeqModule] '${metatype.name}' implements configureKeqMiddleware() but does not explicitly import KeqModule. Add 'imports: [KeqModule]' to its @Module() decorator to ensure middleware is registered before the module's onModuleInit() runs.`);
+	}
+}
 let KeqModule = class KeqModule {
-	constructor(modulesContainer, moduleRef, keqRequest) {
+	constructor(modulesContainer, keqRequest) {
 		this.modulesContainer = modulesContainer;
-		this.moduleRef = moduleRef;
 		this.keqRequest = keqRequest;
+		validateConfigureKeqMiddlewareImports(modulesContainer);
 	}
 	onModuleInit() {
 		for (const [, moduleWrapper] of this.modulesContainer) {
 			const instance = moduleWrapper.instance;
-			if (hasConfigureKeqMiddleware(instance)) {
-				const consumer = new KeqMiddlewareConsumerImpl();
-				instance.configureKeqMiddleware(consumer);
-				consumer.applyTo(this.keqRequest, this.moduleRef);
-			}
+			if (!hasConfigureKeqMiddleware(instance)) continue;
+			if (moduleWrapper.metatype[CONFIGURED_SYMBOL]) continue;
+			moduleWrapper.metatype[CONFIGURED_SYMBOL] = true;
+			const consumer = new KeqMiddlewareConsumerImpl();
+			instance.configureKeqMiddleware(consumer);
+			consumer.applyTo(this.keqRequest, this.modulesContainer);
 		}
 	}
 };
@@ -139,11 +231,7 @@ KeqModule = __decorate([
 		}],
 		exports: [keq.KeqRequest]
 	}),
-	__decorateMetadata("design:paramtypes", [
-		typeof (_ref = typeof _nestjs_core.ModulesContainer !== "undefined" && _nestjs_core.ModulesContainer) === "function" ? _ref : Object,
-		typeof (_ref2 = typeof _nestjs_core.ModuleRef !== "undefined" && _nestjs_core.ModuleRef) === "function" ? _ref2 : Object,
-		typeof (_ref3 = typeof keq.KeqRequest !== "undefined" && keq.KeqRequest) === "function" ? _ref3 : Object
-	])
+	__decorateMetadata("design:paramtypes", [typeof (_ref = typeof _nestjs_core.ModulesContainer !== "undefined" && _nestjs_core.ModulesContainer) === "function" ? _ref : Object, typeof (_ref2 = typeof keq.KeqRequest !== "undefined" && keq.KeqRequest) === "function" ? _ref2 : Object])
 ], KeqModule);
 //#endregion
 exports.KEQ_ROUTES = KEQ_ROUTES;
@@ -153,5 +241,6 @@ Object.defineProperty(exports, "KeqModule", {
 		return KeqModule;
 	}
 });
+exports.validateConfigureKeqMiddlewareImports = validateConfigureKeqMiddlewareImports;
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["KeqRequest"],"sources":["../src/constants.ts","../src/keq-middleware-consumer.ts","../src/utils/has-configure-keq-middleware.ts","../src/keq.module.ts"],"sourcesContent":["export const KEQ_ROUTES = {\n  ALL: Symbol('KEQ_ROUTES.ALL'),\n} as const\n","import type { Type } from '@nestjs/common'\nimport type { ModuleRef } from '@nestjs/core'\nimport type { KeqMiddleware, KeqRoute } from 'keq'\nimport { composeRoute, KeqRequest } from 'keq'\nimport picomatch from 'picomatch'\nimport { KEQ_ROUTES } from './constants.js'\nimport type { KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\n\n\ninterface MiddlewareEntry {\n  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>\n  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>\n}\n\nexport class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {\n  private entries: MiddlewareEntry[] = []\n\n  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {\n    const entry: MiddlewareEntry = { middlewares, routes: [] }\n    this.entries.push(entry)\n    return {\n      forRoutes: (...routes) => {\n        entry.routes = routes\n        return this\n      },\n    }\n  }\n\n  applyTo(keqRequest: KeqRequest, moduleRef: ModuleRef): void {\n    for (const entry of this.entries) {\n      const resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef))\n      const isGlobal = entry.routes.length === 0\n        || entry.routes.some((r) => r === KEQ_ROUTES.ALL)\n\n      if (isGlobal) {\n        for (const mw of resolved) keqRequest.use(mw)\n      } else {\n        for (const routeTarget of entry.routes) {\n          if (routeTarget === KEQ_ROUTES.ALL) continue\n\n          if (this.isKeqModuleClass(routeTarget)) {\n            const targetRequest = moduleRef.get<KeqRequest>(routeTarget.KEQ_REQUEST, { strict: false })\n            if (targetRequest) {\n              for (const mw of resolved) targetRequest.use(mw)\n            }\n          } else {\n            const route = this.buildRoute(routeTarget as KeqRouteInfo)\n            keqRequest.useRouter().route(route, resolved)\n          }\n        }\n      }\n    }\n  }\n\n  private isKeqModuleClass(route: unknown): route is KeqModuleClass {\n    return (\n      typeof route === 'function'\n      && 'KEQ_REQUEST' in route\n      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'\n    )\n  }\n\n  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {\n    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype\n  }\n\n  private resolveMiddleware(m: Type<KeqNestMiddleware> | KeqMiddleware, moduleRef: ModuleRef): KeqMiddleware {\n    if (this.isNestMiddlewareClass(m)) {\n      const instance = moduleRef.get<KeqNestMiddleware>(m, { strict: false })\n      return async (ctx, next) => {\n        await instance.use(ctx, next)\n      }\n    }\n    return m\n  }\n\n  private buildRoute(info: KeqRouteInfo): KeqRoute {\n    const routes: KeqRoute[] = []\n    if (info.host) {\n      const host = info.host\n      routes.push((ctx) => ctx.request.url.host === host)\n    }\n    if (info.method) {\n      const method = info.method.toLowerCase()\n      routes.push((ctx) => ctx.request.method.toLowerCase() === method)\n    }\n    if (info.pathname) {\n      const isMatch: (test: string) => boolean = picomatch(info.pathname)\n      routes.push((ctx) => isMatch(ctx.request.url.pathname))\n    }\n    if (routes.length === 1) return routes[0]\n    return composeRoute(routes)\n  }\n}\n","import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'\n\n\nexport function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {\n  return (\n    instance !== null\n    && instance !== undefined\n    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'\n  )\n}\n","import { Global, Module, OnModuleInit } from '@nestjs/common'\nimport { ModulesContainer, ModuleRef } from '@nestjs/core'\nimport { KeqRequest } from 'keq'\nimport { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'\nimport { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'\n\n\n@Global()\n@Module({\n  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],\n  exports: [KeqRequest],\n})\nexport class KeqModule implements OnModuleInit {\n  constructor(\n    private readonly modulesContainer: ModulesContainer,\n    private readonly moduleRef: ModuleRef,\n    private readonly keqRequest: KeqRequest,\n  ) {}\n\n  onModuleInit(): void {\n    for (const [, moduleWrapper] of this.modulesContainer) {\n      const instance = moduleWrapper.instance\n      if (hasConfigureKeqMiddleware(instance)) {\n        const consumer = new KeqMiddlewareConsumerImpl()\n        instance.configureKeqMiddleware(consumer)\n        consumer.applyTo(this.keqRequest, this.moduleRef)\n      }\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["KeqRequest"],"sources":["../src/constants.ts","../src/keq-middleware-consumer.ts","../src/utils/has-configure-keq-middleware.ts","../src/keq.module.ts"],"sourcesContent":["export const KEQ_ROUTES = {\n  ALL: Symbol('KEQ_ROUTES.ALL'),\n} as const\n","import type { Type } from '@nestjs/common'\nimport type { ModulesContainer } from '@nestjs/core'\nimport type { KeqExecutionContext, KeqMiddleware, KeqRoute } from 'keq'\nimport { composeRoute, KeqRequest } from 'keq'\nimport picomatch from 'picomatch'\nimport { KEQ_ROUTES } from './constants.js'\nimport type { KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\n\n\ninterface MiddlewareEntry {\n  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>\n  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>\n  excludedRouteInfos?: KeqRouteInfo[]\n}\n\nexport class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {\n  private entries: MiddlewareEntry[] = []\n\n  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {\n    const entry: MiddlewareEntry = { middlewares, routes: [] }\n    const excludedRouteInfos: KeqRouteInfo[] = []\n    this.entries.push(entry)\n\n    const proxy: KeqMiddlewareConfigProxy = {\n      exclude: (...routes) => {\n        excludedRouteInfos.push(...routes)\n        return proxy\n      },\n      forRoutes: (...routes) => {\n        entry.routes = routes\n        if (excludedRouteInfos.length > 0) {\n          entry.excludedRouteInfos = excludedRouteInfos\n        }\n        return this\n      },\n    }\n    return proxy\n  }\n\n  applyTo(keqRequest: KeqRequest, modulesContainer: ModulesContainer): void {\n    for (const entry of this.entries) {\n      let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, modulesContainer))\n\n      if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {\n        const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info))\n        resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes))\n      }\n\n      const isGlobal = entry.routes.length === 0\n        || entry.routes.some((r) => r === KEQ_ROUTES.ALL)\n\n      if (isGlobal) {\n        for (const mw of resolved) keqRequest.use(mw)\n      } else {\n        for (const routeTarget of entry.routes) {\n          if (routeTarget === KEQ_ROUTES.ALL) continue\n\n          if (this.isKeqModuleClass(routeTarget)) {\n            const targetRequest = this.findInModulesContainer(routeTarget, modulesContainer)\n            if (targetRequest) {\n              for (const mw of resolved) targetRequest.use(mw)\n            }\n          } else {\n            const route = this.buildRoute(routeTarget as KeqRouteInfo)\n            keqRequest.useRouter().route(route, resolved)\n          }\n        }\n      }\n    }\n  }\n\n  private isKeqModuleClass(route: unknown): route is KeqModuleClass {\n    return (\n      typeof route === 'function'\n      && 'KEQ_REQUEST' in route\n      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'\n    )\n  }\n\n  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {\n    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype\n  }\n\n  private findMiddlewareInstance(\n    middlewareClass: Type<KeqNestMiddleware>,\n    modulesContainer: ModulesContainer,\n  ): KeqNestMiddleware | undefined {\n    for (const [, moduleWrapper] of modulesContainer) {\n      const provider = moduleWrapper.providers.get(middlewareClass)\n      if (provider?.instance) {\n        return provider.instance as KeqNestMiddleware\n      }\n    }\n    return undefined\n  }\n\n  private resolveMiddleware(\n    m: Type<KeqNestMiddleware> | KeqMiddleware,\n    modulesContainer: ModulesContainer,\n  ): KeqMiddleware {\n    if (this.isNestMiddlewareClass(m)) {\n      const instance = this.findMiddlewareInstance(m, modulesContainer)\n      if (!instance) {\n        throw new Error(\n          `[KeqModule] Nest middleware class '${m.name}' is not registered as a provider in any module. `\n          + 'Ensure the middleware class is added to the providers array of a @Module() decorator.',\n        )\n      }\n      return async (ctx, next) => {\n        await instance.use(ctx, next)\n      }\n    }\n    return m\n  }\n\n  /**\n   * 从 ModulesContainer 中查找目标 KeqModule 的 KeqRequest 实例\n   *\n   * 通过 metatype 精确匹配模块，从模块 providers 中直接获取 KeqRequest。\n   * 不依赖 ModuleRef 的作用域机制，直接从 NestJS 全局模块容器中查找。\n   *\n   * @param routeTarget - 目标 KeqModule 类，必须具有 KEQ_REQUEST symbol 属性\n   * @param modulesContainer - NestJS 全局模块容器\n   * @returns KeqRequest 实例，未找到时返回 undefined\n   */\n  private findInModulesContainer(\n    routeTarget: KeqModuleClass,\n    modulesContainer: ModulesContainer,\n  ): KeqRequest | undefined {\n    const token = routeTarget.KEQ_REQUEST\n    for (const [, moduleWrapper] of modulesContainer) {\n      if (moduleWrapper.metatype !== routeTarget) continue\n\n      const provider = moduleWrapper.providers.get(token)\n      if (!provider) continue\n\n      if (provider.instance) {\n        return provider.instance as KeqRequest\n      }\n    }\n    return undefined\n  }\n\n  private buildRoute(info: KeqRouteInfo): KeqRoute {\n    const routes: KeqRoute[] = []\n    if (info.host) {\n      const host = info.host\n      routes.push((ctx) => ctx.request.url.host === host)\n    }\n    if (info.method) {\n      const method = info.method.toLowerCase()\n      routes.push((ctx) => ctx.request.method.toLowerCase() === method)\n    }\n    if (info.pathname) {\n      const isMatch: (test: string) => boolean = picomatch(info.pathname)\n      routes.push((ctx) => isMatch(ctx.request.url.pathname))\n    }\n    if (routes.length === 1) return routes[0]\n    return composeRoute(routes)\n  }\n\n  private wrapWithExclusion(middleware: KeqMiddleware, excludedRoutes: KeqRoute[]): KeqMiddleware {\n    const excluded: KeqMiddleware = async (ctx, next) => {\n      if (await this.checkExcluded(ctx, excludedRoutes)) {\n        return next()\n      }\n      return middleware(ctx, next)\n    }\n    return excluded\n  }\n\n  private async checkExcluded(ctx: KeqExecutionContext, excludedRoutes: KeqRoute[]): Promise<boolean> {\n    for (const route of excludedRoutes) {\n      if (await route(ctx)) return true\n    }\n    return false\n  }\n}\n","import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'\n\n\nexport function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {\n  return (\n    instance !== null\n    && instance !== undefined\n    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'\n  )\n}\n","import { Global, Module, OnModuleInit, Type } from '@nestjs/common'\nimport { ModulesContainer } from '@nestjs/core'\nimport { KeqRequest } from 'keq'\nimport { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'\nimport { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'\n\n/**\n * 全局标记，用于跨 KeqModule 实例去重\n *\n * 当 pnpm 等包管理器因为 peerDependencies 版本差异生成多个\n * `@keq-request/nestjs` 的 `.pnpm` 目录时，Node.js 会将它们视为不同模块，\n * 产生多个 `KeqModule` 类引用，导致 NestJS 创建多个 `KeqModule` 实例。\n *\n * 每个实例的 `onModuleInit()` 都会遍历 `ModulesContainer` 并调用所有\n * 实现了 `configureKeqMiddleware` 的模块。通过 `Symbol.for()`（全局 Symbol\n * 注册表）在 `moduleWrapper.metatype` 上做标记，确保同一个模块类\n * 只被处理一次，无论有多少个 `KeqModule` 实例。\n */\nconst CONFIGURED_SYMBOL = Symbol.for('__keq_middleware_configured__')\n\n/**\n * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块\n * 是否显式导入了 `KeqModule`。\n *\n * NestJS 初始化分为两个严格串行的阶段：\n * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，\n *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set\n * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit\n *\n * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，\n * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。\n *\n * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：\n * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中\n * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败\n */\nexport function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void {\n  // 从 ModulesContainer 中查找 KeqModule 的 metatype，\n  // 解决 pnpm 下 @keq-request/nestjs 存在多个包实例导致 === 引用比对失败的问题\n  let keqModuleMetatype: Type<any> | undefined\n  for (const [, moduleWrapper] of modulesContainer) {\n    if (moduleWrapper.metatype?.name === 'KeqModule') {\n      keqModuleMetatype = moduleWrapper.metatype\n      break\n    }\n  }\n\n  for (const [, moduleWrapper] of modulesContainer) {\n    const metatype = moduleWrapper.metatype\n    if (typeof metatype?.prototype?.configureKeqMiddleware !== 'function') continue\n\n    // 使用运行时 imports Set（NestJS 扫描阶段已解析 DynamicModule 的 imports），\n    // 替代 Reflect.getMetadata('imports', metatype)，解决：\n    // 1. DynamicModule 的 imports 无法通过静态元数据检测\n    // 2. 重复包实例导致的类引用不匹配\n    const hasKeqModule = [...moduleWrapper.imports].some(\n      (importedModule) => importedModule.metatype === keqModuleMetatype,\n    )\n\n    if (!hasKeqModule) {\n      throw new Error(\n        `[KeqModule] '${metatype.name}' implements configureKeqMiddleware() `\n        + 'but does not explicitly import KeqModule. '\n        + 'Add \\'imports: [KeqModule]\\' to its @Module() decorator to ensure '\n        + 'middleware is registered before the module\\'s onModuleInit() runs.',\n      )\n    }\n  }\n}\n\n@Global()\n@Module({\n  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],\n  exports: [KeqRequest],\n})\nexport class KeqModule implements OnModuleInit {\n  constructor(\n    private readonly modulesContainer: ModulesContainer,\n    private readonly keqRequest: KeqRequest,\n  ) {\n    validateConfigureKeqMiddlewareImports(modulesContainer)\n  }\n\n  onModuleInit(): void {\n    for (const [, moduleWrapper] of this.modulesContainer) {\n      const instance = moduleWrapper.instance\n      if (!hasConfigureKeqMiddleware(instance)) continue\n\n      // 跨 KeqModule 实例去重：\n      // moduleWrapper.metatype 是同一个类引用，Symbol.for 是全局共享 key\n      if (moduleWrapper.metatype[CONFIGURED_SYMBOL]) continue\n      moduleWrapper.metatype[CONFIGURED_SYMBOL] = true\n\n      const consumer = new KeqMiddlewareConsumerImpl()\n      instance.configureKeqMiddleware(consumer)\n      consumer.applyTo(this.keqRequest, this.modulesContainer)\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Global, Module } from "@nestjs/common";
-import { ModuleRef, ModulesContainer } from "@nestjs/core";
+import { ModulesContainer } from "@nestjs/core";
 import { KeqRequest, composeRoute } from "keq";
 import picomatch from "picomatch";
 //#region src/constants.ts
@@ -13,20 +13,33 @@ var KeqMiddlewareConsumerImpl = class {
 			middlewares,
 			routes: []
 		};
+		const excludedRouteInfos = [];
 		this.entries.push(entry);
-		return { forRoutes: (...routes) => {
-			entry.routes = routes;
-			return this;
-		} };
+		const proxy = {
+			exclude: (...routes) => {
+				excludedRouteInfos.push(...routes);
+				return proxy;
+			},
+			forRoutes: (...routes) => {
+				entry.routes = routes;
+				if (excludedRouteInfos.length > 0) entry.excludedRouteInfos = excludedRouteInfos;
+				return this;
+			}
+		};
+		return proxy;
 	}
-	applyTo(keqRequest, moduleRef) {
+	applyTo(keqRequest, modulesContainer) {
 		for (const entry of this.entries) {
-			const resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef));
+			let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, modulesContainer));
+			if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {
+				const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info));
+				resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes));
+			}
 			if (entry.routes.length === 0 || entry.routes.some((r) => r === KEQ_ROUTES.ALL)) for (const mw of resolved) keqRequest.use(mw);
 			else for (const routeTarget of entry.routes) {
 				if (routeTarget === KEQ_ROUTES.ALL) continue;
 				if (this.isKeqModuleClass(routeTarget)) {
-					const targetRequest = moduleRef.get(routeTarget.KEQ_REQUEST, { strict: false });
+					const targetRequest = this.findInModulesContainer(routeTarget, modulesContainer);
 					if (targetRequest) for (const mw of resolved) targetRequest.use(mw);
 				} else {
 					const route = this.buildRoute(routeTarget);
@@ -41,15 +54,41 @@ var KeqMiddlewareConsumerImpl = class {
 	isNestMiddlewareClass(m) {
 		return typeof m === "function" && m.prototype !== void 0 && "use" in m.prototype;
 	}
-	resolveMiddleware(m, moduleRef) {
+	findMiddlewareInstance(middlewareClass, modulesContainer) {
+		for (const [, moduleWrapper] of modulesContainer) {
+			const provider = moduleWrapper.providers.get(middlewareClass);
+			if (provider?.instance) return provider.instance;
+		}
+	}
+	resolveMiddleware(m, modulesContainer) {
 		if (this.isNestMiddlewareClass(m)) {
-			const instance = moduleRef.get(m, { strict: false });
+			const instance = this.findMiddlewareInstance(m, modulesContainer);
+			if (!instance) throw new Error(`[KeqModule] Nest middleware class '${m.name}' is not registered as a provider in any module. Ensure the middleware class is added to the providers array of a @Module() decorator.`);
 			return async (ctx, next) => {
 				await instance.use(ctx, next);
 			};
 		}
 		return m;
 	}
+	/**
+	* 从 ModulesContainer 中查找目标 KeqModule 的 KeqRequest 实例
+	*
+	* 通过 metatype 精确匹配模块，从模块 providers 中直接获取 KeqRequest。
+	* 不依赖 ModuleRef 的作用域机制，直接从 NestJS 全局模块容器中查找。
+	*
+	* @param routeTarget - 目标 KeqModule 类，必须具有 KEQ_REQUEST symbol 属性
+	* @param modulesContainer - NestJS 全局模块容器
+	* @returns KeqRequest 实例，未找到时返回 undefined
+	*/
+	findInModulesContainer(routeTarget, modulesContainer) {
+		const token = routeTarget.KEQ_REQUEST;
+		for (const [, moduleWrapper] of modulesContainer) {
+			if (moduleWrapper.metatype !== routeTarget) continue;
+			const provider = moduleWrapper.providers.get(token);
+			if (!provider) continue;
+			if (provider.instance) return provider.instance;
+		}
+	}
 	buildRoute(info) {
 		const routes = [];
 		if (info.host) {
@@ -67,6 +106,17 @@ var KeqMiddlewareConsumerImpl = class {
 		if (routes.length === 1) return routes[0];
 		return composeRoute(routes);
 	}
+	wrapWithExclusion(middleware, excludedRoutes) {
+		const excluded = async (ctx, next) => {
+			if (await this.checkExcluded(ctx, excludedRoutes)) return next();
+			return middleware(ctx, next);
+		};
+		return excluded;
+	}
+	async checkExcluded(ctx, excludedRoutes) {
+		for (const route of excludedRoutes) if (await route(ctx)) return true;
+		return false;
+	}
 };
 //#endregion
 //#region src/utils/has-configure-keq-middleware.ts
@@ -88,21 +138,63 @@ function __decorate(decorators, target, key, desc) {
 }
 //#endregion
 //#region src/keq.module.ts
-var _ref, _ref2, _ref3;
+var _ref, _ref2;
+/**
+* 全局标记，用于跨 KeqModule 实例去重
+*
+* 当 pnpm 等包管理器因为 peerDependencies 版本差异生成多个
+* `@keq-request/nestjs` 的 `.pnpm` 目录时，Node.js 会将它们视为不同模块，
+* 产生多个 `KeqModule` 类引用，导致 NestJS 创建多个 `KeqModule` 实例。
+*
+* 每个实例的 `onModuleInit()` 都会遍历 `ModulesContainer` 并调用所有
+* 实现了 `configureKeqMiddleware` 的模块。通过 `Symbol.for()`（全局 Symbol
+* 注册表）在 `moduleWrapper.metatype` 上做标记，确保同一个模块类
+* 只被处理一次，无论有多少个 `KeqModule` 实例。
+*/
+const CONFIGURED_SYMBOL = Symbol.for("__keq_middleware_configured__");
+/**
+* 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
+* 是否显式导入了 `KeqModule`。
+*
+* NestJS 初始化分为两个严格串行的阶段：
+* 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
+*    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
+* 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
+*
+* 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
+* 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
+*
+* 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
+* - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
+* - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
+*/
+function validateConfigureKeqMiddlewareImports(modulesContainer) {
+	let keqModuleMetatype;
+	for (const [, moduleWrapper] of modulesContainer) if (moduleWrapper.metatype?.name === "KeqModule") {
+		keqModuleMetatype = moduleWrapper.metatype;
+		break;
+	}
+	for (const [, moduleWrapper] of modulesContainer) {
+		const metatype = moduleWrapper.metatype;
+		if (typeof metatype?.prototype?.configureKeqMiddleware !== "function") continue;
+		if (![...moduleWrapper.imports].some((importedModule) => importedModule.metatype === keqModuleMetatype)) throw new Error(`[KeqModule] '${metatype.name}' implements configureKeqMiddleware() but does not explicitly import KeqModule. Add 'imports: [KeqModule]' to its @Module() decorator to ensure middleware is registered before the module's onModuleInit() runs.`);
+	}
+}
 let KeqModule = class KeqModule {
-	constructor(modulesContainer, moduleRef, keqRequest) {
+	constructor(modulesContainer, keqRequest) {
 		this.modulesContainer = modulesContainer;
-		this.moduleRef = moduleRef;
 		this.keqRequest = keqRequest;
+		validateConfigureKeqMiddlewareImports(modulesContainer);
 	}
 	onModuleInit() {
 		for (const [, moduleWrapper] of this.modulesContainer) {
 			const instance = moduleWrapper.instance;
-			if (hasConfigureKeqMiddleware(instance)) {
-				const consumer = new KeqMiddlewareConsumerImpl();
-				instance.configureKeqMiddleware(consumer);
-				consumer.applyTo(this.keqRequest, this.moduleRef);
-			}
+			if (!hasConfigureKeqMiddleware(instance)) continue;
+			if (moduleWrapper.metatype[CONFIGURED_SYMBOL]) continue;
+			moduleWrapper.metatype[CONFIGURED_SYMBOL] = true;
+			const consumer = new KeqMiddlewareConsumerImpl();
+			instance.configureKeqMiddleware(consumer);
+			consumer.applyTo(this.keqRequest, this.modulesContainer);
 		}
 	}
 };
@@ -115,13 +207,9 @@ KeqModule = __decorate([
 		}],
 		exports: [KeqRequest]
 	}),
-	__decorateMetadata("design:paramtypes", [
-		typeof (_ref = typeof ModulesContainer !== "undefined" && ModulesContainer) === "function" ? _ref : Object,
-		typeof (_ref2 = typeof ModuleRef !== "undefined" && ModuleRef) === "function" ? _ref2 : Object,
-		typeof (_ref3 = typeof KeqRequest !== "undefined" && KeqRequest) === "function" ? _ref3 : Object
-	])
+	__decorateMetadata("design:paramtypes", [typeof (_ref = typeof ModulesContainer !== "undefined" && ModulesContainer) === "function" ? _ref : Object, typeof (_ref2 = typeof KeqRequest !== "undefined" && KeqRequest) === "function" ? _ref2 : Object])
 ], KeqModule);
 //#endregion
-export { KEQ_ROUTES, KeqModule };
+export { KEQ_ROUTES, KeqModule, validateConfigureKeqMiddlewareImports };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/constants.ts","../src/keq-middleware-consumer.ts","../src/utils/has-configure-keq-middleware.ts","../src/keq.module.ts"],"sourcesContent":["export const KEQ_ROUTES = {\n  ALL: Symbol('KEQ_ROUTES.ALL'),\n} as const\n","import type { Type } from '@nestjs/common'\nimport type { ModuleRef } from '@nestjs/core'\nimport type { KeqMiddleware, KeqRoute } from 'keq'\nimport { composeRoute, KeqRequest } from 'keq'\nimport picomatch from 'picomatch'\nimport { KEQ_ROUTES } from './constants.js'\nimport type { KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\n\n\ninterface MiddlewareEntry {\n  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>\n  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>\n}\n\nexport class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {\n  private entries: MiddlewareEntry[] = []\n\n  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {\n    const entry: MiddlewareEntry = { middlewares, routes: [] }\n    this.entries.push(entry)\n    return {\n      forRoutes: (...routes) => {\n        entry.routes = routes\n        return this\n      },\n    }\n  }\n\n  applyTo(keqRequest: KeqRequest, moduleRef: ModuleRef): void {\n    for (const entry of this.entries) {\n      const resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef))\n      const isGlobal = entry.routes.length === 0\n        || entry.routes.some((r) => r === KEQ_ROUTES.ALL)\n\n      if (isGlobal) {\n        for (const mw of resolved) keqRequest.use(mw)\n      } else {\n        for (const routeTarget of entry.routes) {\n          if (routeTarget === KEQ_ROUTES.ALL) continue\n\n          if (this.isKeqModuleClass(routeTarget)) {\n            const targetRequest = moduleRef.get<KeqRequest>(routeTarget.KEQ_REQUEST, { strict: false })\n            if (targetRequest) {\n              for (const mw of resolved) targetRequest.use(mw)\n            }\n          } else {\n            const route = this.buildRoute(routeTarget as KeqRouteInfo)\n            keqRequest.useRouter().route(route, resolved)\n          }\n        }\n      }\n    }\n  }\n\n  private isKeqModuleClass(route: unknown): route is KeqModuleClass {\n    return (\n      typeof route === 'function'\n      && 'KEQ_REQUEST' in route\n      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'\n    )\n  }\n\n  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {\n    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype\n  }\n\n  private resolveMiddleware(m: Type<KeqNestMiddleware> | KeqMiddleware, moduleRef: ModuleRef): KeqMiddleware {\n    if (this.isNestMiddlewareClass(m)) {\n      const instance = moduleRef.get<KeqNestMiddleware>(m, { strict: false })\n      return async (ctx, next) => {\n        await instance.use(ctx, next)\n      }\n    }\n    return m\n  }\n\n  private buildRoute(info: KeqRouteInfo): KeqRoute {\n    const routes: KeqRoute[] = []\n    if (info.host) {\n      const host = info.host\n      routes.push((ctx) => ctx.request.url.host === host)\n    }\n    if (info.method) {\n      const method = info.method.toLowerCase()\n      routes.push((ctx) => ctx.request.method.toLowerCase() === method)\n    }\n    if (info.pathname) {\n      const isMatch: (test: string) => boolean = picomatch(info.pathname)\n      routes.push((ctx) => isMatch(ctx.request.url.pathname))\n    }\n    if (routes.length === 1) return routes[0]\n    return composeRoute(routes)\n  }\n}\n","import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'\n\n\nexport function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {\n  return (\n    instance !== null\n    && instance !== undefined\n    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'\n  )\n}\n","import { Global, Module, OnModuleInit } from '@nestjs/common'\nimport { ModulesContainer, ModuleRef } from '@nestjs/core'\nimport { KeqRequest } from 'keq'\nimport { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'\nimport { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'\n\n\n@Global()\n@Module({\n  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],\n  exports: [KeqRequest],\n})\nexport class KeqModule implements OnModuleInit {\n  constructor(\n    private readonly modulesContainer: ModulesContainer,\n    private readonly moduleRef: ModuleRef,\n    private readonly keqRequest: KeqRequest,\n  ) {}\n\n  onModuleInit(): void {\n    for (const [, moduleWrapper] of this.modulesContainer) {\n      const instance = moduleWrapper.instance\n      if (hasConfigureKeqMiddleware(instance)) {\n        const consumer = new KeqMiddlewareConsumerImpl()\n        instance.configureKeqMiddleware(consumer)\n        consumer.applyTo(this.keqRequest, this.moduleRef)\n      }\n    }\n  }\n}\n"],"mappings":";;;;;AAAA,MAAa,aAAa,EACxB,KAAK,OAAO,iBAAiB,EAC9B;;;ACaD,IAAa,4BAAb,MAAwE;CACtE,UAAqC,EAAE;CAEvC,MAAM,GAAG,aAAuF;EAC9F,MAAM,QAAyB;GAAE;GAAa,QAAQ,EAAE;GAAE;AAC1D,OAAK,QAAQ,KAAK,MAAM;AACxB,SAAO,EACL,YAAY,GAAG,WAAW;AACxB,SAAM,SAAS;AACf,UAAO;KAEV;;CAGH,QAAQ,YAAwB,WAA4B;AAC1D,OAAK,MAAM,SAAS,KAAK,SAAS;GAChC,MAAM,WAAW,MAAM,YAAY,KAAK,MAAM,KAAK,kBAAkB,GAAG,UAAU,CAAC;AAInF,OAHiB,MAAM,OAAO,WAAW,KACpC,MAAM,OAAO,MAAM,MAAM,MAAM,WAAW,IAAI,CAGjD,MAAK,MAAM,MAAM,SAAU,YAAW,IAAI,GAAG;OAE7C,MAAK,MAAM,eAAe,MAAM,QAAQ;AACtC,QAAI,gBAAgB,WAAW,IAAK;AAEpC,QAAI,KAAK,iBAAiB,YAAY,EAAE;KACtC,MAAM,gBAAgB,UAAU,IAAgB,YAAY,aAAa,EAAE,QAAQ,OAAO,CAAC;AAC3F,SAAI,cACF,MAAK,MAAM,MAAM,SAAU,eAAc,IAAI,GAAG;WAE7C;KACL,MAAM,QAAQ,KAAK,WAAW,YAA4B;AAC1D,gBAAW,WAAW,CAAC,MAAM,OAAO,SAAS;;;;;CAOvD,iBAAyB,OAAyC;AAChE,SACE,OAAO,UAAU,cACd,iBAAiB,SACjB,OAAQ,MAAkC,gBAAgB;;CAIjE,sBAA8B,GAA0E;AACtG,SAAO,OAAO,MAAM,cAAc,EAAE,cAAc,KAAA,KAAa,SAAS,EAAE;;CAG5E,kBAA0B,GAA4C,WAAqC;AACzG,MAAI,KAAK,sBAAsB,EAAE,EAAE;GACjC,MAAM,WAAW,UAAU,IAAuB,GAAG,EAAE,QAAQ,OAAO,CAAC;AACvE,UAAO,OAAO,KAAK,SAAS;AAC1B,UAAM,SAAS,IAAI,KAAK,KAAK;;;AAGjC,SAAO;;CAGT,WAAmB,MAA8B;EAC/C,MAAM,SAAqB,EAAE;AAC7B,MAAI,KAAK,MAAM;GACb,MAAM,OAAO,KAAK;AAClB,UAAO,MAAM,QAAQ,IAAI,QAAQ,IAAI,SAAS,KAAK;;AAErD,MAAI,KAAK,QAAQ;GACf,MAAM,SAAS,KAAK,OAAO,aAAa;AACxC,UAAO,MAAM,QAAQ,IAAI,QAAQ,OAAO,aAAa,KAAK,OAAO;;AAEnE,MAAI,KAAK,UAAU;GACjB,MAAM,UAAqC,UAAU,KAAK,SAAS;AACnE,UAAO,MAAM,QAAQ,QAAQ,IAAI,QAAQ,IAAI,SAAS,CAAC;;AAEzD,MAAI,OAAO,WAAW,EAAG,QAAO,OAAO;AACvC,SAAO,aAAa,OAAO;;;;;ACzF/B,SAAgB,0BAA0B,UAAoD;AAC5F,QACE,aAAa,QACV,aAAa,KAAA,KACb,OAAQ,SAAqC,2BAA2B;;;;;;;;;;;;;;;;;;ACKxE,IAAA,YAAA,MAAM,UAAkC;CAC7C,YACE,kBACA,WACA,YACA;AAHiB,OAAA,mBAAA;AACA,OAAA,YAAA;AACA,OAAA,aAAA;;CAGnB,eAAqB;AACnB,OAAK,MAAM,GAAG,kBAAkB,KAAK,kBAAkB;GACrD,MAAM,WAAW,cAAc;AAC/B,OAAI,0BAA0B,SAAS,EAAE;IACvC,MAAM,WAAW,IAAI,2BAA2B;AAChD,aAAS,uBAAuB,SAAS;AACzC,aAAS,QAAQ,KAAK,YAAY,KAAK,UAAU;;;;;;CAlBxD,QAAQ;CACR,OAAO;EACN,WAAW,CAAC;GAAE,SAAS;GAAY,kBAAkB,IAAI,YAAY;GAAE,CAAC;EACxE,SAAS,CAAC,WAAW;EACtB,CAAC"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/constants.ts","../src/keq-middleware-consumer.ts","../src/utils/has-configure-keq-middleware.ts","../src/keq.module.ts"],"sourcesContent":["export const KEQ_ROUTES = {\n  ALL: Symbol('KEQ_ROUTES.ALL'),\n} as const\n","import type { Type } from '@nestjs/common'\nimport type { ModulesContainer } from '@nestjs/core'\nimport type { KeqExecutionContext, KeqMiddleware, KeqRoute } from 'keq'\nimport { composeRoute, KeqRequest } from 'keq'\nimport picomatch from 'picomatch'\nimport { KEQ_ROUTES } from './constants.js'\nimport type { KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'\nimport type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'\n\n\ninterface MiddlewareEntry {\n  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>\n  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>\n  excludedRouteInfos?: KeqRouteInfo[]\n}\n\nexport class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {\n  private entries: MiddlewareEntry[] = []\n\n  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {\n    const entry: MiddlewareEntry = { middlewares, routes: [] }\n    const excludedRouteInfos: KeqRouteInfo[] = []\n    this.entries.push(entry)\n\n    const proxy: KeqMiddlewareConfigProxy = {\n      exclude: (...routes) => {\n        excludedRouteInfos.push(...routes)\n        return proxy\n      },\n      forRoutes: (...routes) => {\n        entry.routes = routes\n        if (excludedRouteInfos.length > 0) {\n          entry.excludedRouteInfos = excludedRouteInfos\n        }\n        return this\n      },\n    }\n    return proxy\n  }\n\n  applyTo(keqRequest: KeqRequest, modulesContainer: ModulesContainer): void {\n    for (const entry of this.entries) {\n      let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, modulesContainer))\n\n      if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {\n        const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info))\n        resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes))\n      }\n\n      const isGlobal = entry.routes.length === 0\n        || entry.routes.some((r) => r === KEQ_ROUTES.ALL)\n\n      if (isGlobal) {\n        for (const mw of resolved) keqRequest.use(mw)\n      } else {\n        for (const routeTarget of entry.routes) {\n          if (routeTarget === KEQ_ROUTES.ALL) continue\n\n          if (this.isKeqModuleClass(routeTarget)) {\n            const targetRequest = this.findInModulesContainer(routeTarget, modulesContainer)\n            if (targetRequest) {\n              for (const mw of resolved) targetRequest.use(mw)\n            }\n          } else {\n            const route = this.buildRoute(routeTarget as KeqRouteInfo)\n            keqRequest.useRouter().route(route, resolved)\n          }\n        }\n      }\n    }\n  }\n\n  private isKeqModuleClass(route: unknown): route is KeqModuleClass {\n    return (\n      typeof route === 'function'\n      && 'KEQ_REQUEST' in route\n      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'\n    )\n  }\n\n  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {\n    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype\n  }\n\n  private findMiddlewareInstance(\n    middlewareClass: Type<KeqNestMiddleware>,\n    modulesContainer: ModulesContainer,\n  ): KeqNestMiddleware | undefined {\n    for (const [, moduleWrapper] of modulesContainer) {\n      const provider = moduleWrapper.providers.get(middlewareClass)\n      if (provider?.instance) {\n        return provider.instance as KeqNestMiddleware\n      }\n    }\n    return undefined\n  }\n\n  private resolveMiddleware(\n    m: Type<KeqNestMiddleware> | KeqMiddleware,\n    modulesContainer: ModulesContainer,\n  ): KeqMiddleware {\n    if (this.isNestMiddlewareClass(m)) {\n      const instance = this.findMiddlewareInstance(m, modulesContainer)\n      if (!instance) {\n        throw new Error(\n          `[KeqModule] Nest middleware class '${m.name}' is not registered as a provider in any module. `\n          + 'Ensure the middleware class is added to the providers array of a @Module() decorator.',\n        )\n      }\n      return async (ctx, next) => {\n        await instance.use(ctx, next)\n      }\n    }\n    return m\n  }\n\n  /**\n   * 从 ModulesContainer 中查找目标 KeqModule 的 KeqRequest 实例\n   *\n   * 通过 metatype 精确匹配模块，从模块 providers 中直接获取 KeqRequest。\n   * 不依赖 ModuleRef 的作用域机制，直接从 NestJS 全局模块容器中查找。\n   *\n   * @param routeTarget - 目标 KeqModule 类，必须具有 KEQ_REQUEST symbol 属性\n   * @param modulesContainer - NestJS 全局模块容器\n   * @returns KeqRequest 实例，未找到时返回 undefined\n   */\n  private findInModulesContainer(\n    routeTarget: KeqModuleClass,\n    modulesContainer: ModulesContainer,\n  ): KeqRequest | undefined {\n    const token = routeTarget.KEQ_REQUEST\n    for (const [, moduleWrapper] of modulesContainer) {\n      if (moduleWrapper.metatype !== routeTarget) continue\n\n      const provider = moduleWrapper.providers.get(token)\n      if (!provider) continue\n\n      if (provider.instance) {\n        return provider.instance as KeqRequest\n      }\n    }\n    return undefined\n  }\n\n  private buildRoute(info: KeqRouteInfo): KeqRoute {\n    const routes: KeqRoute[] = []\n    if (info.host) {\n      const host = info.host\n      routes.push((ctx) => ctx.request.url.host === host)\n    }\n    if (info.method) {\n      const method = info.method.toLowerCase()\n      routes.push((ctx) => ctx.request.method.toLowerCase() === method)\n    }\n    if (info.pathname) {\n      const isMatch: (test: string) => boolean = picomatch(info.pathname)\n      routes.push((ctx) => isMatch(ctx.request.url.pathname))\n    }\n    if (routes.length === 1) return routes[0]\n    return composeRoute(routes)\n  }\n\n  private wrapWithExclusion(middleware: KeqMiddleware, excludedRoutes: KeqRoute[]): KeqMiddleware {\n    const excluded: KeqMiddleware = async (ctx, next) => {\n      if (await this.checkExcluded(ctx, excludedRoutes)) {\n        return next()\n      }\n      return middleware(ctx, next)\n    }\n    return excluded\n  }\n\n  private async checkExcluded(ctx: KeqExecutionContext, excludedRoutes: KeqRoute[]): Promise<boolean> {\n    for (const route of excludedRoutes) {\n      if (await route(ctx)) return true\n    }\n    return false\n  }\n}\n","import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'\n\n\nexport function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {\n  return (\n    instance !== null\n    && instance !== undefined\n    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'\n  )\n}\n","import { Global, Module, OnModuleInit, Type } from '@nestjs/common'\nimport { ModulesContainer } from '@nestjs/core'\nimport { KeqRequest } from 'keq'\nimport { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'\nimport { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'\n\n/**\n * 全局标记，用于跨 KeqModule 实例去重\n *\n * 当 pnpm 等包管理器因为 peerDependencies 版本差异生成多个\n * `@keq-request/nestjs` 的 `.pnpm` 目录时，Node.js 会将它们视为不同模块，\n * 产生多个 `KeqModule` 类引用，导致 NestJS 创建多个 `KeqModule` 实例。\n *\n * 每个实例的 `onModuleInit()` 都会遍历 `ModulesContainer` 并调用所有\n * 实现了 `configureKeqMiddleware` 的模块。通过 `Symbol.for()`（全局 Symbol\n * 注册表）在 `moduleWrapper.metatype` 上做标记，确保同一个模块类\n * 只被处理一次，无论有多少个 `KeqModule` 实例。\n */\nconst CONFIGURED_SYMBOL = Symbol.for('__keq_middleware_configured__')\n\n/**\n * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块\n * 是否显式导入了 `KeqModule`。\n *\n * NestJS 初始化分为两个严格串行的阶段：\n * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，\n *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set\n * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit\n *\n * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，\n * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。\n *\n * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：\n * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中\n * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败\n */\nexport function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void {\n  // 从 ModulesContainer 中查找 KeqModule 的 metatype，\n  // 解决 pnpm 下 @keq-request/nestjs 存在多个包实例导致 === 引用比对失败的问题\n  let keqModuleMetatype: Type<any> | undefined\n  for (const [, moduleWrapper] of modulesContainer) {\n    if (moduleWrapper.metatype?.name === 'KeqModule') {\n      keqModuleMetatype = moduleWrapper.metatype\n      break\n    }\n  }\n\n  for (const [, moduleWrapper] of modulesContainer) {\n    const metatype = moduleWrapper.metatype\n    if (typeof metatype?.prototype?.configureKeqMiddleware !== 'function') continue\n\n    // 使用运行时 imports Set（NestJS 扫描阶段已解析 DynamicModule 的 imports），\n    // 替代 Reflect.getMetadata('imports', metatype)，解决：\n    // 1. DynamicModule 的 imports 无法通过静态元数据检测\n    // 2. 重复包实例导致的类引用不匹配\n    const hasKeqModule = [...moduleWrapper.imports].some(\n      (importedModule) => importedModule.metatype === keqModuleMetatype,\n    )\n\n    if (!hasKeqModule) {\n      throw new Error(\n        `[KeqModule] '${metatype.name}' implements configureKeqMiddleware() `\n        + 'but does not explicitly import KeqModule. '\n        + 'Add \\'imports: [KeqModule]\\' to its @Module() decorator to ensure '\n        + 'middleware is registered before the module\\'s onModuleInit() runs.',\n      )\n    }\n  }\n}\n\n@Global()\n@Module({\n  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],\n  exports: [KeqRequest],\n})\nexport class KeqModule implements OnModuleInit {\n  constructor(\n    private readonly modulesContainer: ModulesContainer,\n    private readonly keqRequest: KeqRequest,\n  ) {\n    validateConfigureKeqMiddlewareImports(modulesContainer)\n  }\n\n  onModuleInit(): void {\n    for (const [, moduleWrapper] of this.modulesContainer) {\n      const instance = moduleWrapper.instance\n      if (!hasConfigureKeqMiddleware(instance)) continue\n\n      // 跨 KeqModule 实例去重：\n      // moduleWrapper.metatype 是同一个类引用，Symbol.for 是全局共享 key\n      if (moduleWrapper.metatype[CONFIGURED_SYMBOL]) continue\n      moduleWrapper.metatype[CONFIGURED_SYMBOL] = true\n\n      const consumer = new KeqMiddlewareConsumerImpl()\n      instance.configureKeqMiddleware(consumer)\n      consumer.applyTo(this.keqRequest, this.modulesContainer)\n    }\n  }\n}\n"],"mappings":"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"}

package/jest.config.cts

@@ -5,6 +5,16 @@ import { compilerOptions } from './tsconfig.json'
 
 // eslint-disable-next-line @typescript-eslint/require-await
 export default async (): Promise<Config> => ({
-  preset: 'ts-jest',
-  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/src', useESM: true }),
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: {
+        noEmitOnError: false,
+      },
+    }],
+  },
+  testMatch: [
+    '<rootDir>/__tests__/**/*.spec.ts',
+    '<rootDir>/src/**/*.spec.ts',
+  ],
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>', useESM: true }),
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keq-request/nestjs",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.13",
   "description": "Request API write by Typescript for flexibility, readability, and a low learning curve.",
   "keywords": [
     "request",
@@ -39,14 +39,16 @@
   "devDependencies": {
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",
+    "@nestjs/testing": "^11.1.27",
     "@types/node": "^20.19.39",
     "@types/picomatch": "^4.0.0",
-    "keq": "5.0.0-beta.11"
+    "reflect-metadata": "^0.2.2",
+    "keq": "5.0.0-beta.13"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
-    "keq": "^5.0.0-beta.11"
+    "keq": "^5.0.0-beta.13"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/interfaces/keq-middleware-consumer.interface.ts

@@ -10,11 +10,12 @@ export interface KeqRouteInfo {
   pathname?: string
 }
 
-export interface KeqModuleClass {
+export interface KeqModuleClass extends Type<any> {
   readonly KEQ_REQUEST: symbol
 }
 
 export interface KeqMiddlewareConfigProxy {
+  exclude(...routes: KeqRouteInfo[]): KeqMiddlewareConfigProxy
   forRoutes(...routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>): KeqMiddlewareConsumer
 }
 

package/src/keq-middleware-consumer.ts

@@ -1,6 +1,6 @@
 import type { Type } from '@nestjs/common'
-import type { ModuleRef } from '@nestjs/core'
-import type { KeqMiddleware, KeqRoute } from 'keq'
+import type { ModulesContainer } from '@nestjs/core'
+import type { KeqExecutionContext, KeqMiddleware, KeqRoute } from 'keq'
 import { composeRoute, KeqRequest } from 'keq'
 import picomatch from 'picomatch'
 import { KEQ_ROUTES } from './constants.js'
@@ -11,6 +11,7 @@ import type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interfa
 interface MiddlewareEntry {
   middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>
   routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>
+  excludedRouteInfos?: KeqRouteInfo[]
 }
 
 export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
@@ -18,18 +19,34 @@ export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
 
   apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {
     const entry: MiddlewareEntry = { middlewares, routes: [] }
+    const excludedRouteInfos: KeqRouteInfo[] = []
     this.entries.push(entry)
-    return {
+
+    const proxy: KeqMiddlewareConfigProxy = {
+      exclude: (...routes) => {
+        excludedRouteInfos.push(...routes)
+        return proxy
+      },
       forRoutes: (...routes) => {
         entry.routes = routes
+        if (excludedRouteInfos.length > 0) {
+          entry.excludedRouteInfos = excludedRouteInfos
+        }
         return this
       },
     }
+    return proxy
   }
 
-  applyTo(keqRequest: KeqRequest, moduleRef: ModuleRef): void {
+  applyTo(keqRequest: KeqRequest, modulesContainer: ModulesContainer): void {
     for (const entry of this.entries) {
-      const resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, moduleRef))
+      let resolved = entry.middlewares.map((m) => this.resolveMiddleware(m, modulesContainer))
+
+      if (entry.excludedRouteInfos && entry.excludedRouteInfos.length > 0) {
+        const excludedRoutes = entry.excludedRouteInfos.map((info) => this.buildRoute(info))
+        resolved = resolved.map((mw) => this.wrapWithExclusion(mw, excludedRoutes))
+      }
+
       const isGlobal = entry.routes.length === 0
         || entry.routes.some((r) => r === KEQ_ROUTES.ALL)
 
@@ -40,7 +57,7 @@ export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
           if (routeTarget === KEQ_ROUTES.ALL) continue
 
           if (this.isKeqModuleClass(routeTarget)) {
-            const targetRequest = moduleRef.get<KeqRequest>(routeTarget.KEQ_REQUEST, { strict: false })
+            const targetRequest = this.findInModulesContainer(routeTarget, modulesContainer)
             if (targetRequest) {
               for (const mw of resolved) targetRequest.use(mw)
             }
@@ -65,9 +82,31 @@ export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
     return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype
   }
 
-  private resolveMiddleware(m: Type<KeqNestMiddleware> | KeqMiddleware, moduleRef: ModuleRef): KeqMiddleware {
+  private findMiddlewareInstance(
+    middlewareClass: Type<KeqNestMiddleware>,
+    modulesContainer: ModulesContainer,
+  ): KeqNestMiddleware | undefined {
+    for (const [, moduleWrapper] of modulesContainer) {
+      const provider = moduleWrapper.providers.get(middlewareClass)
+      if (provider?.instance) {
+        return provider.instance as KeqNestMiddleware
+      }
+    }
+    return undefined
+  }
+
+  private resolveMiddleware(
+    m: Type<KeqNestMiddleware> | KeqMiddleware,
+    modulesContainer: ModulesContainer,
+  ): KeqMiddleware {
     if (this.isNestMiddlewareClass(m)) {
-      const instance = moduleRef.get<KeqNestMiddleware>(m, { strict: false })
+      const instance = this.findMiddlewareInstance(m, modulesContainer)
+      if (!instance) {
+        throw new Error(
+          `[KeqModule] Nest middleware class '${m.name}' is not registered as a provider in any module. `
+          + 'Ensure the middleware class is added to the providers array of a @Module() decorator.',
+        )
+      }
       return async (ctx, next) => {
         await instance.use(ctx, next)
       }
@@ -75,6 +114,34 @@ export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
     return m
   }
 
+  /**
+   * 从 ModulesContainer 中查找目标 KeqModule 的 KeqRequest 实例
+   *
+   * 通过 metatype 精确匹配模块，从模块 providers 中直接获取 KeqRequest。
+   * 不依赖 ModuleRef 的作用域机制，直接从 NestJS 全局模块容器中查找。
+   *
+   * @param routeTarget - 目标 KeqModule 类，必须具有 KEQ_REQUEST symbol 属性
+   * @param modulesContainer - NestJS 全局模块容器
+   * @returns KeqRequest 实例，未找到时返回 undefined
+   */
+  private findInModulesContainer(
+    routeTarget: KeqModuleClass,
+    modulesContainer: ModulesContainer,
+  ): KeqRequest | undefined {
+    const token = routeTarget.KEQ_REQUEST
+    for (const [, moduleWrapper] of modulesContainer) {
+      if (moduleWrapper.metatype !== routeTarget) continue
+
+      const provider = moduleWrapper.providers.get(token)
+      if (!provider) continue
+
+      if (provider.instance) {
+        return provider.instance as KeqRequest
+      }
+    }
+    return undefined
+  }
+
   private buildRoute(info: KeqRouteInfo): KeqRoute {
     const routes: KeqRoute[] = []
     if (info.host) {
@@ -92,4 +159,21 @@ export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
     if (routes.length === 1) return routes[0]
     return composeRoute(routes)
   }
+
+  private wrapWithExclusion(middleware: KeqMiddleware, excludedRoutes: KeqRoute[]): KeqMiddleware {
+    const excluded: KeqMiddleware = async (ctx, next) => {
+      if (await this.checkExcluded(ctx, excludedRoutes)) {
+        return next()
+      }
+      return middleware(ctx, next)
+    }
+    return excluded
+  }
+
+  private async checkExcluded(ctx: KeqExecutionContext, excludedRoutes: KeqRoute[]): Promise<boolean> {
+    for (const route of excludedRoutes) {
+      if (await route(ctx)) return true
+    }
+    return false
+  }
 }

package/src/keq.module.ts

@@ -1,9 +1,72 @@
-import { Global, Module, OnModuleInit } from '@nestjs/common'
-import { ModulesContainer, ModuleRef } from '@nestjs/core'
+import { Global, Module, OnModuleInit, Type } from '@nestjs/common'
+import { ModulesContainer } from '@nestjs/core'
 import { KeqRequest } from 'keq'
 import { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'
 import { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'
 
+/**
+ * 全局标记，用于跨 KeqModule 实例去重
+ *
+ * 当 pnpm 等包管理器因为 peerDependencies 版本差异生成多个
+ * `@keq-request/nestjs` 的 `.pnpm` 目录时，Node.js 会将它们视为不同模块，
+ * 产生多个 `KeqModule` 类引用，导致 NestJS 创建多个 `KeqModule` 实例。
+ *
+ * 每个实例的 `onModuleInit()` 都会遍历 `ModulesContainer` 并调用所有
+ * 实现了 `configureKeqMiddleware` 的模块。通过 `Symbol.for()`（全局 Symbol
+ * 注册表）在 `moduleWrapper.metatype` 上做标记，确保同一个模块类
+ * 只被处理一次，无论有多少个 `KeqModule` 实例。
+ */
+const CONFIGURED_SYMBOL = Symbol.for('__keq_middleware_configured__')
+
+/**
+ * 在 NestJS 模块初始化早期阶段校验 `configureKeqMiddleware` 的实现模块
+ * 是否显式导入了 `KeqModule`。
+ *
+ * NestJS 初始化分为两个严格串行的阶段：
+ * 1. 全量扫描 — 所有模块 wrapper 加入 ModulesContainer，metatype 已设置，
+ *    DynamicModule 的 imports 已被解析并写入 moduleWrapper.imports Set
+ * 2. 实例创建 — 按依赖顺序调用构造函数 → onModuleInit
+ *
+ * 此校验在阶段 2 开头（构造函数中）执行，早于所有 onModuleInit，
+ * 确保中间件缺失问题在启动期就被捕获，而非在业务模块 onModuleInit 发请求时静默失效。
+ *
+ * 使用运行时 imports Set 而非 Reflect.getMetadata('imports', metatype) 的原因：
+ * - DynamicModule 通过 register() 返回的 imports 不在静态装饰器元数据中
+ * - 从 ModulesContainer 获取 KeqModule metatype 可避免 pnpm 重复包实例导致的 === 比对失败
+ */
+export function validateConfigureKeqMiddlewareImports(modulesContainer: ModulesContainer): void {
+  // 从 ModulesContainer 中查找 KeqModule 的 metatype，
+  // 解决 pnpm 下 @keq-request/nestjs 存在多个包实例导致 === 引用比对失败的问题
+  let keqModuleMetatype: Type<any> | undefined
+  for (const [, moduleWrapper] of modulesContainer) {
+    if (moduleWrapper.metatype?.name === 'KeqModule') {
+      keqModuleMetatype = moduleWrapper.metatype
+      break
+    }
+  }
+
+  for (const [, moduleWrapper] of modulesContainer) {
+    const metatype = moduleWrapper.metatype
+    if (typeof metatype?.prototype?.configureKeqMiddleware !== 'function') continue
+
+    // 使用运行时 imports Set（NestJS 扫描阶段已解析 DynamicModule 的 imports），
+    // 替代 Reflect.getMetadata('imports', metatype)，解决：
+    // 1. DynamicModule 的 imports 无法通过静态元数据检测
+    // 2. 重复包实例导致的类引用不匹配
+    const hasKeqModule = [...moduleWrapper.imports].some(
+      (importedModule) => importedModule.metatype === keqModuleMetatype,
+    )
+
+    if (!hasKeqModule) {
+      throw new Error(
+        `[KeqModule] '${metatype.name}' implements configureKeqMiddleware() `
+        + 'but does not explicitly import KeqModule. '
+        + 'Add \'imports: [KeqModule]\' to its @Module() decorator to ensure '
+        + 'middleware is registered before the module\'s onModuleInit() runs.',
+      )
+    }
+  }
+}
 
 @Global()
 @Module({
@@ -13,18 +76,24 @@ import { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.
 export class KeqModule implements OnModuleInit {
   constructor(
     private readonly modulesContainer: ModulesContainer,
-    private readonly moduleRef: ModuleRef,
     private readonly keqRequest: KeqRequest,
-  ) {}
+  ) {
+    validateConfigureKeqMiddlewareImports(modulesContainer)
+  }
 
   onModuleInit(): void {
     for (const [, moduleWrapper] of this.modulesContainer) {
       const instance = moduleWrapper.instance
-      if (hasConfigureKeqMiddleware(instance)) {
-        const consumer = new KeqMiddlewareConsumerImpl()
-        instance.configureKeqMiddleware(consumer)
-        consumer.applyTo(this.keqRequest, this.moduleRef)
-      }
+      if (!hasConfigureKeqMiddleware(instance)) continue
+
+      // 跨 KeqModule 实例去重：
+      // moduleWrapper.metatype 是同一个类引用，Symbol.for 是全局共享 key
+      if (moduleWrapper.metatype[CONFIGURED_SYMBOL]) continue
+      moduleWrapper.metatype[CONFIGURED_SYMBOL] = true
+
+      const consumer = new KeqMiddlewareConsumerImpl()
+      instance.configureKeqMiddleware(consumer)
+      consumer.applyTo(this.keqRequest, this.modulesContainer)
     }
   }
 }