create-pardx-scaffold 0.1.0

package/template/apps/api/libs/infra/common/decorators/feature-flag/feature-flag.decorator.ts

@@ -0,0 +1,221 @@
+/**
+ * Feature Flag Decorators
+ *
+ * 提供功能开关装饰器，支持 Unleash 集成或自定义实现。
+ *
+ * 支持的策略:
+ * - 布尔值: 简单开关
+ * - 用户 ID: 基于用户的灰度
+ * - 百分比: 按比例开放
+ * - 环境: 基于运行环境
+ * - 自定义: 自定义评估策略
+ *
+ * @example
+ * ```typescript
+ * // 简单功能开关
+ * @FeatureEnabled('new-dashboard')
+ * @Get('dashboard')
+ * async getDashboard() { ... }
+ *
+ * // 条件开关 - 抛出 NotImplementedException
+ * @FeatureEnabled('beta-feature', { throwIfDisabled: true })
+ * async betaFeature() { ... }
+ *
+ * // 灰度发布 - 基于用户
+ * @FeatureEnabled('premium-feature', { userIdParam: 'userId' })
+ * async premiumFeature(@Param('userId') userId: string) { ... }
+ * ```
+ */
+
+import { SetMetadata } from '@nestjs/common';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const FEATURE_FLAG_METADATA_KEY = 'feature:flag';
+export const FEATURE_FLAGS_METADATA_KEY = 'feature:flags';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * 功能开关策略类型
+ */
+export type FeatureFlagStrategy =
+  | 'boolean'
+  | 'userId'
+  | 'percentage'
+  | 'environment'
+  | 'custom';
+
+/**
+ * 功能开关配置选项
+ */
+export interface FeatureFlagOptions {
+  /** 功能标识 */
+  flagName: string;
+
+  /** 策略类型，默认 'boolean' */
+  strategy?: FeatureFlagStrategy;
+
+  /**
+   * 功能关闭时是否抛出异常
+   * 默认: false (跳过执行，返回 null)
+   */
+  throwIfDisabled?: boolean;
+
+  /**
+   * 自定义错误消息
+   */
+  errorMessage?: string;
+
+  /**
+   * 用户 ID 参数名 (用于 userId 策略)
+   */
+  userIdParam?: string;
+
+  /**
+   * 开放百分比 (用于 percentage 策略，0-100)
+   */
+  percentage?: number;
+
+  /**
+   * 允许的环境列表 (用于 environment 策略)
+   */
+  environments?: string[];
+
+  /**
+   * 自定义评估函数 (用于 custom 策略)
+   */
+  customEvaluator?: (context: any) => boolean | Promise<boolean>;
+}
+
+/**
+ * 功能开关上下文
+ */
+export interface FeatureFlagContext {
+  /** 用户 ID */
+  userId?: string;
+  /** 当前环境 */
+  environment?: string;
+  /** 请求信息 */
+  request?: any;
+  /** 额外属性 */
+  properties?: Record<string, any>;
+}
+
+// ============================================================================
+// Decorators
+// ============================================================================
+
+/**
+ * @FeatureEnabled - 功能开关装饰器
+ *
+ * 根据功能开关状态决定是否执行方法。
+ *
+ * @param flagName - 功能标识
+ * @param options - 配置选项
+ *
+ * @example
+ * ```typescript
+ * // 简单开关
+ * @FeatureEnabled('new-feature')
+ * @Get()
+ * async getNewFeature() { ... }
+ *
+ * // 抛出异常
+ * @FeatureEnabled('beta', { throwIfDisabled: true, errorMessage: '功能暂未开放' })
+ * async betaFeature() { ... }
+ * ```
+ */
+export function FeatureEnabled(
+  flagName: string,
+  options?: Partial<Omit<FeatureFlagOptions, 'flagName'>>,
+): MethodDecorator {
+  const flagOptions: FeatureFlagOptions = {
+    flagName,
+    strategy: 'boolean',
+    throwIfDisabled: false,
+    ...options,
+  };
+
+  return SetMetadata(FEATURE_FLAG_METADATA_KEY, flagOptions);
+}
+
+/**
+ * @FeatureFlags - 多功能开关装饰器
+ *
+ * 同时检查多个功能开关，全部启用时才执行方法。
+ *
+ * @param flags - 功能开关配置数组
+ *
+ * @example
+ * ```typescript
+ * @FeatureFlags([
+ *     { flagName: 'feature-a' },
+ *     { flagName: 'feature-b', throwIfDisabled: true },
+ * ])
+ * async combinedFeature() { ... }
+ * ```
+ */
+export function FeatureFlags(
+  flags: Array<{
+    flagName: string;
+    options?: Partial<Omit<FeatureFlagOptions, 'flagName'>>;
+  }>,
+): MethodDecorator {
+  const flagConfigs = flags.map((f) => ({
+    flagName: f.flagName,
+    strategy: 'boolean' as FeatureFlagStrategy,
+    throwIfDisabled: false,
+    ...f.options,
+  }));
+
+  return SetMetadata(FEATURE_FLAGS_METADATA_KEY, flagConfigs);
+}
+
+/**
+ * @IfFeatureEnabled - 条件装饰器别名
+ *
+ * 与 @FeatureEnabled 相同，但语义更清晰。
+ * 如果功能未启用，抛出 NotFoundException。
+ */
+export function IfFeatureEnabled(flagName: string): MethodDecorator {
+  return FeatureEnabled(flagName, { throwIfDisabled: true });
+}
+
+/**
+ * @BetaFeature - Beta 功能装饰器
+ *
+ * 标记 Beta 功能，仅对特定用户或环境开放。
+ */
+export function BetaFeature(
+  flagName: string,
+  options?: { userIdParam?: string },
+): MethodDecorator {
+  return FeatureEnabled(flagName, {
+    strategy: 'userId',
+    throwIfDisabled: true,
+    errorMessage: 'Beta 功能暂未对您开放',
+    ...options,
+  });
+}
+
+/**
+ * @GradualRollout - 灰度发布装饰器
+ *
+ * 按百分比逐步开放功能。
+ */
+export function GradualRollout(
+  flagName: string,
+  percentage: number,
+): MethodDecorator {
+  return FeatureEnabled(flagName, {
+    strategy: 'percentage',
+    percentage,
+    throwIfDisabled: true,
+    errorMessage: '功能正在逐步开放中',
+  });
+}

