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

package/dist/file-upload/utils/filename.util.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNameUtil = void 0;
+const path = require("path");
+/**
+ * 文件名处理工具类
+ * 统一管理文件名的编码、清理、截取等操作
+ */
+class FileNameUtil {
+    /**
+     * 解码并标准化文件名
+     * 1. Multer 默认使用 Latin1 解码，需要转换为 UTF-8
+     * 2. 移除特殊字符和控制字符
+     * 3. 截取超长文件名到指定长度
+     *
+     * @param filename 原始文件名
+     * @param maxLength 最大长度（默认 100 字符）
+     * @returns 处理后的文件名
+     */
+    static decodeAndNormalize(filename, maxLength = 100) {
+        if (!filename) {
+            return 'unknown';
+        }
+        let decoded;
+        // 尝试从 Latin1 转换（这是 Multer 的常见情况）
+        try {
+            const buffer = Buffer.from(filename, 'latin1');
+            decoded = buffer.toString('utf8');
+            // 检查转换结果是否包含 UTF-8 替换字符（表示可能有乱码）
+            if (!decoded.includes('\uFFFD') && this.hasValidCharacters(decoded)) {
+                // 转换成功且看起来有效
+            }
+            else {
+                // 可能不是 Latin1 编码，保持原始字符串
+                decoded = filename;
+            }
+        }
+        catch (_a) {
+            // 转换失败，保持原始字符串
+            decoded = filename;
+        }
+        // 移除不可见控制字符（但保留换行符）
+        decoded = decoded.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F-\x9F]/g, '');
+        // 移除常见乱码字符（替换符）
+        decoded = decoded.replace(/\uFFFD/g, '');
+        // 移除前后空格
+        decoded = decoded.trim();
+        // 截取长度（按字符数，不是字节数）
+        if (decoded.length > maxLength) {
+            return this.truncateWithExtension(decoded, maxLength);
+        }
+        return decoded;
+    }
+    /**
+     * 智能截取文件名（保留扩展名）
+     *
+     * @param filename 文件名
+     * @param maxLength 最大长度
+     * @returns 截取后的文件名
+     */
+    static truncateWithExtension(filename, maxLength) {
+        // 如果文件名长度不超过限制，直接返回
+        if (filename.length <= maxLength) {
+            return filename;
+        }
+        // 保留文件扩展名
+        const extMatch = filename.match(/\.[^.]+$/);
+        const ext = extMatch ? extMatch[0] : '';
+        const nameWithoutExt = ext ? filename.slice(0, -ext.length) : filename;
+        // 如果没有扩展名，直接截断到指定长度
+        if (!ext) {
+            return filename.slice(0, maxLength);
+        }
+        // 计算可用的文件名长度
+        const availableLength = maxLength - ext.length - 3; // 预留 3 个字符用于 "..."
+        if (availableLength > 0) {
+            return nameWithoutExt.slice(0, availableLength) + '...' + ext;
+        }
+        else {
+            // 如果扩展名本身就超过限制，直接截取
+            return filename.slice(0, maxLength);
+        }
+    }
+    /**
+     * 清理文件名（移除危险字符）
+     * 移除路径遍历、路径分隔符、控制字符等
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitize(filename) {
+        // 移除路径遍历字符
+        let sanitized = filename.replace(/\.\./g, '');
+        // 移除路径分隔符
+        sanitized = sanitized.replace(/[\/\\]/g, '');
+        // 移除控制字符
+        sanitized = sanitized.replace(/[\x00-\x1f\x80-\x9f]/g, '');
+        // 保留空格，只替换其他特殊字符
+        sanitized = sanitized.replace(/[^a-zA-Z0-9.\-_\s\u4e00-\u9fa5]/g, '_');
+        // 移除前导/尾随空格和点
+        sanitized = sanitized
+            .trim()
+            .replace(/^\.+|\.+$/g, '')
+            .replace(/^_+|_+$/g, '');
+        return sanitized;
+    }
+    /**
+     * 清理并保留原始文件名结构
+     * 先解码 UTF-8，再清理危险字符
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitizeOriginal(filename) {
+        // 1. 解码 UTF-8
+        const decoded = this.decodeAndNormalize(filename);
+        // 2. 移除路径遍历字符
+        let sanitized = decoded.replace(/\.\./g, '');
+        sanitized = sanitized.replace(/[\/\\]/g, '');
+        // 3. 移除控制字符
+        sanitized = sanitized.replace(/[\x00-\x1f\x80-\x9f]/g, '');
+        // 4. 移除前导/尾随空格和点
+        sanitized = sanitized.trim().replace(/^\.+|\.+$/g, '');
+        return sanitized;
+    }
+    /**
+     * 提取文件扩展名
+     *
+     * @param filename 文件名
+     * @returns 扩展名（包含点）或空字符串
+     */
+    static extractExtension(filename) {
+        const lastDotIndex = filename.lastIndexOf('.');
+        // 如果没有点、点是第一个字符（隐藏文件）、或点是最后一个字符
+        if (lastDotIndex === -1 ||
+            lastDotIndex === 0 ||
+            lastDotIndex === filename.length - 1) {
+            return '';
+        }
+        return filename.substring(lastDotIndex);
+    }
+    /**
+     * 获取不包含扩展名的文件名
+     *
+     * @param filename 文件名
+     * @returns 不包含扩展名的文件名
+     */
+    static getBaseName(filename) {
+        return path.basename(filename, this.extractExtension(filename));
+    }
+    /**
+     * 检查字符串是否包含有效的字符
+     */
+    static hasValidCharacters(str) {
+        // 如果字符串太短，无法判断
+        if (str.length === 0)
+            return true;
+        // 计算有效字符的比例
+        let validCount = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str[i];
+            const code = char.charCodeAt(0);
+            // ASCII 可打印字符
+            if (code >= 0x20 && code <= 0x7e) {
+                validCount++;
+            }
+            // 基本拉丁字母扩展
+            else if (code >= 0xa0 && code <= 0xff) {
+                validCount++;
+            }
+            // 中文、日文、韩文等 CJK 字符
+            else if (code >= 0x4e00 && code <= 0x9fff) {
+                validCount++;
+            }
+            // 其他 Unicode 字符
+            else if (code > 0xff) {
+                validCount++;
+            }
+        }
+        // 如果超过 70% 的字符是有效的，认为是有效的字符串
+        return validCount / str.length > 0.7;
+    }
+}
+exports.FileNameUtil = FileNameUtil;

