@be-link/shield-for-tcb-node-sdk 1.0.11 → 1.0.13

package/README.md

@@ -126,6 +126,68 @@ const frontendConfig = await frontendConfigService.fetchConfig({ key: 'your-key'
 | 版本追踪 | ❌ | ✅ |
 | 审计日志 | ❌ | ✅ |
 
+---
+
+## ShieldConfigManager（配置管理器）
+
+`ShieldConfigManager` 提供配置自动拉取、缓存、定时刷新功能，适合需要持续使用配置的服务。
+
+### 使用方式
+
+```typescript
+import { ShieldConfigManager } from '@be-link/shield-for-tcb-node-sdk'
+
+const manager = new ShieldConfigManager({
+  serviceName: 'BackendBff',
+  env: 'local',
+  enableInfoLog: true, // 可选，默认 false
+})
+
+await manager.setup()
+const config = manager.getConfig<MyConfig>()
+manager.stop()
+```
+
+### 配置参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `serviceName` | `string` | **必填** | 服务名称 |
+| `env` | `string` | `NODE_ENV` | 环境 |
+| `refreshIntervalMs` | `number` | `5000` | 刷新间隔（毫秒） |
+| `fetchTimeoutMs` | `number` | `10000` | 请求超时（毫秒） |
+| `enableInfoLog` | `boolean` | `false` | 是否打印 info 日志 |
+| `logger` | `Logger` | `console` | 自定义日志函数 |
+
+### 日志说明
+
+`enableInfoLog` 默认为 `false`，不打印 info 级别日志。设置为 `true` 时会打印以下日志：
+
+- 初始化成功
+- 配置刷新（包含配置的 key 列表）
+- 配置最终内容
+- 定时器启动信息
+- 停止信息
+
+error 级别日志不受 `enableInfoLog` 影响，始终打印：
+
+- 初始刷新失败
+- 配置为空警告
+- 刷新错误
+- 定时器刷新错误
+
+### API
+
+| 方法 | 说明 |
+|------|------|
+| `setup()` | 初始化并启动定时刷新，幂等操作 |
+| `getConfig<T>()` | 获取类型化的配置对象 |
+| `refresh()` | 手动触发一次配置刷新 |
+| `stop()` | 停止定时刷新，清理资源 |
+| `waitForSetup()` | 等待初始化完成 |
+| `isSetup` | 是否已完成初始化（只读属性） |
+| `config` | 当前缓存的配置（原始 Record，只读属性） |
+
 ## 发布流程
 
 ### 自动发布（推荐）

package/modules/config/ShieldConfigManager.d.ts

@@ -45,6 +45,32 @@ export interface Logger {
     warn: (message: string, ...args: any[]) => void;
     error: (message: string, ...args: any[]) => void;
 }
+/**
+ * 流量控制配置
+ *
+ * @example
+ * ```json
+ * {
+ *   "enabled": true,
+ *   "totalBuckets": 100,
+ *   "effectiveBuckets": 10,
+ *   "whitelist": ["user_001", "user_002"],
+ *   "blacklist": ["test_*"]
+ * }
+ * ```
+ */
+export interface TrafficControlConfig {
+    /** 总开关 */
+    enabled: boolean;
+    /** 总桶数 */
+    totalBuckets: number;
+    /** 生效桶数（bucket 0 到 effectiveBuckets-1 生效） */
+    effectiveBuckets: number;
+    /** 白名单（命中后视为生效） */
+    whitelist?: string[];
+    /** 黑名单（命中后视为不生效） */
+    blacklist?: string[];
+}
 /**
  * 配置管理器
  *
@@ -76,6 +102,52 @@ export declare class ShieldConfigManager<T = Record<string, any>> {
      * @returns 泛型 T 类型的配置对象
      */
     getConfig(): T | null;
+    /**
+     * 根据 config_key 获取对应的配置值
+     * @param key 配置键名（如 'REDIS', 'SQL'）
+     * @param defaultValue 默认值（可选）
+     * @returns 配置值，如果不存在则返回默认值或 undefined
+     * @example
+     * ```ts
+     * // 获取配置
+     * const port = manager.getValue('API_PORT', 8090)
+     *
+     * // 获取配置并指定类型
+     * const isEnabled = manager.getValue<boolean>('FEATURE.ENABLED', false)
+     * ```
+     */
+    getValue<T = string>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * 根据 config_key 获取开关状态（布尔值）
+     * @param key 配置键名
+     * @param defaultValue 默认值（可选），默认为 false
+     * @returns 开关状态，true 表示开启，false 表示关闭
+     * @example
+     * ```ts
+     * // 检查功能是否开启
+     * const isEnabled = manager.isSwitchEnabled('FEATURE.ENABLED')
+     *
+     * // 指定默认值为 true
+     * const isDebug = manager.isSwitchEnabled('DEBUG_MODE', true)
+     * ```
+     */
+    isSwitchEnabled(key: string, defaultValue?: boolean): boolean;
+    /**
+     * 判断请求是否命中灰度流量
+     * @param configKey 配置键名（如 'TRAFFIC_SPLIT'）
+     * @param identifier 路由标识（如用户ID）
+     * @param defaultValue 默认值（可选），默认为 false
+     * @returns 是否命中灰度流量
+     * @example
+     * ```ts
+     * // 检查用户是否命中灰度流量
+     * const isHit = manager.isHitGrey('TRAFFIC_SPLIT', userId, false)
+     * if (isHit) {
+     *   // 灰度流量
+     * }
+     * ```
+     */
+    isHitGrey(configKey: string, identifier: string, defaultValue?: boolean): boolean;
     /**
      * 停止定时刷新，清理资源
      */

package/modules/config/ShieldConfigManager.js

@@ -71,7 +71,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _ShieldConfigManager_instances, _ShieldConfigManager_serviceName, _ShieldConfigManager_env, _ShieldConfigManager_refreshIntervalMs, _ShieldConfigManager_fetchTimeoutMs, _ShieldConfigManager_enableInfoLog, _ShieldConfigManager_logger, _ShieldConfigManager_config, _ShieldConfigManager_refreshTimer, _ShieldConfigManager_isSetup, _ShieldConfigManager_setupPromise, _ShieldConfigManager_doSetup, _ShieldConfigManager_startRefreshTimer;
+var _ShieldConfigManager_instances, _ShieldConfigManager_serviceName, _ShieldConfigManager_env, _ShieldConfigManager_refreshIntervalMs, _ShieldConfigManager_fetchTimeoutMs, _ShieldConfigManager_enableInfoLog, _ShieldConfigManager_logger, _ShieldConfigManager_config, _ShieldConfigManager_refreshTimer, _ShieldConfigManager_isSetup, _ShieldConfigManager_setupPromise, _ShieldConfigManager_doSetup, _ShieldConfigManager_hashString, _ShieldConfigManager_startRefreshTimer;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShieldConfigManager = void 0;
 const serviceV2_1 = require("./serviceV2");
@@ -155,14 +155,14 @@ class ShieldConfigManager {
             const config = await withTimeout(serviceV2_1.backendConfigServiceV2.fetchAllConfigs(__classPrivateFieldGet(this, _ShieldConfigManager_serviceName, "f"), __classPrivateFieldGet(this, _ShieldConfigManager_env, "f")), __classPrivateFieldGet(this, _ShieldConfigManager_fetchTimeoutMs, "f"));
             if (config && Object.keys(config).length > 0) {
                 __classPrivateFieldSet(this, _ShieldConfigManager_config, config, "f");
-                __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info(`ShieldConfigManager config refreshed (keys: ${JSON.stringify(Object.keys(config))})`);
+                __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info(`ShieldConfigManager config refreshed (keys: ${JSON.stringify(config)})`);
             }
             else {
                 __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").warn('ShieldConfigManager fetched empty config');
             }
         }
         catch (error) {
-            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`ShieldConfigManager refresh error: ${error}`);
+            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`ShieldConfigManager refresh error: ${error instanceof Error ? error.message : JSON.stringify(error)}`);
         }
         // 兼容旧的逻辑
         try {
@@ -172,9 +172,9 @@ class ShieldConfigManager {
             }
         }
         catch (error) {
-            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`fetch dynamic config error: ${error}`);
+            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`fetch dynamic config error: ${error instanceof Error ? error.message : JSON.stringify(error)}`);
         }
