@be-link/shield-for-tcb-node-sdk 1.0.1 → 1.0.3

package/README.md

@@ -10,7 +10,96 @@ npm install @be-link/shield-for-tcb-node-sdk
 pnpm add @be-link/shield-for-tcb-node-sdk
 ```
 
-## 使用
+## V2 SDK（推荐）
+
+V2 SDK 从 MySQL 数据源读取配置，支持按 service + key 获取配置，并提供自动类型解析。
+
+### 基本使用
+
+```typescript
+import { backendConfigServiceV2 } from '@be-link/shield-for-tcb-node-sdk'
+```
+
+### 获取服务列表
+
+```typescript
+const services = await backendConfigServiceV2.getServices('local')
+// 返回: ['BackendUser', 'Trade', 'User', ...]
+```
+
+### 获取服务的配置键列表
+
+```typescript
+const keys = await backendConfigServiceV2.getServiceKeys('TestService', 'local')
+// 返回: ['TestServiceKey1', 'TestServiceKey2', 'TestServiceKey3', ...]
+```
+
+### 获取单个配置
+
+```typescript
+// 原始格式（包含元数据）
+const config = await backendConfigServiceV2.fetchConfig({
+  service: 'TestService',
+  key: 'TestServiceKey1',
+  env: 'local'
+})
+// 返回: { config_key: 'TestServiceKey1', value: 'xxx', value_type: 'string', updated_at: '...' }
+
+// 自动解析类型（推荐）
+const host = await backendConfigServiceV2.getConfigValue<string>('TestService', 'TestServiceKey1', 'local')
+// 返回: '127.0.0.1'
+
+const port = await backendConfigServiceV2.getConfigValue<number>('TestService', 'TestServiceKey1', 'local')
+// 返回: 1234（自动解析为数字）
+
+const enabled = await backendConfigServiceV2.getConfigValue<boolean>('TestService', 'TestServiceKey1', 'local')
+// 返回: true/false（自动解析为布尔值）
+
+const jsonConfig = await backendConfigServiceV2.getConfigValue<object>('BackendUser', 'TestServiceKey1', 'local')
+// 返回: { ... }（自动 JSON 解析）
+```
+
+### 批量获取配置
+
+```typescript
+// 原始格式
+const configs = await backendConfigServiceV2.fetchConfigs({
+  service: 'TestService',
+  keys: ['TestServiceKey1', 'TestServiceKey2'],
+  env: 'local'
+})
+// 返回: { 'TestServiceKey1': { value: 'xxx', value_type: 'string' }, ... }
+
+// 自动解析类型（推荐）
+const values = await backendConfigServiceV2.getConfigValues(
+  'TestService',
+  ['TestServiceKey1', 'TestServiceKey2', 'TestServiceKey3'],
+  'local'
+)
+// 返回: {
+// }
+```
+
+### 环境变量
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| `SHIELD_SDK_HOST` | 覆盖 SDK 请求地址（本地开发用） | `http://localhost:8090` |
+| `CONTAINER_ENV` | 容器环境，默认 `SCF`（云函数），设置为其他值使用内网地址 | `ECS` |
+| `NODE_ENV` | 环境标识，`prod` 使用生产环境地址 | `local` / `ppe` / `prod` |
+
+### 本地开发
+
+```bash
+# 设置本地服务地址
+export SHIELD_SDK_HOST=http://localhost:8090
+```
+
+---
+
+## V1 SDK（旧版）
+
+V1 SDK 从 YAML 文件读取配置，保持向后兼容。
 
 ```typescript
 import { backendConfigService, frontendConfigService } from '@be-link/shield-for-tcb-node-sdk'
@@ -21,13 +110,22 @@ const config = await backendConfigService.fetchConfig({ key: 'your-key', type: '
 // 前端使用（跳过异常处理，直接抛出原始错误）
 const frontendConfig = await frontendConfigService.fetchConfig({ key: 'your-key', type: 'json' })
 
-// 获取全局动态配置
-const globalConfig = await backendConfigService.fetchGlobalDynamicConfig()
-
-// 获取 COS 临时密钥
-const cosTempSecret = await backendConfigService.getCosTempSecret()
 ```
 
