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

package/src/keq-middleware-consumer.ts

@@ -1,179 +1,33 @@
-import type { Type } from '@nestjs/common'
-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'
-import type { KeqMiddlewareConfigProxy, KeqMiddlewareConsumer, KeqModuleClass, KeqRouteInfo } from './interfaces/keq-middleware-consumer.interface.js'
+import { Injectable } from '@nestjs/common'
+import type { KeqMiddleware } from 'keq'
+import { KeqRequest } from 'keq'
+import type { KeqMiddlewareConfigProxy } from './interfaces/keq-middleware-consumer.interface.js'
 import type { KeqNestMiddleware } from './interfaces/keq-nest-middleware.interface.js'
-
-
-interface MiddlewareEntry {
-  middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>
-  routes: Array<typeof KEQ_ROUTES.ALL | KeqRouteInfo | KeqModuleClass>
-  excludedRouteInfos?: KeqRouteInfo[]
-}
-
-export class KeqMiddlewareConsumerImpl implements KeqMiddlewareConsumer {
-  private entries: MiddlewareEntry[] = []
-
-  apply(...middlewares: Array<Type<KeqNestMiddleware> | KeqMiddleware>): KeqMiddlewareConfigProxy {
-    const entry: MiddlewareEntry = { middlewares, routes: [] }
-    const excludedRouteInfos: KeqRouteInfo[] = []
-    this.entries.push(entry)
-
-    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, modulesContainer: ModulesContainer): void {
-    for (const entry of this.entries) {
-      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)
-
-      if (isGlobal) {
-        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 = this.findInModulesContainer(routeTarget, modulesContainer)
-            if (targetRequest) {
-              for (const mw of resolved) targetRequest.use(mw)
-            }
-          } else {
-            const route = this.buildRoute(routeTarget as KeqRouteInfo)
-            keqRequest.useRouter().route(route, resolved)
-          }
-        }
-      }
-    }
-  }
-
-  private isKeqModuleClass(route: unknown): route is KeqModuleClass {
-    return (
-      typeof route === 'function'
-      && 'KEQ_REQUEST' in route
-      && typeof (route as Record<string, unknown>).KEQ_REQUEST === 'symbol'
-    )
-  }
-
-  private isNestMiddlewareClass(m: Type<KeqNestMiddleware> | KeqMiddleware): m is Type<KeqNestMiddleware> {
-    return typeof m === 'function' && m.prototype !== undefined && 'use' in m.prototype
-  }
-
-  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 = 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
-   */
-  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) {
-      const host = info.host
-      routes.push((ctx) => ctx.request.url.host === host)
-    }
-    if (info.method) {
-      const method = info.method.toLowerCase()
-      routes.push((ctx) => ctx.request.method.toLowerCase() === method)
-    }
-    if (info.pathname) {
-      const isMatch: (test: string) => boolean = picomatch(info.pathname)
-      routes.push((ctx) => isMatch(ctx.request.url.pathname))
-    }
-    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
+import { KeqMiddlewareCollector } from './keq-middleware-collector.js'
+
+
+/**
+ * 全局中间件消费者，提供 `.apply().forRoutes()` API。
+ *
+ * `forRoutes()` 返回 `KeqMiddlewareConsumer` 自身，支持链式注册：
+ *
+ * ```ts
+ * consumer
+ *   .apply(mw1).forRoutes(KEQ_ROUTES.ALL)
+ *   .apply(mw2).forRoutes({ pathname: '/api/*' })
+ * ```
+ *
+ * 模块级别的中间件请使用 `@InjectKeqConsumer(GeneratedModule)` 注入
+ * `KeqConsumer<GeneratedModule>`，其 `forRoutes()` 直接作用于目标模块。
+ */
+@Injectable()
+export class KeqMiddlewareConsumer {
+  constructor(private readonly keqRequest: KeqRequest) {}
+
+  apply(
+    ...middlewares: Array<KeqNestMiddleware | KeqMiddleware>
+  ): KeqMiddlewareConfigProxy {
+    const collector = new KeqMiddlewareCollector(this.keqRequest, this)
+    return collector.apply(middlewares)
   }
 }

package/src/keq.module.ts

@@ -1,99 +1,14 @@
-import { Global, Module, OnModuleInit, Type } from '@nestjs/common'
-import { ModulesContainer } from '@nestjs/core'
+import { Global, Module } from '@nestjs/common'
 import { KeqRequest } from 'keq'
-import { KeqMiddlewareConsumerImpl } from './keq-middleware-consumer.js'
-import { hasConfigureKeqMiddleware } from './utils/has-configure-keq-middleware.js'
+import { KeqMiddlewareConsumer } from './keq-middleware-consumer.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({
-  providers: [{ provide: KeqRequest, useFactory: () => new KeqRequest() }],
-  exports: [KeqRequest],
+  providers: [
+    { provide: KeqRequest, useFactory: () => new KeqRequest() },
+    KeqMiddlewareConsumer,
+  ],
+  exports: [KeqRequest, KeqMiddlewareConsumer],
 })
-export class KeqModule implements OnModuleInit {
-  constructor(
-    private readonly modulesContainer: ModulesContainer,
-    private readonly keqRequest: KeqRequest,
-  ) {
-    validateConfigureKeqMiddlewareImports(modulesContainer)
-  }
-
-  onModuleInit(): void {
-    for (const [, moduleWrapper] of this.modulesContainer) {
-      const instance = moduleWrapper.instance
-      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)
-    }
-  }
-}
+export class KeqModule {}

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

@@ -1,6 +0,0 @@
-import type { KeqMiddlewareConsumer } from './keq-middleware-consumer.interface.js'
-
-
-export interface KeqMiddlewareModule {
-  configureKeqMiddleware(consumer: KeqMiddlewareConsumer): void
-}

package/src/utils/has-configure-keq-middleware.ts

@@ -1,10 +0,0 @@
-import type { KeqMiddlewareModule } from '../interfaces/keq-middleware-module.interface.js'
-
-
-export function hasConfigureKeqMiddleware(instance: unknown): instance is KeqMiddlewareModule {
-  return (
-    instance !== null
-    && instance !== undefined
-    && typeof (instance as Record<string, unknown>).configureKeqMiddleware === 'function'
-  )
-}