package/dist/file-upload/utils/filepath.util.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 文件路径处理工具类
+ * 统一管理文件上传路径、相对路径转换等操作
+ */
+export declare class FilePathUtil {
+    /**
+     * 获取上传根目录
+     * 优先使用环境变量 FILE_UPLOAD_PATH，否则使用 process.cwd()/uploads
+     *
+     * @returns 上传根目录的绝对路径
+     */
+    static getUploadDir(): string;
+    /**
+     * 生成日期子目录格式 (YYYY/MM/DD)
+     *
+     * @returns 日期子目录路径
+     */
+    static getDateSubdirectory(): string;
+    /**
+     * 获取完整的上传目录（包含日期子目录）
+     *
+     * @returns 完整的上传目录路径
+     */
+    static getFullUploadPath(): string;
+    /**
+     * 将绝对路径转换为相对路径（相对于上传根目录）
+     * 例如: /Users/.../uploads/2025/11/30/xxx.txt -> 2025/11/30/xxx.txt
+     *
+     * @param absolutePath 绝对路径
+     * @returns 相对路径
+     */
+    static toRelativePath(absolutePath: string): string;
+    /**
+     * 将相对路径转换为绝对路径（物理路径）
+     * 例如: 2025/11/30/xxx.txt -> /Users/.../uploads/2025/11/30/xxx.txt
+     *
+     * @param relativePath 相对路径
+     * @returns 绝对路径
+     */
+    static toAbsolutePath(relativePath: string): string;
+    /**
+     * 规范化路径（统一使用正斜杠）
+     *
+     * @param filePath 文件路径
+     * @returns 规范化后的路径
+     */
+    static normalize(filePath: string): string;
+    /**
+     * 检查路径是否为绝对路径
+     *
+     * @param filePath 文件路径
+     * @returns 是否为绝对路径
+     */
+    static isAbsolute(filePath: string): boolean;
+    /**
+     * 检查文件是否存在
+     *
+     * @param filePath 文件路径（绝对或相对）
+     * @returns 文件是否存在
+     */
+    static exists(filePath: string): boolean;
+    /**
+     * 获取文件的物理路径（用于文件系统访问）
+     *
+     * @param relativePath 相对路径
+     * @param storageProvider 存储提供商
+     * @returns 物理路径或相对路径（对象存储）
+     */
+    static getPhysicalPath(relativePath: string, storageProvider?: string): string;
+}