+---
+
+## V1 vs V2 对比
+
+| 特性 | V1 SDK | V2 SDK |
+|------|--------|--------|
+| 数据源 | YAML 文件 | MySQL |
+| 获取方式 | 按 key | 按 service + key |
+| 类型解析 | 手动指定 type | 自动根据 value_type 解析 |
+| 批量获取 | ❌ | ✅ |
+| 配置管理 | ❌ | ✅（通过管理后台） |
+| 版本追踪 | ❌ | ✅ |
+| 审计日志 | ❌ | ✅ |
+
 ## 发布流程
 
 ### 自动发布（推荐）

package/index.d.ts

@@ -1,2 +1,4 @@
 export { backendConfigService } from './modules/config/service';
 export type { Service as ConfigControllerTypes } from './modules/config/types';
+export { backendConfigServiceV2, ConfigServiceV2 } from './modules/config/serviceV2';
+export type { ServiceV2 as ConfigControllerTypesV2 } from './modules/config/typesV2';

package/index.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.backendConfigService = void 0;
+exports.ConfigServiceV2 = exports.backendConfigServiceV2 = exports.backendConfigService = void 0;
+// V1 SDK (YAML 数据源)
 var service_1 = require("./modules/config/service");
 Object.defineProperty(exports, "backendConfigService", { enumerable: true, get: function () { return service_1.backendConfigService; } });
+// V2 SDK (MySQL 数据源)
+var serviceV2_1 = require("./modules/config/serviceV2");
+Object.defineProperty(exports, "backendConfigServiceV2", { enumerable: true, get: function () { return serviceV2_1.backendConfigServiceV2; } });
+Object.defineProperty(exports, "ConfigServiceV2", { enumerable: true, get: function () { return serviceV2_1.ConfigServiceV2; } });

package/modules/BaseService.d.ts

@@ -9,6 +9,12 @@ export default abstract class BaseService {
     protected readonly publicDevHost = "https://ecommerce-dev.wejourney.top";
     protected readonly publicProdHost = "https://ecommerce-release.wejourney.top";
     constructor();
+    /** 获取 Host */
+    protected getHost(): string;
+    /** 获取 Host (V2，支持环境变量覆盖) */
+    protected getHostV2(): string;
     /** 获取API URL */
     protected getApiUrl(func: Function): string;
+    /** 获取API URL (V2，支持环境变量覆盖) */
+    protected getApiUrlV2(path: string): string;
 }

package/modules/BaseService.js

@@ -16,16 +16,32 @@ class BaseService {
         /** 如果是云函数环境, 默认走公网访问 */
         this.isPublicEnv = (process.env.CONTAINER_ENV || 'SCF') === 'SCF';
     }
-    /** 获取API URL */
-    getApiUrl(func) {
-        const host = this.isPublicEnv
+    /** 获取 Host */
+    getHost() {
+        return this.isPublicEnv
             ? env_1.default.isProduction()
                 ? this.publicProdHost
                 : this.publicDevHost
             : env_1.default.isProduction()
                 ? this.natProdHost
                 : this.natDevHost;
-        return `${host}${this.prefixUrl}/${(0, string_1.camelToKebabCase)(func.name)}`;
+    }
+    /** 获取 Host (V2，支持环境变量覆盖) */
+    getHostV2() {
+        // 支持通过环境变量覆盖 host（用于本地测试）
+        const overrideHost = process.env.SHIELD_SDK_HOST;
+        if (overrideHost) {
+            return overrideHost;
+        }
+        return this.getHost();
+    }
+    /** 获取API URL */
+    getApiUrl(func) {
+        return `${this.getHost()}${this.prefixUrl}/${(0, string_1.camelToKebabCase)(func.name)}`;
+    }
+    /** 获取API URL (V2，支持环境变量覆盖) */
+    getApiUrlV2(path) {
+        return `${this.getHostV2()}${this.prefixUrl}${path}`;
     }
 }
 exports.default = BaseService;