-        __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info(`ShieldConfigManager config refreshed finally (config: ${__classPrivateFieldGet(this, _ShieldConfigManager_config, "f")})`);
+        __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info(`ShieldConfigManager config refreshed finally (config: ${JSON.stringify(__classPrivateFieldGet(this, _ShieldConfigManager_config, "f"))})`);
     }
     /**
      * 获取类型化的配置
@@ -183,6 +183,108 @@ class ShieldConfigManager {
     getConfig() {
         return __classPrivateFieldGet(this, _ShieldConfigManager_config, "f") ?? null;
     }
+    /**
+     * 根据 config_key 获取对应的配置值
+     * @param key 配置键名（如 'REDIS', 'SQL'）
+     * @param defaultValue 默认值（可选）
+     * @returns 配置值，如果不存在则返回默认值或 undefined
+     * @example
+     * ```ts
+     * // 获取配置
+     * const port = manager.getValue('API_PORT', 8090)
+     *
+     * // 获取配置并指定类型
+     * const isEnabled = manager.getValue<boolean>('FEATURE.ENABLED', false)
+     * ```
+     */
+    getValue(key, defaultValue) {
+        if (!__classPrivateFieldGet(this, _ShieldConfigManager_config, "f")) {
+            return defaultValue;
+        }
+        const value = __classPrivateFieldGet(this, _ShieldConfigManager_config, "f")[key];
+        if (value === undefined || value === null) {
+            return defaultValue;
+        }
+        return value;
+    }
+    /**
+     * 根据 config_key 获取开关状态（布尔值）
+     * @param key 配置键名
+     * @param defaultValue 默认值（可选），默认为 false
+     * @returns 开关状态，true 表示开启，false 表示关闭
+     * @example
+     * ```ts
+     * // 检查功能是否开启
+     * const isEnabled = manager.isSwitchEnabled('FEATURE.ENABLED')
+     *
+     * // 指定默认值为 true
+     * const isDebug = manager.isSwitchEnabled('DEBUG_MODE', true)
+     * ```
+     */
+    isSwitchEnabled(key, defaultValue = false) {
+        if (!__classPrivateFieldGet(this, _ShieldConfigManager_config, "f")) {
+            return defaultValue;
+        }
+        const value = __classPrivateFieldGet(this, _ShieldConfigManager_config, "f")[key];
+        if (value === undefined || value === null) {
+            return defaultValue;
+        }
+        // 支持多种布尔值表示
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'number') {
+            return value !== 0;
+        }
+        if (typeof value === 'string') {
+            const lower = value.toLowerCase();
+            if (lower === 'true' || lower === '1' || lower === 'yes' || lower === 'on') {
+                return true;
+            }
+            if (lower === 'false' || lower === '0' || lower === 'no' || lower === 'off') {
+                return false;
+            }
+        }
+        return defaultValue;
+    }
+    /**
+     * 判断请求是否命中灰度流量
+     * @param configKey 配置键名（如 'TRAFFIC_SPLIT'）
+     * @param identifier 路由标识（如用户ID）
+     * @param defaultValue 默认值（可选），默认为 false
+     * @returns 是否命中灰度流量
+     * @example
+     * ```ts
+     * // 检查用户是否命中灰度流量
+     * const isHit = manager.isHitGrey('TRAFFIC_SPLIT', userId, false)
+     * if (isHit) {
+     *   // 灰度流量
+     * }
+     * ```
+     */
+    isHitGrey(configKey, identifier, defaultValue = false) {
+        const config = this.getValue(configKey);
+        if (!config) {
+            return defaultValue;
+        }
+        // 总开关关闭，返回 false
+        if (!config.enabled) {
+            return false;
+        }
+        // 黑名单检查（精确匹配）- 命中后返回 false
+        if (config.blacklist && config.blacklist.includes(identifier)) {
+            return false;
+        }
+        // 白名单检查（精确匹配）- 命中后返回 true
+        if (config.whitelist && config.whitelist.includes(identifier)) {
+            return true;
+        }
+        // 桶路由
+        const totalBuckets = config.totalBuckets || 100;
+        const effectiveBuckets = config.effectiveBuckets || 0;
+        const hash = __classPrivateFieldGet(this, _ShieldConfigManager_instances, "m", _ShieldConfigManager_hashString).call(this, identifier);
+        return hash % totalBuckets < effectiveBuckets;
+    }
     /**
      * 停止定时刷新，清理资源
      */