package/dist/file-upload/utils/filepath.util.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilePathUtil = void 0;
+const path = require("path");
+const fs = require("fs");
+/**
+ * 文件路径处理工具类
+ * 统一管理文件上传路径、相对路径转换等操作
+ */
+class FilePathUtil {
+    /**
+     * 获取上传根目录
+     * 优先使用环境变量 FILE_UPLOAD_PATH，否则使用 process.cwd()/uploads
+     *
+     * @returns 上传根目录的绝对路径
+     */
+    static getUploadDir() {
+        const uploadPath = process.env.FILE_UPLOAD_PATH || path.join(process.cwd(), 'uploads');
+        // 确保目录存在
+        if (!fs.existsSync(uploadPath)) {
+            fs.mkdirSync(uploadPath, { recursive: true });
+        }
+        return uploadPath;
+    }
+    /**
+     * 生成日期子目录格式 (YYYY/MM/DD)
+     *
+     * @returns 日期子目录路径
+     */
+    static getDateSubdirectory() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const day = String(now.getDate()).padStart(2, '0');
+        return path.join(String(year), month, day);
+    }
+    /**
+     * 获取完整的上传目录（包含日期子目录）
+     *
+     * @returns 完整的上传目录路径
+     */
+    static getFullUploadPath() {
+        const basePath = this.getUploadDir();
+        const subDir = this.getDateSubdirectory();
+        const fullPath = path.join(basePath, subDir);
+        // 确保目录存在
+        if (!fs.existsSync(fullPath)) {
+            fs.mkdirSync(fullPath, { recursive: true });
+        }
+        return fullPath;
+    }
+    /**
+     * 将绝对路径转换为相对路径（相对于上传根目录）
+     * 例如: /Users/.../uploads/2025/11/30/xxx.txt -> 2025/11/30/xxx.txt
+     *
+     * @param absolutePath 绝对路径
+     * @returns 相对路径
+     */
+    static toRelativePath(absolutePath) {
+        if (!absolutePath) {
+            return '';
+        }
+        const uploadDir = this.getUploadDir();
+        // 方法1: 使用 startsWith 精确匹配
+        if (absolutePath.startsWith(uploadDir)) {
+            return absolutePath.substring(uploadDir.length).replace(/^[\/\\]+/, '');
+        }
+        // 方法2: 兼容处理 - 如果包含 /uploads/，从该位置开始截取
+        if (absolutePath.includes('/uploads/')) {
+            const uploadIndex = absolutePath.indexOf('/uploads/');
+            return absolutePath.substring(uploadIndex + '/uploads/'.length);
+        }
+        // 方法3: 兼容 Windows 路径
+        if (absolutePath.includes('\\uploads\\')) {
+            const uploadIndex = absolutePath.indexOf('\\uploads\\');
+            return absolutePath
+                .substring(uploadIndex + '\\uploads\\'.length)
+                .replace(/\\/g, '/');
+        }
+        // 如果都不匹配，返回原路径
+        return absolutePath;
+    }
+    /**
+     * 将相对路径转换为绝对路径（物理路径）
+     * 例如: 2025/11/30/xxx.txt -> /Users/.../uploads/2025/11/30/xxx.txt
+     *
+     * @param relativePath 相对路径
+     * @returns 绝对路径
+     */
+    static toAbsolutePath(relativePath) {
+        if (!relativePath) {
+            return '';
+        }
+        const uploadDir = this.getUploadDir();
+        return path.join(uploadDir, relativePath);
+    }
+    /**
+     * 规范化路径（统一使用正斜杠）
+     *
+     * @param filePath 文件路径
+     * @returns 规范化后的路径
+     */
+    static normalize(filePath) {
+        return filePath.replace(/\\/g, '/');
+    }
+    /**
+     * 检查路径是否为绝对路径
+     *
+     * @param filePath 文件路径
+     * @returns 是否为绝对路径
+     */
+    static isAbsolute(filePath) {
+        return path.isAbsolute(filePath);
+    }
+    /**
+     * 检查文件是否存在
+     *
+     * @param filePath 文件路径（绝对或相对）
+     * @returns 文件是否存在
+     */
+    static exists(filePath) {
+        const absolutePath = this.isAbsolute(filePath)
+            ? filePath
+            : this.toAbsolutePath(filePath);
+        return fs.existsSync(absolutePath);
+    }
+    /**
+     * 获取文件的物理路径（用于文件系统访问）
+     *
+     * @param relativePath 相对路径
+     * @param storageProvider 存储提供商
+     * @returns 物理路径或相对路径（对象存储）
+     */
+    static getPhysicalPath(relativePath, storageProvider = 'local') {
+        if (!relativePath) {
+            return '';
+        }
+        switch (storageProvider) {
+            case 'local':
+                return this.toAbsolutePath(relativePath);
+            case 's3':
+            case 'oss':
+            case 'minio':
+            case 'cdn':
+                // 对象存储返回相对路径，由存储服务处理
+                return relativePath;
+            default:
+                return relativePath;
+        }
+    }
+}
+exports.FilePathUtil = FilePathUtil;