package/modules/config/serviceV2.d.ts

@@ -0,0 +1,58 @@
+import { ServiceV2 } from './typesV2';
+import BaseService from '../BaseService';
+/**
+ * V2 配置服务
+ * 从 MySQL 数据源读取配置，支持按 service + key 获取
+ */
+export declare class ConfigServiceV2 extends BaseService implements ServiceV2.ConfigController {
+    protected prefixUrl: string;
+    /**
+     * 获取单个配置
+     * @param req 请求参数
+     * @returns 配置数据，如果配置不存在返回 null
+     */
+    fetchConfig(req: ServiceV2.Request.FetchConfig): Promise<ServiceV2.Response.FetchConfigResponse | null>;
+    /**
+     * 批量获取配置
+     * @param req 请求参数
+     * @returns 配置数据映射
+     */
+    fetchConfigs(req: ServiceV2.Request.FetchConfigs): Promise<ServiceV2.Response.FetchConfigsResponse>;
+    /**
+     * 获取所有服务列表
+     * @param env 环境名称（可选，默认使用当前环境）
+     * @returns 服务名称列表
+     */
+    getServices(env?: string): Promise<ServiceV2.Response.GetServicesResponse>;
+    /**
+     * 获取指定服务的配置键列表
+     * @param serviceName 服务名称
+     * @param env 环境名称（可选，默认使用当前环境）
+     * @returns 配置键列表
+     */
+    getServiceKeys(serviceName: string, env?: string): Promise<ServiceV2.Response.GetServiceKeysResponse>;
+    /**
+     * 获取配置值（自动解析类型）
+     * @param service 服务名称
+     * @param key 配置键
+     * @param env 环境（可选）
+     * @returns 解析后的配置值
+     */
+    getConfigValue<T = any>(service: string, key: string, env?: string): Promise<T | null>;
+    /**
+     * 批量获取配置值（自动解析类型）
+     * @param service 服务名称
+     * @param keys 配置键列表（可选，不传则获取该服务所有配置）
+     * @param env 环境（可选）
+     * @returns 解析后的配置值映射
+     */
+    getConfigValues<T = any>(service: string, keys?: string[], env?: string): Promise<Record<string, T>>;
+    /**
+     * 获取指定服务的所有配置
+     * @param service 服务名称
+     * @param env 环境（可选）
+     * @returns 该服务所有配置（自动解析类型）
+     */
+    fetchAllConfigs<T = any>(service: string, env?: string): Promise<Record<string, T>>;
+}
+export declare const backendConfigServiceV2: ConfigServiceV2;