package/template/apps/api/libs/infra/common/decorators/feature-flag/feature-flag.interceptor.ts

@@ -0,0 +1,150 @@
+/**
+ * Feature Flag Interceptor
+ *
+ * 拦截器实现，处理 @FeatureEnabled 装饰器逻辑。
+ */
+
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+  Inject,
+  NotImplementedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable, of, from } from 'rxjs';
+import { switchMap } from 'rxjs/operators';
+import { WINSTON_MODULE_PROVIDER } from 'nest-winston';
+import { Logger } from 'winston';
+
+import {
+  FEATURE_FLAG_METADATA_KEY,
+  FEATURE_FLAGS_METADATA_KEY,
+  FeatureFlagOptions,
+  FeatureFlagContext,
+} from './feature-flag.decorator';
+import { FeatureFlagService } from './feature-flag.service';
+
+@Injectable()
+export class FeatureFlagInterceptor implements NestInterceptor {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly featureFlagService: FeatureFlagService,
+    @Inject(WINSTON_MODULE_PROVIDER) private readonly logger: Logger,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const handler = context.getHandler();
+
+    // 获取单个功能开关
+    const flagOptions = this.reflector.get<FeatureFlagOptions>(
+      FEATURE_FLAG_METADATA_KEY,
+      handler,
+    );
+
+    // 获取多个功能开关
+    const flagsOptions = this.reflector.get<FeatureFlagOptions[]>(
+      FEATURE_FLAGS_METADATA_KEY,
+      handler,
+    );
+
+    // 无功能开关配置，直接执行
+    if (!flagOptions && !flagsOptions) {
+      return next.handle();
+    }
+
+    // 构建评估上下文
+    const request = context.switchToHttp().getRequest();
+    const flagContext: FeatureFlagContext = {
+      userId: request.user?.id || request.userId,
+      environment: process.env.NODE_ENV,
+      request: {
+        ip: request.ip,
+        sessionId: request.session?.id,
+        headers: request.headers,
+      },
+      properties: {},
+    };
+
+    // 处理单个功能开关
+    if (flagOptions) {
+      return from(this.evaluateFlag(flagOptions, flagContext)).pipe(
+        switchMap((isEnabled) => {
+          if (isEnabled) {
+            return next.handle();
+          }
+          return this.handleDisabled(flagOptions);
+        }),
+      );
+    }
+
+    // 处理多个功能开关
+    if (flagsOptions) {
+      return from(this.evaluateMultipleFlags(flagsOptions, flagContext)).pipe(
+        switchMap((allEnabled) => {
+          if (allEnabled) {
+            return next.handle();
+          }
+          // 找到第一个未启用的开关
+          const disabledFlag = flagsOptions.find((f) => f.throwIfDisabled);
+          return this.handleDisabled(disabledFlag || flagsOptions[0]);
+        }),
+      );
+    }
+
+    return next.handle();
+  }
+
+  /**
+   * 评估单个功能开关
+   */
+  private async evaluateFlag(
+    options: FeatureFlagOptions,
+    context: FeatureFlagContext,
+  ): Promise<boolean> {
+    const isEnabled = await this.featureFlagService.evaluate(options, context);
+
+    this.logger.debug('Feature flag evaluated', {
+      flagName: options.flagName,
+      isEnabled,
+      strategy: options.strategy,
+      userId: context.userId,
+    });
+
+    return isEnabled;
+  }
+
+  /**
+   * 评估多个功能开关
+   */
+  private async evaluateMultipleFlags(
+    optionsList: FeatureFlagOptions[],
+    context: FeatureFlagContext,
+  ): Promise<boolean> {
+    for (const options of optionsList) {
+      const isEnabled = await this.featureFlagService.evaluate(
+        options,
+        context,
+      );
+      if (!isEnabled) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * 处理功能未启用
+   */
+  private handleDisabled(options: FeatureFlagOptions): Observable<any> {
+    if (options.throwIfDisabled) {
+      const message =
+        options.errorMessage || `功能 ${options.flagName} 暂未开放`;
+      throw new NotImplementedException(message);
+    }
+
+    // 返回空响应
+    return of(null);
+  }
+}

package/template/apps/api/libs/infra/common/decorators/feature-flag/feature-flag.module.ts

@@ -0,0 +1,27 @@
+/**
+ * Feature Flag Module
+ *
+ * 提供功能开关服务的全局模块。
+ * 支持 Unleash 集成或自定义 Redis/内存实现。
+ */
+
+import { Global, Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { ConfigModule } from '@nestjs/config';
+import { RedisModule } from '@app/redis';
+import { FeatureFlagService } from './feature-flag.service';
+import { FeatureFlagInterceptor } from './feature-flag.interceptor';
+
+@Global()
+@Module({
+  imports: [ConfigModule, RedisModule],
+  providers: [
+    FeatureFlagService,
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: FeatureFlagInterceptor,
+    },
+  ],
+  exports: [FeatureFlagService],
+})
+export class FeatureFlagModule {}