package/dist/file-upload/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dynamic-import.util';
+export * from './checksum.util';
+export * from './filename.util';
+export * from './filepath.util';

package/dist/file-upload/utils/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./dynamic-import.util"), exports);
+__exportStar(require("./checksum.util"), exports);
+__exportStar(require("./filename.util"), exports);
+__exportStar(require("./filepath.util"), exports);

package/{http-client → dist/http-client}/decorators/http-client.decorators.d.ts

@@ -75,8 +75,10 @@ export declare const HttpTimeout: (timeoutMs: number) => (target: any, propertyK
  * 代理装饰器
  */
 export declare const HttpUseProxy: (options: {
-    host: string;
-    port: number;
+    enabled?: boolean;
+    fromEnvironment?: boolean;
+    host?: string;
+    port?: number;
     protocol?: "http" | "https";
     auth?: {
         username: string;

package/{http-client → dist/http-client}/decorators/http-client.decorators.js

@@ -183,7 +183,8 @@ exports.HttpTimeout = HttpTimeout;
  */
 const HttpUseProxy = (options) => {
     return (target, propertyKey, descriptor) => {
-        (0, common_1.SetMetadata)(`${exports.PROXY_OPTIONS_KEY}_${propertyKey}`, options)(descriptor.value);
+        const proxyConfig = Object.assign({ enabled: options.enabled !== false }, options);
+        (0, common_1.SetMetadata)(`${exports.PROXY_OPTIONS_KEY}_${propertyKey}`, proxyConfig)(descriptor.value);
         return descriptor;
     };
 };

package/{http-client → dist/http-client}/entities/http-log.entity.js

@@ -21,22 +21,18 @@ let HttpLogEntity = class HttpLogEntity extends common_1.AbstractUuidPrimaryEnti
 exports.HttpLogEntity = HttpLogEntity;
 __decorate([
     (0, typeorm_1.Column)({ type: 'varchar', length: 36, nullable: true }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "requestId", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'varchar', length: 36, nullable: true }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "userId", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'varchar', length: 10 }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "method", void 0);
 __decorate([
-    (0, typeorm_1.Column)({ type: 'text' }),
-    (0, typeorm_1.Index)(),
+    (0, typeorm_1.Column)({ type: 'varchar' }),
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "url", void 0);
 __decorate([
@@ -53,7 +49,6 @@ __decorate([
 ], HttpLogEntity.prototype, "params", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'int', nullable: true }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", Number)
 ], HttpLogEntity.prototype, "statusCode", void 0);
 __decorate([
@@ -66,7 +61,6 @@ __decorate([
 ], HttpLogEntity.prototype, "attemptCount", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'boolean', default: false }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", Boolean)
 ], HttpLogEntity.prototype, "success", void 0);
 __decorate([
@@ -103,7 +97,6 @@ __decorate([
 ], HttpLogEntity.prototype, "serviceName", void 0);
 __decorate([
     (0, typeorm_1.Column)({ type: 'varchar', length: 200, nullable: true }),
-    (0, typeorm_1.Index)(),
     __metadata("design:type", String)
 ], HttpLogEntity.prototype, "operationName", void 0);
 __decorate([
@@ -140,7 +133,6 @@ exports.HttpLogEntity = HttpLogEntity = __decorate([
     (0, typeorm_1.Index)(['requestId']),
     (0, typeorm_1.Index)(['userId']),
     (0, typeorm_1.Index)(['method']),
-    (0, typeorm_1.Index)(['url']),
     (0, typeorm_1.Index)(['statusCode']),
     (0, typeorm_1.Index)(['success']),
     (0, typeorm_1.Index)(['createdAt']),

package/dist/http-client/examples/proxy-from-environment.example.d.ts

@@ -0,0 +1,133 @@
+/**
+ * ProxyFromEnvironment 使用示例
+ *
+ * 本文件演示如何在 HTTP Client 中使用代理环境变量支持
+ */
+import { HttpClientService } from '@nest-omni/core';
+/**
+ * 示例 1: 使用环境变量配置代理 (推荐方式)
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export HTTPS_PROXY=https://secure-proxy.example.com:8443
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com
+ */
+export declare class ProxyFromEnvironmentExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    /**
+     * 使用装饰器从环境变量读取代理配置
+     */
+    fetchWithProxyFromEnv(): Promise<any>;
+    /**
+     * 直接配置请求时指定从环境变量读取代理
+     */
+    fetchWithConfiguredProxy(): Promise<any>;
+}
+/**
+ * 示例 2: 带认证的代理环境变量
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://username:password@proxy.example.com:8080
+ */
+export declare class ProxyWithAuthExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchWithAuthenticatedProxy(): Promise<any>;
+}
+/**
+ * 示例 3: NO_PROXY 使用示例
+ *
+ * 设置环境变量:
+ * export HTTP_PROXY=http://proxy.example.com:8080
+ * export NO_PROXY=localhost,127.0.0.1,.internal.com,.local
+ */
+export declare class NoProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchExternalApi(): Promise<any>;
+    fetchInternalApi(): Promise<any>;
+    fetchLocalhost(): Promise<any>;
+}
+/**
+ * 示例 4: 混合使用 - 部分请求使用代理，部分不使用
+ */
+export declare class MixedProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    fetchWithProxy(): Promise<any>;
+    fetchWithoutProxy(): Promise<any>;
+}
+/**
+ * 示例 5: 企业环境中的实际使用场景
+ *
+ * 在 docker-compose.yml 或 Kubernetes 配置中设置:
+ * environment:
+ *   - HTTP_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - HTTPS_PROXY=http://proxy-user:proxy-pass@corporate-proxy.company.com:8080
+ *   - NO_PROXY=localhost,127.0.0.1,.company.com,.svc.cluster.local
+ */
+export declare class EnterpriseProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    /**
+     * 访问外部 API（使用企业代理）
+     */
+    fetchFromExternalApi(): Promise<any>;
+    /**
+     * 访问内部服务（不使用代理）
+     */
+    fetchFromInternalService(): Promise<any>;
+    /**
+     * 访问 Kubernetes 集群内服务（不使用代理）
+     */
+    fetchFromK8sService(): Promise<any>;
+}
+/**
+ * 示例 6: 开发环境调试代理
+ *
+ * 本地开发时使用 Charles、Fiddler 等代理工具调试:
+ * export HTTP_PROXY=http://localhost:8888
+ * export HTTPS_PROXY=http://localhost:8888
+ */
+export declare class DevelopmentProxyExample {
+    private readonly httpClient;
+    constructor(httpClient: HttpClientService);
+    debugRequest(): Promise<any>;
+}
+/**
+ * 示例 7: 程序化检查代理配置
+ */
+export declare class ProxyUtilityExample {
+    checkProxyConfiguration(): Promise<void>;
+}
+/**
+ * 模块配置示例
+ */
+export declare const httpClientModuleConfig: {
+    globalProxyFromEnv: {
+        imports: {
+            proxy: {
+                enabled: boolean;
+                fromEnvironment: boolean;
+            };
+        }[];
+    };
+    selectiveProxy: {
+        imports: {
+            proxy: {
+                enabled: boolean;
+            };
+        }[];
+    };
+};
+/**
+ * 环境变量配置示例
+ */
+export declare const environmentVariablesExamples: {
+    basic: string;
+    withAuth: string;
+    specialChars: string;
+    enterprise: string;
+    development: string;
+};