@nest-omni/core 4.1.3-1 → 4.1.3-11

package/vault/vault-config.loader.js

@@ -11,7 +11,15 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultConfigLoader = void 0;
 const common_1 = require("@nestjs/common");
+/**
+ * Vault 配置加载器
+ * 负责在应用启动时从 Vault 加载配置并注入到 process.env
+ * 配置优先级: base.env < 环境.env < Vault
+ */
 class VaultConfigLoader {
+    /**
+     * 从环境变量构建 Vault 配置
+     */
     static buildVaultOptions() {
         var _a;
         const enabled = process.env.VAULT_ENABLED === 'true';
@@ -29,6 +37,7 @@ class VaultConfigLoader {
             this.logger.warn('Vault enabled but VAULT_SECRET_PATHS is empty');
             return null;
         }
+        // 构建认证配置
         const auth = {};
         if (process.env.VAULT_TOKEN) {
             auth.token = process.env.VAULT_TOKEN;
@@ -57,13 +66,17 @@ class VaultConfigLoader {
             timeout: parseInt(process.env.VAULT_TIMEOUT || '5000', 10),
             enableHotReload: process.env.VAULT_HOT_RELOAD === 'true',
             hotReloadInterval: parseInt(process.env.VAULT_HOT_RELOAD_INTERVAL || '300', 10),
-            failOnError: process.env.VAULT_FAIL_ON_ERROR !== 'false',
+            failOnError: process.env.VAULT_FAIL_ON_ERROR !== 'false', // 默认失败时终止
         };
         this.logger.log(`Vault configuration loaded: ${secretPaths.length} secret path(s)`);
         return options;
     }
+    /**
+     * 初始化 Vault 客户端并进行认证
+     */
     static initializeVaultClient(options) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 动态导入 node-vault
             let vault;
             try {
                 vault = yield Promise.resolve().then(() => require('node-vault'));
@@ -79,12 +92,15 @@ class VaultConfigLoader {
                     timeout: options.timeout,
                 },
             });
+            // 根据认证方式进行认证
             try {
                 if (options.auth.token) {
+                    // Token 认证
                     client.token = options.auth.token;
                     this.logger.log('Vault Token authentication configured');
                 }
                 else if (options.auth.roleId && options.auth.secretId) {
+                    // AppRole 认证
                     const result = yield client.approleLogin({
                         role_id: options.auth.roleId,
                         secret_id: options.auth.secretId,
@@ -93,7 +109,9 @@ class VaultConfigLoader {
                     this.logger.log('Vault AppRole authentication successful');
                 }
                 else if (options.auth.k8sRole) {
+                    // Kubernetes 认证
                     let jwt = options.auth.k8sServiceAccountToken;
+                    // 如果没有提供 token，从默认路径读取
                     if (!jwt) {
                         const fs = yield Promise.resolve().then(() => require('fs'));
                         const K8S_SA_TOKEN_PATH = '/var/run/secrets/kubernetes.io/serviceaccount/token';
@@ -114,6 +132,7 @@ class VaultConfigLoader {
                 else {
                     throw new Error('No valid Vault authentication method configured');
                 }
+                // 验证 token 是否有效
                 yield client.tokenLookupSelf();
                 this.logger.log('Vault authentication verified');
                 return client;
@@ -124,6 +143,9 @@ class VaultConfigLoader {
             }
         });
     }
+    /**
+     * 从 Vault 读取指定路径的配置
+     */
     static readSecrets(client, secretPath, apiVersion) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
@@ -133,6 +155,8 @@ class VaultConfigLoader {
                     this.logger.warn(`No data found at path: ${secretPath}`);
                     return {};
                 }
+                // KV v2 引擎的数据在 data.data 中
+                // KV v1 引擎的数据在 data 中
                 const secrets = apiVersion === 'v2' ? result.data.data : result.data;
                 if (!secrets || typeof secrets !== 'object') {
                     this.logger.warn(`Invalid secret format at path: ${secretPath}`);
@@ -148,6 +172,10 @@ class VaultConfigLoader {
             }
         });
     }
+    /**
+     * 加载 Vault 配置并注入到 process.env
+     * 配置优先级: base.env < 环境.env < Vault（Vault 会覆盖之前的配置）
+     */
     static loadVaultConfig() {
         return __awaiter(this, void 0, void 0, function* () {
             const options = this.buildVaultOptions();
@@ -158,11 +186,14 @@ class VaultConfigLoader {
             try {
                 this.logger.log(`Connecting to Vault at ${options.endpoint}`);
                 this.vaultClient = yield this.initializeVaultClient(options);
+                // 从所有配置路径读取配置（后面的路径会覆盖前面的）
                 const allSecrets = {};
                 for (const secretPath of options.secretPaths) {
                     const secrets = yield this.readSecrets(this.vaultClient, secretPath, options.apiVersion);
+                    // 合并配置（后面的路径会覆盖前面的）
                     Object.assign(allSecrets, secrets);
                 }
+                // 注入到 process.env（覆盖所有已有的环境变量）
                 let injectedCount = 0;
                 let overriddenCount = 0;
                 for (const [key, value] of Object.entries(allSecrets)) {
@@ -177,12 +208,14 @@ class VaultConfigLoader {
                     }
                 }
                 this.logger.log(`Vault configuration loaded: ${injectedCount} new, ${overriddenCount} overridden`);
+                // 启动热更新（如果启用）
                 if (options.enableHotReload) {
                     this.startHotReload(options);
                 }
             }
             catch (error) {
                 this.logger.error('Failed to load Vault configuration', error.message);
+                // 根据配置决定是否在 Vault 失败时继续启动
                 if (options.failOnError) {
                     this.logger.error('Application startup failed due to Vault error');
                     throw error;
@@ -193,8 +226,12 @@ class VaultConfigLoader {
             }
         });
     }
+    /**
+     * 启动配置热更新
+     */
     static startHotReload(options) {
         this.logger.log(`Starting Vault hot reload with interval: ${options.hotReloadInterval}s`);
+        // 清除之前的定时器
         if (this.hotReloadTimer) {
             clearInterval(this.hotReloadTimer);
         }
@@ -206,6 +243,7 @@ class VaultConfigLoader {
                     const secrets = yield this.readSecrets(this.vaultClient, secretPath, options.apiVersion);
                     Object.assign(allSecrets, secrets);
                 }
+                // 更新 process.env
                 let changedCount = 0;
                 for (const [key, value] of Object.entries(allSecrets)) {
                     const newValue = String(value);
@@ -227,6 +265,9 @@ class VaultConfigLoader {
             }
         }), options.hotReloadInterval * 1000);
     }
+    /**
+     * 停止热更新
+     */
     static stopHotReload() {
         if (this.hotReloadTimer) {
             clearInterval(this.hotReloadTimer);
@@ -234,9 +275,15 @@ class VaultConfigLoader {
             this.logger.log('Vault hot reload stopped');
         }
     }
+    /**
+     * 获取 Vault 客户端（用于运行时动态读取）
+     */
     static getVaultClient() {
         return this.vaultClient;
     }
+    /**
+     * 检查 Vault 是否已连接
+     */
     static isConnected() {
         return this.vaultClient !== null && this.vaultClient !== undefined;
     }

package/vault/vault-config.service.d.ts

@@ -1,18 +1,71 @@
+/**
+ * Vault 配置服务
+ * 提供运行时动态访问 Vault 配置的能力
+ * 用于读取敏感配置而不缓存到 process.env
+ */
 export declare class VaultConfigService {
     private readonly logger;
     private vaultClient;
     constructor();
+    /**
+     * 检查 Vault 是否可用
+     */
     isAvailable(): boolean;
+    /**
+     * 运行时动态读取 Vault 配置
+     * @param path Vault 配置路径
+     * @param key 可选，指定要读取的配置键，不指定则返回整个配置对象
+     * @returns 配置值
+     *
+     * @example
+     * // 读取整个配置对象
+     * const config = await vaultConfigService.getSecret('secret/data/app/config');
+     *
+     * // 读取指定键
+     * const apiKey = await vaultConfigService.getSecret('secret/data/app/config', 'API_KEY');
+     */
     getSecret(path: string, key?: string): Promise<any>;
+    /**
+     * 写入配置到 Vault（需要相应权限）
+     * @param path Vault 配置路径
+     * @param data 配置数据
+     *
+     * @example
+     * await vaultConfigService.setSecret('secret/data/app/config', {
+     *   API_KEY: 'new-key',
+     *   DB_PASSWORD: 'new-password',
+     * });
+     */
     setSecret(path: string, data: Record<string, any>): Promise<void>;
+    /**
+     * 删除 Vault 中的配置（需要相应权限）
+     * @param path Vault 配置路径
+     */
     deleteSecret(path: string): Promise<void>;
+    /**
+     * 列出指定路径下的所有配置键
+     * @param path Vault 配置路径
+     * @returns 配置键列表
+     */
     listSecrets(path: string): Promise<string[]>;
+    /**
+     * 检查 Vault 健康状态
+     * @returns 是否健康
+     */
     healthCheck(): Promise<boolean>;
+    /**
+     * 获取 Vault 状态信息
+     * @returns Vault 状态
+     */
     getStatus(): Promise<{
         initialized: boolean;
         sealed: boolean;
         standby: boolean;
         version: string;
     } | null>;
+    /**
+     * 续订 Token（对于有时限的 Token）
+     * @param increment 续订时长（秒）
+     */
     renewToken(increment?: number): Promise<void>;
 }

package/vault/vault-config.service.js

@@ -22,6 +22,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultConfigService = void 0;
 const common_1 = require("@nestjs/common");
 const vault_config_loader_1 = require("./vault-config.loader");
+/**
+ * Vault 配置服务
+ * 提供运行时动态访问 Vault 配置的能力
+ * 用于读取敏感配置而不缓存到 process.env
+ */
 let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
     constructor() {
         this.logger = new common_1.Logger(VaultConfigService_1.name);
@@ -30,9 +35,25 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             this.logger.warn('Vault client not initialized. VaultConfigService methods will throw errors.');
         }
     }
+    /**
+     * 检查 Vault 是否可用
+     */
     isAvailable() {
         return vault_config_loader_1.VaultConfigLoader.isConnected();
     }
+    /**
+     * 运行时动态读取 Vault 配置
+     * @param path Vault 配置路径
+     * @param key 可选，指定要读取的配置键，不指定则返回整个配置对象
+     * @returns 配置值
+     *
+     * @example
+     * // 读取整个配置对象
+     * const config = await vaultConfigService.getSecret('secret/data/app/config');
+     *
+     * // 读取指定键
+     * const apiKey = await vaultConfigService.getSecret('secret/data/app/config', 'API_KEY');
+     */
     getSecret(path, key) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -44,16 +65,19 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
                 if (!result || !result.data) {
                     throw new Error(`No data found at path: ${path}`);
                 }
+                // KV v2 引擎的数据在 data.data 中
                 const data = apiVersion === 'v2' ? result.data.data : result.data;
                 if (!data || typeof data !== 'object') {
                     throw new Error(`Invalid secret format at path: ${path}`);
                 }
+                // 如果指定了 key，返回对应的值
                 if (key) {
                     if (!(key in data)) {
                         throw new Error(`Key '${key}' not found in secret at path: ${path}`);
                     }
                     return data[key];
                 }
+                // 否则返回整个配置对象
                 return data;
             }
             catch (error) {
@@ -62,6 +86,17 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 写入配置到 Vault（需要相应权限）
+     * @param path Vault 配置路径
+     * @param data 配置数据
+     *
+     * @example
+     * await vaultConfigService.setSecret('secret/data/app/config', {
+     *   API_KEY: 'new-key',
+     *   DB_PASSWORD: 'new-password',
+     * });
+     */
     setSecret(path, data) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -70,6 +105,7 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             try {
                 const apiVersion = process.env.VAULT_API_VERSION || 'v2';
                 if (apiVersion === 'v2') {
+                    // KV v2 引擎需要将数据包装在 data 字段中
                     yield this.vaultClient.write(path, { data });
                 }
                 else {
@@ -83,6 +119,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 删除 Vault 中的配置（需要相应权限）
+     * @param path Vault 配置路径
+     */
     deleteSecret(path) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -98,6 +138,11 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 列出指定路径下的所有配置键
+     * @param path Vault 配置路径
+     * @returns 配置键列表
+     */
     listSecrets(path) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -116,6 +161,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 检查 Vault 健康状态
+     * @returns 是否健康
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -131,6 +180,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 获取 Vault 状态信息
+     * @returns Vault 状态
+     */
     getStatus() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {
@@ -151,6 +204,10 @@ let VaultConfigService = VaultConfigService_1 = class VaultConfigService {
             }
         });
     }
+    /**
+     * 续订 Token（对于有时限的 Token）
+     * @param increment 续订时长（秒）
+     */
     renewToken(increment) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.vaultClient) {

package/vault/vault.module.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Vault 模块
+ * 全局模块，提供 VaultConfigService 供整个应用使用
+ */
 export declare class VaultModule {
 }

package/vault/vault.module.js

@@ -9,6 +9,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VaultModule = void 0;
 const common_1 = require("@nestjs/common");
 const vault_config_service_1 = require("./vault-config.service");
+/**
+ * Vault 模块
+ * 全局模块，提供 VaultConfigService 供整个应用使用
+ */
 let VaultModule = class VaultModule {
 };
 exports.VaultModule = VaultModule;

package/decorators/examples/validation-decorators.example.d.ts

@@ -1,69 +0,0 @@
-export declare class ContactDto {
-    email?: string;
-    phone?: string;
-    wechat?: string;
-}
-export declare class SearchDto {
-    keyword?: string;
-    category?: string;
-    tags?: string[];
-}
-export declare class PasswordDto {
-    password: string;
-}
-export declare class EmailCheckDto {
-    email: string;
-    userService?: any;
-}
-export declare class OrderDto {
-    orderType: 'standard' | 'express';
-    deliveryDate?: Date;
-}
-export declare class DiscountDto {
-    discountType: 'percentage' | 'fixed';
-    discountValue: number;
-    get validatedDiscountValue(): number;
-}
-export declare class UserRegistrationDto {
-    username: string;
-    password: string;
-    confirmPassword: string;
-    validatePassword(password: string): boolean;
-    validatePasswordMatch(confirmPassword: string): boolean;
-}
-export declare class CreateProductDto {
-    name: string;
-    sku: string;
-    categoryId: string;
-    get validatedCategoryId(): string;
-    productService?: any;
-    categoryService?: any;
-    checkSkuUniqueness(sku: string): Promise<boolean>;
-    validateCategoryExists(categoryId: string): Promise<boolean>;
-}
-export declare class EmployeeDto {
-    name: string;
-    personalEmail?: string;
-    workEmail?: string;
-    phone?: string;
-    validatePhoneFormat(phone: string): boolean;
-}
-export declare class PaymentMethodDto {
-    paymentType: 'credit_card' | 'bank_transfer' | 'digital_wallet';
-    creditCard?: {
-        number: string;
-        expiryDate: string;
-        cvv: string;
-    };
-    bankAccount?: {
-        accountNumber: string;
-        routingNumber: string;
-    };
-    digitalWallet?: {
-        provider: string;
-        walletId: string;
-    };
-    validateCreditCard(creditCard: any): boolean;
-    validateBankAccount(bankAccount: any): boolean;
-    validateDigitalWallet(digitalWallet: any): boolean;
-}