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

package/validators/custom-validate.validator.js

@@ -0,0 +1,214 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomValidateValidator = void 0;
+exports.CustomValidate = CustomValidate;
+const class_validator_1 = require("class-validator");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const nestjs_i18n_1 = require("nestjs-i18n");
+let CustomValidateValidator = class CustomValidateValidator {
+    constructor(moduleRef) {
+        this.moduleRef = moduleRef;
+    }
+    /**
+     * 验证入口
+     */
+    validate(value, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const [constraint, ...extraArgs] = args.constraints;
+            const context = {
+                value,
+                object: args.object,
+                property: args.property,
+                constraints: args.constraints,
+                targetName: args.targetName,
+                args,
+            };
+            try {
+                // 1. 如果是函数，直接调用
+                if (typeof constraint === 'function') {
+                    return yield this.callFunction(constraint, value, context, extraArgs);
+                }
+                // 2. 如果是字符串，调用 Entity 方法
+                if (typeof constraint === 'string') {
+                    return yield this.callEntityMethod(args.object, constraint, value, context, extraArgs);
+                }
+                // 3. 如果是数组，调用 Service 方法
+                if (Array.isArray(constraint)) {
+                    return yield this.callServiceMethod(constraint, value, context);
+                }
+                throw new Error(`[@CustomValidate] Invalid constraint type for property "${args.property}". ` +
+                    `Expected: function, string, or array. Got: ${typeof constraint}`);
+            }
+            catch (error) {
+                // 验证函数执行出错，记录详细错误信息
+                console.error(`[@CustomValidate] Validation error for property "${args.property}":`, error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * 调用内联函数
+     */
+    callFunction(fn, value, context, extraArgs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = fn(value, context, ...extraArgs);
+            return result instanceof Promise ? yield result : result;
+        });
+    }
+    /**
+     * 调用 Entity 方法
+     */
+    callEntityMethod(entity, methodName, value, context, extraArgs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!entity || typeof entity[methodName] !== 'function') {
+                throw new Error(`[@CustomValidate] Method "${methodName}" not found on entity "${context.targetName}". ` +
+                    `Make sure the method exists and is accessible.`);
+            }
+            const result = entity[methodName](value, context, ...extraArgs);
+            return result instanceof Promise ? yield result : result;
+        });
+    }
+    /**
+     * 调用 Service 方法
+     */
+    callServiceMethod(constraint, value, context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let [serviceClass, methodName, ...extraArgs] = constraint;
+            // 验证参数
+            if (!serviceClass || !methodName) {
+                throw new Error(`[@CustomValidate] Invalid service constraint format. ` +
+                    `Expected: [ServiceClass, 'methodName'] or [() => ServiceClass, 'methodName']`);
+            }
+            // 解析延迟引用（解决循环依赖）
+            if (typeof serviceClass === 'function' && !serviceClass.prototype) {
+                serviceClass = serviceClass();
+            }
+            if (!serviceClass) {
+                throw new Error(`[@CustomValidate] Service class is undefined. ` +
+                    `This may be caused by circular dependencies. ` +
+                    `Consider using lazy reference: [() => ServiceClass, 'methodName']`);
+            }
+            // 通过依赖注入获取 service 实例
+            let service;
+            try {
+                service = this.moduleRef.get(serviceClass, { strict: false });
+            }
+            catch (error) {
+                throw new Error(`[@CustomValidate] Failed to resolve service "${serviceClass.name}". ` +
+                    `Make sure the service is registered as a provider in a NestJS module. ` +
+                    `Error: ${error.message}`);
+            }
+            if (!service || typeof service[methodName] !== 'function') {
+                throw new Error(`[@CustomValidate] Method "${methodName}" not found on service "${serviceClass.name}". ` +
+                    `Available methods: ${Object.getOwnPropertyNames(Object.getPrototypeOf(service)).join(', ')}`);
+            }
+            const result = service[methodName](value, context, ...extraArgs);
+            return result instanceof Promise ? yield result : result;
+        });
+    }
+    /**
+     * 默认错误消息
+     */
+    defaultMessage(args) {
+        // 优先使用 i18n
+        return (0, nestjs_i18n_1.i18nValidationMessage)('validation.CUSTOM_VALIDATE')(args);
+    }
+};
+exports.CustomValidateValidator = CustomValidateValidator;
+exports.CustomValidateValidator = CustomValidateValidator = __decorate([
+    (0, common_1.Injectable)(),
+    (0, class_validator_1.ValidatorConstraint)({ name: 'customValidate', async: true }),
+    __metadata("design:paramtypes", [core_1.ModuleRef])
+], CustomValidateValidator);
+/**
+ * @CustomValidate 装饰器
+ *
+ * 支持多种验证方式的灵活验证装饰器
+ *
+ * @example
+ *
+ * // 1. 内联函数（同步）
+ * @CustomValidate(
+ *   (value) => value > 0,
+ *   { message: '价格必须大于0' }
+ * )
+ * price: number;
+ *
+ * @example
+ * // 2. 内联函数（异步）
+ * @CustomValidate(
+ *   async (value, context) => {
+ *     const response = await fetch(`/api/check/${value}`);
+ *     return response.ok;
+ *   }
+ * )
+ * username: string;
+ *
+ * @example
+ * // 3. Entity 方法
+ * @CustomValidate('validateVersion')
+ * version: string;
+ *
+ * validateVersion(value: string): boolean {
+ *   return /^\d+\.\d+\.\d+$/.test(value);
+ * }
+ *
+ * @example
+ * // 4. Service 方法
+ * @CustomValidate([UserValidationService, 'checkUsername'])
+ * username: string;
+ *
+ * @example
+ * // 5. 延迟引用（解决循环依赖）
+ * @CustomValidate([() => UserValidationService, 'checkUsername'])
+ * username: string;
+ *
+ * @example
+ * // 6. 带额外参数
+ * @CustomValidate(
+ *   [ValidationService, 'checkRange', 0, 100],
+ *   { message: '价格必须在 0-100 之间' }
+ * )
+ * price: number;
+ *
+ * @example
+ * // 7. 使用 i18n
+ * @CustomValidate(
+ *   (value) => value.length >= 6,
+ *   { message: 'validation.PASSWORD_TOO_SHORT' }
+ * )
+ * password: string;
+ *
+ * @param constraint 验证约束（函数、方法名、或 [Service, 方法名]）
+ * @param validationOptions 验证选项
+ */
+function CustomValidate(constraint, validationOptions) {
+    return (object, propertyName) => {
+        (0, class_validator_1.registerDecorator)({
+            target: object.constructor,
+            propertyName,
+            options: validationOptions,
+            constraints: [constraint],
+            validator: CustomValidateValidator,
+        });
+    };
+}