package/modules/config/serviceV2.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backendConfigServiceV2 = exports.ConfigServiceV2 = void 0;
+const http_1 = require("../../utils/http");
+const BaseService_1 = __importDefault(require("../BaseService"));
+/**
+ * V2 配置服务
+ * 从 MySQL 数据源读取配置，支持按 service + key 获取
+ */
+class ConfigServiceV2 extends BaseService_1.default {
+    constructor() {
+        super(...arguments);
+        this.prefixUrl = '/v2/shield/config';
+    }
+    /**
+     * 获取单个配置
+     * @param req 请求参数
+     * @returns 配置数据，如果配置不存在返回 null
+     */
+    fetchConfig(req) {
+        return (0, http_1.callApi)(this.getApiUrlV2('/fetch'), req, {
+            skipErrorHandling: true,
+        }).catch(() => null);
+    }
+    /**
+     * 批量获取配置
+     * @param req 请求参数
+     * @returns 配置数据映射
+     */
+    fetchConfigs(req) {
+        return (0, http_1.callApi)(this.getApiUrlV2('/fetch-batch'), req);
+    }
+    /**
+     * 获取所有服务列表
+     * @param env 环境名称（可选，默认使用当前环境）
+     * @returns 服务名称列表
+     */
+    async getServices(env) {
+        const query = env ? `?env=${encodeURIComponent(env)}` : '';
+        return (0, http_1.getApi)(this.getApiUrlV2('/services') + query);
+    }
+    /**
+     * 获取指定服务的配置键列表
+     * @param serviceName 服务名称
+     * @param env 环境名称（可选，默认使用当前环境）
+     * @returns 配置键列表
+     */
+    async getServiceKeys(serviceName, env) {
+        const query = env ? `?env=${encodeURIComponent(env)}` : '';
+        return (0, http_1.getApi)(this.getApiUrlV2(`/services/${serviceName}/keys`) + query);
+    }
+    /**
+     * 获取配置值（自动解析类型）
+     * @param service 服务名称
+     * @param key 配置键
+     * @param env 环境（可选）
+     * @returns 解析后的配置值
+     */
+    async getConfigValue(service, key, env) {
+        const result = await this.fetchConfig({ service, key, env });
+        if (!result) {
+            return null;
+        }
+        // 根据类型解析值
+        switch (result.value_type) {
+            case 'number':
+                return Number(result.value);
+            case 'boolean':
+                return (result.value === 'true' || result.value === '1');
+            case 'object':
+            case 'array':
+                try {
+                    return JSON.parse(result.value);
+                }
+                catch {
+                    return result.value;
+                }
+            default:
+                return result.value;
+        }
+    }
+    /**
+     * 批量获取配置值（自动解析类型）
+     * @param service 服务名称
+     * @param keys 配置键列表（可选，不传则获取该服务所有配置）
+     * @param env 环境（可选）
+     * @returns 解析后的配置值映射
+     */
+    async getConfigValues(service, keys, env) {
+        const result = await this.fetchConfigs({ service, keys, env });
+        const parsed = {};
+        for (const [key, item] of Object.entries(result)) {
+            switch (item.value_type) {
+                case 'number':
+                    parsed[key] = Number(item.value);
+                    break;
+                case 'boolean':
+                    parsed[key] = (item.value === 'true' || item.value === '1');
+                    break;
+                case 'object':
+                case 'array':
+                    try {
+                        parsed[key] = JSON.parse(item.value);
+                    }
+                    catch {
+                        parsed[key] = item.value;
+                    }
+                    break;
+                default:
+                    parsed[key] = item.value;
+            }
+        }
+        return parsed;
+    }
+    /**
+     * 获取指定服务的所有配置
+     * @param service 服务名称
+     * @param env 环境（可选）
+     * @returns 该服务所有配置（自动解析类型）
+     */
+    async fetchAllConfigs(service, env) {
+        return this.getConfigValues(service, undefined, env);
+    }
+}
+exports.ConfigServiceV2 = ConfigServiceV2;
+// 导出单例
+exports.backendConfigServiceV2 = new ConfigServiceV2();

package/modules/config/typesV2.d.ts

