@dangao/bun-server 1.6.0 → 1.7.1

package/src/cache/interceptors.ts

@@ -0,0 +1,295 @@
+import 'reflect-metadata';
+import { BaseInterceptor } from '../interceptor/base-interceptor';
+import type { Container } from '../di/container';
+import type { Context } from '../core/context';
+import type { CacheService } from './service';
+import { CACHE_SERVICE_TOKEN } from './types';
+import {
+  getCacheableMetadata,
+  getCacheEvictMetadata,
+  getCachePutMetadata,
+  type CacheableMetadata,
+  type CacheEvictMetadata,
+  type CachePutMetadata,
+} from './decorators';
+
+/**
+ * 缓存装饰器元数据键（用于拦截器注册）
+ */
+export const CACHEABLE_INTERCEPTOR_KEY = Symbol('@dangao/bun-server:cache:cacheable');
+export const CACHE_EVICT_INTERCEPTOR_KEY = Symbol('@dangao/bun-server:cache:cache-evict');
+export const CACHE_PUT_INTERCEPTOR_KEY = Symbol('@dangao/bun-server:cache:cache-put');
+
+/**
+ * 解析缓存键中的参数占位符
+ * 支持 SpEL 风格的表达式，如 'user:{id}' 或 'user:{0}'
+ * @param keyTemplate - 键模板
+ * @param args - 方法参数
+ * @param paramNames - 参数名称（如果可用）
+ * @returns 解析后的缓存键
+ */
+function resolveKeyTemplate(
+  keyTemplate: string,
+  args: unknown[],
+  paramNames?: string[],
+): string {
+  let result = keyTemplate;
+
+  // 替换数字索引占位符，如 {0}, {1}
+  result = result.replace(/\{(\d+)\}/g, (_, index) => {
+    const i = parseInt(index, 10);
+    if (i < args.length) {
+      return String(args[i]);
+    }
+    return `{${index}}`;
+  });
+
+  // 替换命名参数占位符，如 {id}, {name}
+  if (paramNames) {
+    for (let i = 0; i < paramNames.length; i++) {
+      const name = paramNames[i];
+      const regex = new RegExp(`\\{${name}\\}`, 'g');
+      result = result.replace(regex, String(args[i]));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 生成默认缓存键
+ * @param target - 目标对象
+ * @param propertyKey - 方法名
+ * @param args - 方法参数
+ * @param keyPrefix - 键前缀
+ * @returns 缓存键
+ */
+function generateDefaultCacheKey(
+  target: unknown,
+  propertyKey: string | symbol,
+  args: unknown[],
+  keyPrefix?: string,
+): string {
+  const className = typeof target === 'object' && target !== null
+    ? (target as { constructor?: { name?: string } }).constructor?.name || 'Unknown'
+    : 'Unknown';
+  const methodName = String(propertyKey);
+  const argsKey = args.length > 0 ? ':' + JSON.stringify(args) : '';
+  const prefix = keyPrefix ? `${keyPrefix}:` : '';
+
+  return `${prefix}${className}:${methodName}${argsKey}`;
+}
+
+/**
+ * @Cacheable 拦截器
+ * 实现方法结果缓存功能
+ */
+export class CacheableInterceptor extends BaseInterceptor {
+  /**
+   * 执行拦截器逻辑
+   */
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 从原型方法获取元数据（元数据存储在原型上，而不是绑定后的函数上）
+    // 当通过代理调用时，originalMethod 可能是 .bind() 后的函数，没有元数据
+    // 所以我们需要从 target 的原型上获取原始方法来读取元数据
+    let metadata = getCacheableMetadata(originalMethod);
+
+    if (!metadata && target && typeof target === 'object') {
+      const prototype = Object.getPrototypeOf(target);
+      if (prototype && typeof propertyKey === 'string') {
+        const protoMethod = prototype[propertyKey];
+        if (protoMethod) {
+          metadata = getCacheableMetadata(protoMethod);
+        }
+      }
+    }
+
+    if (!metadata) {
+      // 没有缓存元数据，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 获取缓存服务
+    let cacheService: CacheService;
+    try {
+      cacheService = container.resolve<CacheService>(CACHE_SERVICE_TOKEN);
+    } catch {
+      // 缓存服务未注册，直接执行原方法
+      console.warn('[CacheableInterceptor] CacheService not registered, skipping cache');
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 生成缓存键
+    const cacheKey = metadata.key
+      ? resolveKeyTemplate(metadata.key, args)
+      : generateDefaultCacheKey(target, propertyKey, args, metadata.keyPrefix);
+
+    // 检查条件表达式（如果有）
+    if (metadata.condition) {
+      // 简单的条件评估：目前只支持 'true'/'false' 字符串
+      // 未来可以扩展为完整的表达式求值
+      if (metadata.condition === 'false') {
+        return await Promise.resolve(originalMethod.apply(target, args));
+      }
+    }
+
+    // 使用 getOrSet 实现缓存逻辑
+    const result = await cacheService.getOrSet<T>(
+      cacheKey,
+      async () => {
+        return await Promise.resolve(originalMethod.apply(target, args));
+      },
+      metadata.ttl,
+    );
+
+    return result;
+  }
+}
+
+/**
+ * @CacheEvict 拦截器
+ * 实现缓存清除功能
+ */
+export class CacheEvictInterceptor extends BaseInterceptor {
+  /**
+   * 执行拦截器逻辑
+   */
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 从原型方法获取元数据
+    let metadata = getCacheEvictMetadata(originalMethod);
+
+    if (!metadata && target && typeof target === 'object') {
+      const prototype = Object.getPrototypeOf(target);
+      if (prototype && typeof propertyKey === 'string') {
+        const protoMethod = prototype[propertyKey];
+        if (protoMethod) {
+          metadata = getCacheEvictMetadata(protoMethod);
+        }
+      }
+    }
+
+    if (!metadata) {
+      // 没有缓存清除元数据，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 获取缓存服务
+    let cacheService: CacheService;
+    try {
+      cacheService = container.resolve<CacheService>(CACHE_SERVICE_TOKEN);
+    } catch {
+      // 缓存服务未注册，直接执行原方法
+      console.warn('[CacheEvictInterceptor] CacheService not registered, skipping cache eviction');
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 生成缓存键
+    const cacheKey = metadata.key
+      ? resolveKeyTemplate(metadata.key, args)
+      : generateDefaultCacheKey(target, propertyKey, args, metadata.keyPrefix);
+
+    // 如果配置了在方法执行前清除缓存
+    if (metadata.beforeInvocation) {
+      if (metadata.allEntries) {
+        await cacheService.clear();
+      } else {
+        await cacheService.delete(cacheKey);
+      }
+    }
+
+    // 执行原方法
+    const result = await Promise.resolve(originalMethod.apply(target, args));
+
+    // 如果配置了在方法执行后清除缓存（默认行为）
+    if (!metadata.beforeInvocation) {
+      if (metadata.allEntries) {
+        await cacheService.clear();
+      } else {
+        await cacheService.delete(cacheKey);
+      }
+    }
+
+    return result;
+  }
+}
+
+/**
+ * @CachePut 拦截器
+ * 实现缓存更新功能（总是执行方法并更新缓存）
+ */
+export class CachePutInterceptor extends BaseInterceptor {
+  /**
+   * 执行拦截器逻辑
+   */
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 从原型方法获取元数据
+    let metadata = getCachePutMetadata(originalMethod);
+
+    if (!metadata && target && typeof target === 'object') {
+      const prototype = Object.getPrototypeOf(target);
+      if (prototype && typeof propertyKey === 'string') {
+        const protoMethod = prototype[propertyKey];
+        if (protoMethod) {
+          metadata = getCachePutMetadata(protoMethod);
+        }
+      }
+    }
+
+    if (!metadata) {
+      // 没有缓存更新元数据，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 获取缓存服务
+    let cacheService: CacheService;
+    try {
+      cacheService = container.resolve<CacheService>(CACHE_SERVICE_TOKEN);
+    } catch {
+      // 缓存服务未注册，直接执行原方法
+      console.warn('[CachePutInterceptor] CacheService not registered, skipping cache update');
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 执行原方法
+    const result = await Promise.resolve(originalMethod.apply(target, args));
+
+    // 检查条件表达式（如果有）
+    if (metadata.condition) {
+      // 简单的条件评估
+      if (metadata.condition === 'false') {
+        return result;
+      }
+    }
+
+    // 生成缓存键
+    const cacheKey = metadata.key
+      ? resolveKeyTemplate(metadata.key, args)
+      : generateDefaultCacheKey(target, propertyKey, args, metadata.keyPrefix);
+
+    // 更新缓存
+    await cacheService.set(cacheKey, result, metadata.ttl);
+
+    return result;
+  }
+}

package/src/cache/service-proxy.ts

@@ -0,0 +1,219 @@
+import 'reflect-metadata';
+import type { Container } from '../di/container';
+import type { InstancePostProcessor } from '../di/types';
+import type { Constructor } from '../core/types';
+import {
+  getCacheableMetadata,
+  getCacheEvictMetadata,
+  getCachePutMetadata,
+} from './decorators';
+import {
+  CacheableInterceptor,
+  CacheEvictInterceptor,
+  CachePutInterceptor,
+} from './interceptors';
+
+/**
+ * 缓存服务代理工厂
+ * 为服务实例创建代理，拦截带有缓存装饰器的方法
+ */
+export class CacheServiceProxy {
+  private static cacheableInterceptor = new CacheableInterceptor();
+  private static cacheEvictInterceptor = new CacheEvictInterceptor();
+  private static cachePutInterceptor = new CachePutInterceptor();
+
+  /**
+   * 为服务实例创建缓存代理
+   * @param instance - 原始服务实例
+   * @param container - DI 容器
+   * @returns 代理实例
+   */
+  public static createProxy<T extends object>(
+    instance: T,
+    container: Container,
+  ): T {
+    const prototype = Object.getPrototypeOf(instance);
+    const methodNames = Object.getOwnPropertyNames(prototype).filter(
+      (name) => name !== 'constructor' && typeof prototype[name] === 'function',
+    );
+
+    // 检查是否有任何需要缓存处理的方法
+    // 从原型获取方法（元数据存储在原型的方法上）
+    let hasAnyMetadata = false;
+    for (const methodName of methodNames) {
+      const prototypeMethod = prototype[methodName];
+      const cacheable = getCacheableMetadata(prototypeMethod);
+      const cacheEvict = getCacheEvictMetadata(prototypeMethod);
+      const cachePut = getCachePutMetadata(prototypeMethod);
+
+      if (cacheable || cacheEvict || cachePut) {
+        hasAnyMetadata = true;
+        break;
+      }
+    }
+
+    // 如果没有缓存装饰器，直接返回原实例
+    if (!hasAnyMetadata) {
+      return instance;
+    }
+
+    // 创建代理
+    return new Proxy(instance, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+
+        // 只处理函数
+        if (typeof value !== 'function' || typeof prop === 'symbol') {
+          return value;
+        }
+
+        const methodName = prop as string;
+
+        // 从原型获取方法以检查元数据（元数据存储在原型的方法上）
+        const prototypeMethod = prototype[methodName];
+        if (!prototypeMethod) {
+          return value;
+        }
+
+        // 检查缓存装饰器（从原型方法获取元数据）
+        const cacheableMetadata = getCacheableMetadata(prototypeMethod);
+        const cacheEvictMetadata = getCacheEvictMetadata(prototypeMethod);
+        const cachePutMetadata = getCachePutMetadata(prototypeMethod);
+
+        // 如果没有缓存装饰器，返回原方法
+        if (!cacheableMetadata && !cacheEvictMetadata && !cachePutMetadata) {
+          return value;
+        }
+
+        // 返回包装后的方法
+        // 使用原型方法以确保拦截器能获取到正确的元数据
+        const originalMethod = prototypeMethod as (...args: unknown[]) => unknown;
+
+        return async function (this: T, ...args: unknown[]): Promise<unknown> {
+          // 按优先级执行拦截器：CacheEvict (beforeInvocation) -> Cacheable/CachePut -> CacheEvict (afterInvocation)
+
+          // 如果有 @CacheEvict 且配置了 beforeInvocation
+          if (cacheEvictMetadata?.beforeInvocation) {
+            await CacheServiceProxy.cacheEvictInterceptor.execute(
+              target,
+              methodName,
+              originalMethod.bind(target),
+              args,
+              container,
+            );
+            // beforeInvocation 只清除缓存，继续执行
+          }
+
+          let result: unknown;
+
+          // 如果有 @Cacheable，使用缓存逻辑
+          if (cacheableMetadata) {
+            result = await CacheServiceProxy.cacheableInterceptor.execute(
+              target,
+              methodName,
+              originalMethod.bind(target),
+              args,
+              container,
+            );
+          } else if (cachePutMetadata) {
+            // 如果有 @CachePut，执行并更新缓存
+            result = await CacheServiceProxy.cachePutInterceptor.execute(
+              target,
+              methodName,
+              originalMethod.bind(target),
+              args,
+              container,
+            );
+          } else {
+            // 只有 @CacheEvict，正常执行方法
+            result = await originalMethod.apply(target, args);
+          }
+
+          // 如果有 @CacheEvict 且未配置 beforeInvocation（默认行为）
+          if (cacheEvictMetadata && !cacheEvictMetadata.beforeInvocation) {
+            // 执行缓存清除逻辑（方法已执行，只需清除缓存）
+            await CacheServiceProxy.cacheEvictInterceptor.execute(
+              target,
+              methodName,
+              async () => result, // 返回已有结果，不再执行方法
+              args,
+              container,
+            );
+          }
+
+          return result;
+        };
+      },
+    });
+  }
+}
+
+/**
+ * 元数据键：标记服务需要缓存代理
+ */
+export const CACHE_PROXY_ENABLED_KEY = Symbol('@dangao/bun-server:cache:proxy-enabled');
+
+/**
+ * 启用服务缓存代理的装饰器
+ * 用于标记服务类需要缓存代理支持
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * @EnableCacheProxy()
+ * class UserService {
+ *   @Cacheable({ key: 'user:{0}', ttl: 60000 })
+ *   async findById(id: string) {
+ *     return await this.db.findUser(id);
+ *   }
+ * }
+ * ```
+ */
+export function EnableCacheProxy(): ClassDecorator {
+  return function (target: Function): void {
+    Reflect.defineMetadata(CACHE_PROXY_ENABLED_KEY, true, target);
+  };
+}
+
+/**
+ * 检查类是否启用了缓存代理
+ * @param target - 目标类
+ * @returns 是否启用
+ */
+export function isCacheProxyEnabled(target: Function): boolean {
+  return Reflect.getMetadata(CACHE_PROXY_ENABLED_KEY, target) === true;
+}
+
+/**
+ * 缓存实例后处理器
+ * 自动为带有 @EnableCacheProxy() 装饰器的服务创建缓存代理
+ */
+export class CachePostProcessor implements InstancePostProcessor {
+  /**
+   * 优先级（较低以确保在其他处理器之后运行）
+   */
+  public priority = 50;
+
+  /**
+   * 处理新创建的实例
+   */
+  public postProcess<T>(
+    instance: T,
+    constructor: Constructor<T>,
+    container: unknown,
+  ): T {
+    // 检查是否启用了缓存代理
+    const proxyEnabled = isCacheProxyEnabled(constructor);
+    if (!proxyEnabled) {
+      return instance;
+    }
+
+    // 创建缓存代理
+    const proxied = CacheServiceProxy.createProxy(
+      instance as object,
+      container as Container,
+    ) as T;
+
+    return proxied;
+  }
+}

package/src/controller/controller.ts

@@ -234,19 +234,43 @@ export class ControllerRegistry {
    * @param basePath - 基础路径
    * @param methodPath - 方法路径
    * @returns 组合后的路径
+   *
+   * 路径规范化规则：
+   * - [/ + /api/base] -> /api/base
+   * - [// + /api/base] -> /api/base
+   * - [/api + /base] -> /api/base
+   * - [/api/ + base] -> /api/base
+   * - [/api/base + ""] -> /api/base
+   * - [/api/base + /] -> /api/base
    */
   private combinePaths(basePath: string, methodPath: string): string {
-    // 规范化路径：确保 basePath 以 / 开头，不以 / 结尾
-    const base = basePath.replace(/\/$/, '').replace(/^\/?/, '/');
-    // methodPath 移除前导斜杠
-    const method = methodPath.replace(/^\//, '');
+    // 规范化 basePath：
+    // 1. 移除所有末尾斜杠
+    // 2. 确保以单个 / 开头
+    // 3. 合并多个连续斜杠为单个斜杠
+    let base = basePath
+      .replace(/\/+$/, '')    // 移除末尾所有斜杠
+      .replace(/^\/+/, '/')   // 确保开头只有一个斜杠
+      .replace(/\/+/g, '/');  // 合并多个连续斜杠
+
+    // 如果 base 为空，设为 /
+    if (!base) {
+      base = '/';
+    }
+
+    // 规范化 methodPath：移除前导斜杠
+    const method = methodPath.replace(/^\/+/, '');
 
     if (!method) {
       // 如果方法路径为空，返回基础路径
       return base === '/' ? '/' : base;
     }
-    
-    // 组合路径
+
+    // 组合路径：如果 base 是 '/'，直接返回 '/' + method，避免 '//method'
+    if (base === '/') {
+      return '/' + method;
+    }
+
     return base + '/' + method;
   }
 

package/src/core/application.ts

@@ -16,6 +16,7 @@ import { InterceptorRegistry, INTERCEPTOR_REGISTRY_TOKEN } from '../interceptor'
 import { CONFIG_SERVICE_TOKEN } from '../config/types';
 import { ConfigService } from '../config/service';
 import { ConfigModule } from '../config/config-module';
+import { CacheModule, CACHE_POST_PROCESSOR_TOKEN } from '../cache';
 import { LoggerManager } from '@dangao/logsmith';
 
 /**
@@ -285,7 +286,8 @@ export class Application {
    */
   public registerModule(moduleClass: ModuleClass): void {
     const registry = ModuleRegistry.getInstance();
-    registry.register(moduleClass, this.getContainer());
+    const container = this.getContainer();
+    registry.register(moduleClass, container);
     
     // 注册模块的扩展和中间件
     const extensions = registry.getModuleExtensions(moduleClass);
@@ -297,6 +299,28 @@ export class Application {
     for (const middleware of middlewares) {
       this.use(middleware);
     }
+
+    // 检测并注册缓存后处理器
+    // CacheModule.getPostProcessor() 会在 forRoot() 被调用后返回后处理器
+    this.registerCachePostProcessorIfNeeded(container);
+  }
+
+  /**
+   * 检测并注册缓存后处理器
+   * @param container - DI 容器
+   */
+  private registerCachePostProcessorIfNeeded(container: ReturnType<typeof this.getContainer>): void {
+    // 直接从 CacheModule 获取后处理器
+    // 如果 CacheModule.forRoot() 被调用过，后处理器就会存在
+    const postProcessor = CacheModule.getPostProcessor();
+    if (postProcessor) {
+      // 检查是否已经注册过（避免重复注册）
+      // @ts-expect-error - 访问私有属性
+      const existingProcessors = container.postProcessors as unknown[];
+      if (!existingProcessors.includes(postProcessor)) {
+        container.registerPostProcessor(postProcessor);
+      }
+    }
   }
 
   /**

package/src/core/server.ts

@@ -86,6 +86,7 @@ export class BunServer {
           upgradeHeader.toLowerCase() === "websocket"
         ) {
           const url = new URL(request.url);
+          // 检查是否有匹配的网关（支持动态路径匹配）
           if (!this.options.websocketRegistry.hasGateway(url.pathname)) {
             return new Response("WebSocket gateway not found", { status: 404 });
           }