package/validators/index.d.ts

@@ -4,3 +4,5 @@ export * from './file-mimetype.validator';
 export * from './is-exists.validator';
 export * from './is-unique.validator';
 export * from './same-as.validator';
+export * from './custom-validate.validator';
+export * from './common-validators';

package/validators/index.js

@@ -20,3 +20,5 @@ __exportStar(require("./file-mimetype.validator"), exports);
 __exportStar(require("./is-exists.validator"), exports);
 __exportStar(require("./is-unique.validator"), exports);
 __exportStar(require("./same-as.validator"), exports);
+__exportStar(require("./custom-validate.validator"), exports);
+__exportStar(require("./common-validators"), exports);

package/validators/is-exists.validator.d.ts

@@ -1,14 +1,28 @@
 import type { ValidationArguments, ValidationOptions, ValidatorConstraintInterface } from 'class-validator';
 import type { EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
-import { DataSource } from 'typeorm';
+import { TransactionHost } from '@nestjs-cls/transactional';
+import { TransactionalAdapterTypeOrm } from '@nestjs-cls/transactional-adapter-typeorm';
 export declare class IsExistsValidator implements ValidatorConstraintInterface {
-    private readonly dataSource;
-    constructor(dataSource: DataSource);
+    private readonly transactionHost;
+    constructor(transactionHost: TransactionHost<TransactionalAdapterTypeOrm>);
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
+    private resolveEntity;
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
+    private inferEntityNameFromProperty;
     validate<E>(value: string, args: IExistsValidationArguments<E>): Promise<boolean>;
     defaultMessage(args: ValidationArguments): string;
 }
 type ExistsValidationConstraints<E> = [
-    ObjectType<E> | EntitySchema<E> | string,
+    ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string),
     (validationArguments: ValidationArguments) => FindOptionsWhere<E>
 ];
 interface IExistsValidationArguments<E> extends ValidationArguments {

package/validators/is-exists.validator.js

@@ -21,18 +21,79 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IsExistsValidator = void 0;
 exports.IsExists = IsExists;
 const class_validator_1 = require("class-validator");
-const typeorm_1 = require("typeorm");
 const nestjs_i18n_1 = require("nestjs-i18n");
 const common_1 = require("@nestjs/common");
+const transactional_1 = require("@nestjs-cls/transactional");
 let IsExistsValidator = class IsExistsValidator {
-    constructor(dataSource) {
-        this.dataSource = dataSource;
+    constructor(transactionHost) {
+        this.transactionHost = transactionHost;
+    }
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
+    resolveEntity(entityRef, propertyName, object) {
+        // 1. 如果是字符串，直接返回（TypeORM 支持字符串）
+        if (typeof entityRef === 'string') {
+            return entityRef;
+        }
+        // 2. 如果是函数，需要区分延迟函数和 Entity 类
+        if (typeof entityRef === 'function') {
+            // 2.1 箭头函数没有 prototype，是延迟函数
+            if (!entityRef.prototype) {
+                const resolved = entityRef();
+                if (resolved)
+                    return resolved;
+            }
+            else {
+                // 2.2 有 prototype，是 Entity 类或普通构造函数
+                // 直接返回
+                return entityRef;
+            }
+        }
+        // 3. 如果是 undefined，尝试从属性名推断 Entity
+        // 例如：appId -> AppEntity, userId -> UserEntity
+        if (!entityRef) {
+            const inferredEntityName = this.inferEntityNameFromProperty(propertyName);
+            if (inferredEntityName) {
+                console.warn(`[IsExists] Entity reference is undefined for property "${propertyName}". ` +
+                    `This may be caused by circular dependencies. ` +
+                    `Consider using lazy reference: () => ${inferredEntityName}`);
+                // 返回字符串形式的 Entity 名称
+                return inferredEntityName;
+            }
+        }
+        throw new Error(`[IsExists] Cannot resolve entity reference for property "${propertyName}". ` +
+            `Entity is undefined. This is likely caused by circular dependencies. ` +
+            `Please use one of the following solutions:\n` +
+            `1. Lazy reference: @IsExists([() => EntityClass, ...])\n` +
+            `2. String reference: @IsExists(["EntityName", ...])\n` +
+            `3. Break the circular dependency`);
+    }
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
+    inferEntityNameFromProperty(propertyName) {
+        // 移除常见后缀：Id, Ids, Key, Code
+        const name = propertyName.replace(/(Id|Ids|Key|Code)$/, '');
+        if (!name)
+            return null;
+        // 转换为 PascalCase 并添加 Entity 后缀
+        const entityName = name.charAt(0).toUpperCase() + name.slice(1) + 'Entity';
+        return entityName;
     }
     validate(value, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const [entityClass, findCondition] = args.constraints;
+            const [entityRef, findCondition] = args.constraints;
+            // 解析 Entity 引用
+            const entityClass = this.resolveEntity(entityRef, args.property, args.object);
+            const repository = this.transactionHost.tx.getRepository(entityClass);
             args.value = value;
-            return ((yield this.dataSource.getRepository(entityClass).count({
+            return ((yield repository.count({
                 where: findCondition(args),
             })) > 0);
         });
@@ -45,7 +106,7 @@ exports.IsExistsValidator = IsExistsValidator;
 exports.IsExistsValidator = IsExistsValidator = __decorate([
     (0, common_1.Injectable)(),
     (0, class_validator_1.ValidatorConstraint)({ name: 'isExists', async: true }),
-    __metadata("design:paramtypes", [typeorm_1.DataSource])
+    __metadata("design:paramtypes", [transactional_1.TransactionHost])
 ], IsExistsValidator);
 function IsExists(constraints, validationOptions) {
     return (object, propertyName) => {

package/validators/is-unique.validator.d.ts

@@ -1,14 +1,41 @@
 import type { ValidationArguments, ValidationOptions, ValidatorConstraintInterface } from 'class-validator';
-import { DataSource, EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
+import { EntitySchema, FindOptionsWhere, ObjectType } from 'typeorm';
+import { TransactionHost } from '@nestjs-cls/transactional';
+import { TransactionalAdapterTypeOrm } from '@nestjs-cls/transactional-adapter-typeorm';
 export declare class IsUniqueValidator implements ValidatorConstraintInterface {
-    private readonly dataSource;
-    constructor(dataSource: DataSource);
+    private readonly transactionHost;
+    constructor(transactionHost: TransactionHost<TransactionalAdapterTypeOrm>);
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
+    private resolveEntity;
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
+    private inferEntityNameFromProperty;
     validate<E>(value: string, args: IUniqueValidationArguments<E>): Promise<boolean>;
     defaultMessage(args: ValidationArguments): string;
 }
+/**
+ * IsUnique 配置选项
+ */
+export interface IsUniqueOptions {
+    /**
+     * 手动指定用于判断是否为新建的字段名
+     * 适用于视图（View）等没有主键的场景
+     * 例如：uniqueKeys: ['id'] 或 uniqueKeys: ['id', 'version']
+     */
+    uniqueKeys?: string[];
+}
 type UniqueValidationConstraints<E> = [
-    ObjectType<E> | EntitySchema<E> | string,
-    (validationArguments: ValidationArguments) => FindOptionsWhere<E>
+    ObjectType<E> | EntitySchema<E> | string | (() => ObjectType<E> | EntitySchema<E> | string),
+    (validationArguments: ValidationArguments) => FindOptionsWhere<E>,
+    IsUniqueOptions?
 ];
 interface IUniqueValidationArguments<E> extends ValidationArguments {
     constraints: UniqueValidationConstraints<E>;

package/validators/is-unique.validator.js

@@ -21,48 +21,129 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IsUniqueValidator = void 0;
 exports.IsUnique = IsUnique;
 const class_validator_1 = require("class-validator");
-const typeorm_1 = require("typeorm");
 const nestjs_i18n_1 = require("nestjs-i18n");
+const common_1 = require("@nestjs/common");
+const transactional_1 = require("@nestjs-cls/transactional");
 let IsUniqueValidator = class IsUniqueValidator {
-    constructor(dataSource) {
-        this.dataSource = dataSource;
+    constructor(transactionHost) {
+        this.transactionHost = transactionHost;
+    }
+    /**
+     * 解析 Entity 引用，支持多种形式：
+     * 1. Entity 类直接引用
+     * 2. 延迟函数 () => Entity
+     * 3. 字符串名称 "EntityName"
+     * 4. undefined (从属性名自动推断)
+     */
+    resolveEntity(entityRef, propertyName, object) {
+        // 1. 如果是字符串，直接返回（TypeORM 支持字符串）
+        if (typeof entityRef === 'string') {
+            return entityRef;
+        }
+        // 2. 如果是函数，需要区分延迟函数和 Entity 类
+        if (typeof entityRef === 'function') {
+            // 2.1 箭头函数没有 prototype，是延迟函数
+            if (!entityRef.prototype) {
+                const resolved = entityRef();
+                if (resolved)
+                    return resolved;
+            }
+            else {
+                // 2.2 有 prototype，是 Entity 类或普通构造函数
+                // 直接返回
+                return entityRef;
+            }
+        }
+        // 3. 如果是 undefined，尝试从属性名推断 Entity
+        if (!entityRef) {
+            const inferredEntityName = this.inferEntityNameFromProperty(propertyName);
+            if (inferredEntityName) {
+                console.warn(`[IsUnique] Entity reference is undefined for property "${propertyName}". ` +
+                    `This may be caused by circular dependencies. ` +
+                    `Consider using lazy reference: () => ${inferredEntityName}`);
+                return inferredEntityName;
+            }
+        }
+        throw new Error(`[IsUnique] Cannot resolve entity reference for property "${propertyName}". ` +
+            `Entity is undefined. This is likely caused by circular dependencies. ` +
+            `Please use one of the following solutions:\n` +
+            `1. Lazy reference: @IsUnique([() => EntityClass, ...])\n` +
+            `2. String reference: @IsUnique(["EntityName", ...])\n` +
+            `3. Break the circular dependency`);
+    }
+    /**
+     * 从属性名推断 Entity 名称
+     * 例如：appId -> App, userId -> User
+     */
+    inferEntityNameFromProperty(propertyName) {
+        const name = propertyName.replace(/(Id|Ids|Key|Code)$/, '');
+        if (!name)
+            return null;
+        const entityName = name.charAt(0).toUpperCase() + name.slice(1) + 'Entity';
+        return entityName;
     }
     validate(value, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const [entityClass, findCondition] = args.constraints;
+            const [entityRef, findCondition, options] = args.constraints;
+            // 解析 Entity 引用
+            const entityClass = this.resolveEntity(entityRef, args.property, args.object);
+            const repository = this.transactionHost.tx.getRepository(entityClass);
             args.value = value;
             let exists;
             const defCon = findCondition(args);
-            const pkCols = this.dataSource
-                .getMetadata(entityClass)
-                .primaryColumns.map((column) => column.propertyName);
-            const isNew = pkCols.some((pk) => args.object[pk]);
-            if (!isNew) {
+            // 获取用于判断是否为新建的字段
+            // 优先级：手动配置的 uniqueKeys > 实体主键
+            let pkCols;
+            if ((options === null || options === void 0 ? void 0 : options.uniqueKeys) && options.uniqueKeys.length > 0) {
+                // 1. 使用手动指定的字段
+                pkCols = options.uniqueKeys;
+            }
+            else {
+                // 2. 使用实体的主键
+                pkCols = repository.metadata
+                    .primaryColumns.map((column) => column.propertyName);
+            }
+            // 如果没有主键也没有 uniqueKeys，使用简化逻辑
+            // 查询条件本身表示唯一性，只要存在记录就不允许
+            if (pkCols.length === 0) {
+                const count = yield repository.count({ where: defCon });
+                exists = count < 1;
+                return exists;
+            }
+            // 修复：检查是否为新建记录
+            // 如果所有 uniqueKeys/主键都没有值（null/undefined），则为新建
+            const isNew = !pkCols.some((pk) => {
+                const pkValue = args.object[pk];
+                return pkValue !== null && pkValue !== undefined && pkValue !== '';
+            });
+            if (isNew) {
+                // 新建场景：简单检查是否存在相同值的记录
                 exists =
-                    (yield this.dataSource
-                        .getRepository(entityClass)
+                    (yield repository
                         .count({ where: defCon })) < 1;
             }
             else {
-                const entities = yield this.dataSource
-                    .getRepository(entityClass)
+                // 更新场景：需要排除当前记录（通过主键对比）
+                const entities = yield repository
                     .createQueryBuilder()
                     .where(defCon)
-                    .select(pkCols)
                     .limit(2)
-                    .execute();
+                    .getMany();
                 const entityCount = entities.length;
                 if (entityCount === 1) {
+                    // 只有一条记录，检查是否是当前记录本身
                     const entity = entities[0];
                     const oldPk = {};
                     const newPk = {};
-                    pkCols.map((pk) => {
+                    pkCols.forEach((pk) => {
                         oldPk[pk] = entity[pk];
                         newPk[pk] = args.object[pk];
                     });
+                    // 如果主键相同，说明是自己，允许（唯一）
                     exists = JSON.stringify(oldPk) === JSON.stringify(newPk);
                 }
                 else {
+                    // 0条或多条记录
                     exists = entityCount < 1;
                 }
             }
@@ -75,8 +156,9 @@ let IsUniqueValidator = class IsUniqueValidator {
 };
 exports.IsUniqueValidator = IsUniqueValidator;
 exports.IsUniqueValidator = IsUniqueValidator = __decorate([
+    (0, common_1.Injectable)(),
     (0, class_validator_1.ValidatorConstraint)({ name: 'isUnique', async: true }),
-    __metadata("design:paramtypes", [typeorm_1.DataSource])
+    __metadata("design:paramtypes", [transactional_1.TransactionHost])
 ], IsUniqueValidator);
 function IsUnique(constraints, validationOptions) {
     return function (object, propertyName) {

package/validators/skip-empty.validator.d.ts

@@ -1 +1,6 @@
+/**
+ * When the value is emtpy, validation is skipped
+ * @param field
+ * @constructor
+ */
 export declare function SkipEmpty(field?: string): <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/validators/skip-empty.validator.js

@@ -5,6 +5,11 @@ const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
 const class_validator_1 = require("class-validator");
 const lodash_1 = require("lodash");
+/**
+ * When the value is emtpy, validation is skipped
+ * @param field
+ * @constructor
+ */
 function SkipEmpty(field) {
     return (0, common_1.applyDecorators)((0, swagger_1.ApiProperty)({ required: false }), (0, class_validator_1.ValidateIf)((obj, value) => {
         if (field) {

package/vault/interfaces/vault-options.interface.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Vault 认证选项
+ */
 export interface VaultAuthOptions {
     token?: string;
     roleId?: string;
@@ -5,6 +8,9 @@ export interface VaultAuthOptions {
     k8sRole?: string;
     k8sServiceAccountToken?: string;
 }
+/**
+ * Vault 配置选项
+ */
 export interface VaultOptions {
     endpoint: string;
     auth: VaultAuthOptions;
@@ -16,6 +22,9 @@ export interface VaultOptions {
     hotReloadInterval?: number;
     failOnError?: boolean;
 }
+/**
+ * Vault 配置
+ */
 export interface VaultConfig {
     enabled: boolean;
     options?: VaultOptions;

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

@@ -1,13 +1,43 @@
+/**
+ * Vault 配置加载器
+ * 负责在应用启动时从 Vault 加载配置并注入到 process.env
+ * 配置优先级: base.env < 环境.env < Vault
+ */
 export declare class VaultConfigLoader {
     private static readonly logger;
     private static vaultClient;
     private static hotReloadTimer;
+    /**
+     * 从环境变量构建 Vault 配置
+     */
     private static buildVaultOptions;
+    /**
+     * 初始化 Vault 客户端并进行认证
+     */
     private static initializeVaultClient;
+    /**
+     * 从 Vault 读取指定路径的配置
+     */
     private static readSecrets;
+    /**
+     * 加载 Vault 配置并注入到 process.env
+     * 配置优先级: base.env < 环境.env < Vault（Vault 会覆盖之前的配置）
+     */
     static loadVaultConfig(): Promise<void>;
+    /**
+     * 启动配置热更新
+     */
     private static startHotReload;
+    /**
+     * 停止热更新
+     */
     static stopHotReload(): void;
+    /**
+     * 获取 Vault 客户端（用于运行时动态读取）
+     */
     static getVaultClient(): any;
+    /**
+     * 检查 Vault 是否已连接
+     */
     static isConnected(): boolean;
 }