@@ -210,10 +312,18 @@ _ShieldConfigManager_serviceName = new WeakMap(), _ShieldConfigManager_env = new
     __classPrivateFieldGet(this, _ShieldConfigManager_instances, "m", _ShieldConfigManager_startRefreshTimer).call(this);
     __classPrivateFieldSet(this, _ShieldConfigManager_isSetup, true, "f");
     __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info('ShieldConfigManager initialized successfully');
+}, _ShieldConfigManager_hashString = function _ShieldConfigManager_hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash);
 }, _ShieldConfigManager_startRefreshTimer = function _ShieldConfigManager_startRefreshTimer() {
     __classPrivateFieldSet(this, _ShieldConfigManager_refreshTimer, setInterval(() => {
         this.refresh().catch((error) => {
-            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`ShieldConfigManager timer refresh error: ${error}`);
+            __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").error(`ShieldConfigManager timer refresh error: ${error instanceof Error ? error.message : JSON.stringify(error)}`);
         });
     }, __classPrivateFieldGet(this, _ShieldConfigManager_refreshIntervalMs, "f")), "f");
     __classPrivateFieldGet(this, _ShieldConfigManager_logger, "f").info(`ShieldConfigManager refresh timer started (interval: ${__classPrivateFieldGet(this, _ShieldConfigManager_refreshIntervalMs, "f")}ms)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@be-link/shield-for-tcb-node-sdk",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "ShieldForTCB Node.js SDK",
   "main": "index.js",
   "types": "index.d.ts",