@@ -0,0 +1,109 @@
+export declare namespace ServiceV2 {
+    namespace Entity {
+        /**
+         * 配置项
+         */
+        interface ConfigItem {
+            config_key: string;
+            value: string;
+            value_type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            updated_at: string;
+        }
+        /**
+         * 批量配置项
+         */
+        interface BatchConfigItem {
+            value: string;
+            value_type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+        }
+    }
+    namespace Request {
+        /**
+         * 获取单个配置请求参数
+         */
+        interface FetchConfig {
+            service: string;
+            key: string;
+            env?: string;
+        }
+        /**
+         * 批量获取配置请求参数
+         */
+        interface FetchConfigs {
+            service: string;
+            keys?: string[];
+            env?: string;
+        }
+        /**
+         * 获取服务列表请求参数
+         */
+        interface GetServices {
+            env?: string;
+        }
+        /**
+         * 获取服务配置键列表请求参数
+         */
+        interface GetServiceKeys {
+            serviceName: string;
+            env?: string;
+        }
+    }
+    namespace Response {
+        /**
+         * 获取单个配置响应
+         */
+        interface FetchConfigResponse {
+            config_key: string;
+            value: string;
+            value_type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            updated_at: string;
+        }
+        /**
+         * 批量获取配置响应
+         */
+        interface FetchConfigsResponse {
+            [key: string]: {
+                value: string;
+                value_type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+            };
+        }
+        /**
+         * 获取服务列表响应
+         */
+        type GetServicesResponse = string[];
+        /**
+         * 获取服务配置键列表响应
+         */
+        type GetServiceKeysResponse = string[];
+    }
+    /**
+     * V2 配置控制器接口
+     */
+    interface ConfigController {
+        /**
+         * 获取单个配置
+         * @param req 请求参数
+         * @returns 配置数据
+         */
+        fetchConfig(req: Request.FetchConfig): Promise<Response.FetchConfigResponse | null>;
+        /**
+         * 批量获取配置
+         * @param req 请求参数
+         * @returns 配置数据映射
+         */
+        fetchConfigs(req: Request.FetchConfigs): Promise<Response.FetchConfigsResponse>;
+        /**
+         * 获取所有服务列表
+         * @param env 环境名称
+         * @returns 服务列表
+         */
+        getServices(env?: string): Promise<Response.GetServicesResponse>;
+        /**
+         * 获取指定服务的配置键列表
+         * @param serviceName 服务名称
+         * @param env 环境名称
+         * @returns 配置键列表
+         */
+        getServiceKeys(serviceName: string, env?: string): Promise<Response.GetServiceKeysResponse>;
+    }
+}

package/modules/config/typesV2.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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

package/utils/http.d.ts

@@ -1,5 +1,12 @@
 type CallApiOptions = {
     skipErrorHandling?: boolean;
 };
+type GetApiOptions = {
+    skipErrorHandling?: boolean;
+};
 export declare function callApi<T extends (args: any) => Promise<any>>(url: string, request?: Parameters<T>[0], options?: CallApiOptions): Promise<Awaited<ReturnType<T>>>;
+/**
+ * GET 请求 API
+ */
+export declare function getApi<T extends (args: any) => Promise<any>>(url: string, options?: GetApiOptions): Promise<Awaited<ReturnType<T>>>;
 export {};

package/utils/http.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.callApi = callApi;
+exports.getApi = getApi;
 const axios_1 = __importDefault(require("axios"));
 const uuid_1 = require("uuid");
 const axios_retry_1 = __importDefault(require("axios-retry"));
@@ -99,3 +100,33 @@ async function callApi(url, request, options) {
         throw error;
     }
 }
+/**
+ * GET 请求 API
+ */
+async function getApi(url, options) {
+    const requestId = (0, uuid_1.v4)();
+    try {
+        console.info(`准备发起shield-for-tcb GET请求[${requestId}]: ${url}`);
+        const response = await axios_1.default.get(url, {
+            headers: { 'x-request-id': requestId, 'content-type': 'application/json' },
+        });
+        const responseData = response.data;
+        return responseData.data;
+    }
+    catch (error) {
+        if (options?.skipErrorHandling) {
+            throw error;
+        }
+        const axiosError = error;
+        if (axiosError.response) {
+            const response = axiosError.response;
+            const data = response.data;
+            console.error(`shield-for-tcb GET异常: ${axiosError.message}, requestId: ${requestId}`);
+            console.info('响应信息', data.message);
+            console.error('异常堆栈', JSON.stringify(error.stack));
+            throw axiosError;
+        }
+        console.error(`shield-for-tcb GET未知异常: ${axiosError.message}`, error.stack);
+        throw error;
+    }
+}