lz-nframe 1.0.0

package/lib/NApp.d.ts

@@ -0,0 +1,13 @@
+/*******************************************************************************
+文件: NApp.ts
+创建: 2022年02月15日
+作者: 老张
+描述:
+    应用基类
+*******************************************************************************/
+import { EventEmitter } from 'events';
+export default abstract class NApp extends EventEmitter {
+    protected appName: string;
+    constructor(appName: string);
+    abstract start(): void;
+}

package/lib/NApp.js

@@ -0,0 +1,23 @@
+/*******************************************************************************
+文件: NApp.ts
+创建: 2022年02月15日
+作者: 老张
+描述:
+    应用基类
+*******************************************************************************/
+import { EventEmitter } from 'events';
+import * as fs from 'fs';
+export default class NApp extends EventEmitter {
+    constructor(appName) {
+        super();
+        this.appName = appName;
+        // 输出日志
+        console.log(`${appName} Start ${new Date()}`);
+        console.error(`${appName} Start ${new Date()}`);
+        // 捕获未处理异常
+        process.on('uncaughtException', (err) => {
+            console.error(err);
+            fs.writeFileSync('./runtime.log', err + '\n', { flag: 'a+' });
+        });
+    }
+}

package/lib/NConfigsMgr.d.ts

@@ -0,0 +1,50 @@
+/*******************************************************************************
+文件: NConfigsMgr.ts
+创建: 2022年02月05日
+作者: 老张
+描述:
+    配置文件加载、变动监视，文件修改自动重载
+    配置来源分为：
+        1.通过代码提交的【默认配置】
+        2.通过本地文件存储的【本地配置】
+        3.通过远程部署的文件进行的【动态配置】
+
+    获取配置时的顺序：【动态配置】->【本地配置】->【默认配置】
+*******************************************************************************/
+import { NestedKeyOf, ValueAtPath } from './NType';
+export default class NConfigsMgr<T extends object> {
+    get configs(): T;
+    private defaultConfigs;
+    private localConfigs;
+    private dynamicConfigs;
+    private _configs;
+    private localConfigsFile;
+    private dynamicConfigsFile;
+    private changeListener;
+    private fileWatcherHandler;
+    /**
+     * 设置配置文件
+     * @param defaultConfig 默认配置
+     * @param localConfigsFile 本地配置文件路径，可使用path.join和__dirname来合成
+     * @param dynamicConfigsFile 动态配置文件路径，可使用path.join和__dirname来合成
+     */
+    constructor(defaultConfigs: T, localConfigsFile: string, dynamicConfigsFile: string);
+    /** 监听某项配置的变化，支持子属性路径（如 'db.host'） */
+    addConfigChangeListener<K extends NestedKeyOf<T> & string>(key: K, listener: (last: ValueAtPath<T, K>, current: ValueAtPath<T, K>) => void): void;
+    /**
+     * 使用默认配置生成一个配置json模板
+     * @param outPath 模板存储路径，可使用path.join和__dirname来合成
+     */
+    createTemplateJson(outPath: string): boolean;
+    /**
+     * 释放内部文件监听器，避免测试或短生命周期场景中残留句柄导致进程无法退出
+     */
+    close(): void;
+    /** 设置属性查询器，【动态配置】->【本地配置】->【默认配置】 */
+    private setupSetter;
+    private fileWatcher;
+    /** 加载本地配置文件、动态配置文件 */
+    private loadFile;
+    /** 根据点号路径从对象中获取值 */
+    private getValueByPath;
+}

package/lib/NConfigsMgr.js

@@ -0,0 +1,162 @@
+/*******************************************************************************
+文件: NConfigsMgr.ts
+创建: 2022年02月05日
+作者: 老张
+描述:
+    配置文件加载、变动监视，文件修改自动重载
+    配置来源分为：
+        1.通过代码提交的【默认配置】
+        2.通过本地文件存储的【本地配置】
+        3.通过远程部署的文件进行的【动态配置】
+
+    获取配置时的顺序：【动态配置】->【本地配置】->【默认配置】
+*******************************************************************************/
+import * as fs from 'fs';
+import NUtils from 'lz-nutils';
+export default class NConfigsMgr {
+    get configs() {
+        return this._configs;
+    }
+    /**
+     * 设置配置文件
+     * @param defaultConfig 默认配置
+     * @param localConfigsFile 本地配置文件路径，可使用path.join和__dirname来合成
+     * @param dynamicConfigsFile 动态配置文件路径，可使用path.join和__dirname来合成
+     */
+    constructor(defaultConfigs, localConfigsFile, dynamicConfigsFile) {
+        this.changeListener = {};
+        this.defaultConfigs = NUtils.copySimple(defaultConfigs);
+        this.setupSetter();
+        this.localConfigsFile = localConfigsFile;
+        this.dynamicConfigsFile = dynamicConfigsFile;
+        this.fileWatcherHandler = this.fileWatcher.bind(this);
+        fs.watchFile(this.localConfigsFile, this.fileWatcherHandler);
+        fs.watchFile(this.dynamicConfigsFile, this.fileWatcherHandler);
+        this.loadFile(true);
+    }
+    /** 监听某项配置的变化，支持子属性路径（如 'db.host'） */
+    addConfigChangeListener(key, listener) {
+        if (this.changeListener[key] == null) {
+            this.changeListener[key] = [];
+        }
+        this.changeListener[key].push(listener);
+    }
+    /**
+     * 使用默认配置生成一个配置json模板
+     * @param outPath 模板存储路径，可使用path.join和__dirname来合成
+     */
+    createTemplateJson(outPath) {
+        try {
+            let content = JSON.stringify(this.defaultConfigs, null, 4);
+            fs.writeFileSync(outPath, content);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * 释放内部文件监听器，避免测试或短生命周期场景中残留句柄导致进程无法退出
+     */
+    close() {
+        fs.unwatchFile(this.localConfigsFile, this.fileWatcherHandler);
+        fs.unwatchFile(this.dynamicConfigsFile, this.fileWatcherHandler);
+    }
+    /** 设置属性查询器，【动态配置】->【本地配置】->【默认配置】 */
+    setupSetter() {
+        this._configs = {};
+        for (let key in this.defaultConfigs) {
+            if (!this.defaultConfigs.hasOwnProperty(key))
+                continue;
+            Object.defineProperty(this._configs, key, {
+                get: () => {
+                    if (this.dynamicConfigs && this.dynamicConfigs[key] != null)
+                        return this.dynamicConfigs[key];
+                    if (this.localConfigs && this.localConfigs[key] != null)
+                        return this.localConfigs[key];
+                    return this.defaultConfigs[key];
+                },
+                configurable: false
+            });
+        }
+    }
+    fileWatcher(current, prev) {
+        // ctime是文件stats发生变化的时间，ctime为0可以认定文件不存在
+        // mtime是文件内容修改时间
+        // 文件创建
+        if (prev.ctime.getTime() === 0 && current.ctime.getTime() !== 0) {
+            this.loadFile();
+        }
+        // 文件删除，已加载的配置不变
+        else if (current.ctime.getTime() === 0) {
+            //
+        }
+        // 文件修改了
+        else if (current.mtime.getTime() !== prev.mtime.getTime()) {
+            this.loadFile();
+        }
+    }
+    /** 加载本地配置文件、动态配置文件 */
+    loadFile(init = false) {
+        let lastConfigs = {};
+        if (!init) {
+            for (let key in this.defaultConfigs) {
+                if (!this.defaultConfigs.hasOwnProperty(key))
+                    continue;
+                lastConfigs[key] = this.configs[key];
+            }
+        }
+        // 本地配置
+        try {
+            let content = fs.readFileSync(this.localConfigsFile);
+            let json = JSON.parse(content.toString());
+            this.localConfigs = json;
+        }
+        catch (error) {
+        }
+        // 动态配置
+        try {
+            let content = fs.readFileSync(this.dynamicConfigsFile);
+            let json = JSON.parse(content.toString());
+            this.dynamicConfigs = json;
+        }
+        catch (error) {
+        }
+        // 变动检查
+        if (!init) {
+            let changedKeys = [];
+            // 检测所有注册了监听器的路径
+            for (const key of Object.keys(this.changeListener)) {
+                const lastValue = this.getValueByPath(lastConfigs, key);
+                const currentValue = this.getValueByPath(this.configs, key);
+                if (lastValue === currentValue)
+                    continue;
+                if (JSON.stringify(lastValue) !== JSON.stringify(currentValue)) {
+                    changedKeys.push({ key, last: lastValue, current: currentValue });
+                }
+            }
+            // 隔离调用
+            for (const entry of changedKeys) {
+                let listeners = this.changeListener[entry.key] || [];
+                for (let listener of listeners) {
+                    try {
+                        listener(entry.last, entry.current);
+                    }
+                    catch (error) {
+                    }
+                }
+            }
+        }
+    }
+    /** 根据点号路径从对象中获取值 */
+    getValueByPath(obj, path) {
+        const keys = path.split('.');
+        let current = obj;
+        for (const key of keys) {
+            if (current == null)
+                return undefined;
+            current = current[key];
+        }
+        return current;
+    }
+}

package/lib/NHttpClient.d.ts

@@ -0,0 +1,71 @@
+/*******************************************************************************
+文件: NHttpClient.ts
+创建: 2026年05月06日
+作者: 老张
+描述:
+    网络请求客户端 (优化版：不再强制抛错，返回统一的结果包装)
+    - 支持自动处理中文 URL 编码
+    - 支持泛型与类型安全
+*******************************************************************************/
+import * as http from 'http';
+/**
+ * 请求配置接口
+ */
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string | number>;
+    timeout?: number;
+    body?: any;
+}
+/**
+ * 统一响应包装器
+ * 成功时 error 为 null，失败时 data 为 null
+ */
+export interface ApiResult<T> {
+    success: boolean;
+    data: T | null;
+    error: {
+        message: string;
+        code?: number;
+        details?: any;
+    } | null;
+    response?: {
+        statusCode?: number;
+        headers: http.IncomingHttpHeaders;
+    };
+}
+export default class NHttpClient {
+    /**
+     * 核心请求方法
+     * 内部捕获所有异常，确保始终 resolve 一个 ApiResult 对象
+     */
+    static request<T = any>(url: string, options?: RequestOptions): Promise<ApiResult<T>>;
+    /**
+     * 获取客户端真实 IP
+     * 按优先级依次检查各类代理 header，最终回退到 socket.remoteAddress
+     */
+    static getClientIp(req: http.IncomingMessage): string;
+    static get<T = any>(url: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    /**
+     * GET 请求（自动将 params 对象拼接到 URL 作为查询参数）
+     */
+    static getWithParams<T = any>(url: string, params?: Record<string, string | number | boolean>, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    static post<T = any>(url: string, body?: any, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    /**
+     * POST 请求（表单编码 body）
+     * 自动设置 Content-Type 为 application/x-www-form-urlencoded
+     */
+    static postForm<T = any>(url: string, body: Record<string, string | number | boolean>, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    static put<T = any>(url: string, body?: any, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    /**
+     * PUT 请求（表单编码 body）
+     * 自动设置 Content-Type 为 application/x-www-form-urlencoded
+     */
+    static putForm<T = any>(url: string, body: Record<string, string | number | boolean>, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    static delete<T = any>(url: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResult<T>>;
+    /**
+     * 将普通对象编码为 application/x-www-form-urlencoded 格式字符串
+     */
+    static encodeFormBody(data: Record<string, string | number | boolean>): string;
+}
+export {};

package/lib/NHttpClient.js

@@ -0,0 +1,196 @@
+/*******************************************************************************
+文件: NHttpClient.ts
+创建: 2026年05月06日
+作者: 老张
+描述:
+    网络请求客户端 (优化版：不再强制抛错，返回统一的结果包装)
+    - 支持自动处理中文 URL 编码
+    - 支持泛型与类型安全
+*******************************************************************************/
+import * as http from 'http';
+import * as https from 'https';
+import { URL } from 'url';
+export default class NHttpClient {
+    /**
+     * 核心请求方法
+     * 内部捕获所有异常，确保始终 resolve 一个 ApiResult 对象
+     */
+    static request(url, options = {}) {
+        return new Promise((resolve) => {
+            try {
+                // 1. 处理中文 URL。直接 new URL(url) 会自动对路径部分进行合法性校验，
+                // 但为了保险，我们确保使用 URL 对象的 href 属性发送请求，它会自动处理编码。
+                const parsedUrl = new URL(url);
+                const protocol = parsedUrl.protocol === 'https:' ? https : http;
+                const requestOptions = {
+                    hostname: parsedUrl.hostname,
+                    port: parsedUrl.port || (parsedUrl.protocol === 'https:' ? 443 : 80),
+                    // 使用 URL 对象的 pathname + search 保证了中文参数被正确编码为 % 格式
+                    path: parsedUrl.pathname + parsedUrl.search,
+                    method: (options.method || 'GET').toUpperCase(),
+                    headers: options.headers || {},
+                    timeout: options.timeout || 10000,
+                };
+                let postData = null;
+                if (options.body) {
+                    if (typeof options.body === 'object') {
+                        postData = JSON.stringify(options.body);
+                        const headers = requestOptions.headers;
+                        headers['Content-Type'] = headers['Content-Type'] || 'application/json';
+                        headers['Content-Length'] = Buffer.byteLength(postData);
+                    }
+                    else {
+                        postData = String(options.body);
+                    }
+                }
+                const req = protocol.request(requestOptions, (res) => {
+                    const chunks = [];
+                    res.on('data', (chunk) => chunks.push(chunk));
+                    res.on('end', () => {
+                        const buffer = Buffer.concat(chunks);
+                        const responseString = buffer.toString();
+                        let data;
+                        const contentType = res.headers['content-type'] || '';
+                        if (contentType.includes('application/json')) {
+                            try {
+                                data = responseString ? JSON.parse(responseString) : null;
+                            }
+                            catch (e) {
+                                data = responseString;
+                            }
+                        }
+                        else {
+                            data = responseString;
+                        }
+                        const statusCode = res.statusCode || 0;
+                        const success = statusCode >= 200 && statusCode < 300;
+                        resolve({
+                            success,
+                            data: success ? data : null,
+                            error: success ? null : {
+                                message: `HTTP Error: ${statusCode}`,
+                                details: data
+                            },
+                            response: {
+                                statusCode,
+                                headers: res.headers
+                            }
+                        });
+                    });
+                });
+                req.on('error', (err) => {
+                    resolve({
+                        success: false,
+                        data: null,
+                        error: { message: err.message },
+                    });
+                });
+                req.on('timeout', () => {
+                    req.destroy();
+                    resolve({
+                        success: false,
+                        data: null,
+                        error: { message: `Request timed out after ${requestOptions.timeout}ms` },
+                    });
+                });
+                if (postData)
+                    req.write(postData);
+                req.end();
+            }
+            catch (err) {
+                // 处理 URL 解析错误（如 URL 格式不合法）
+                resolve({
+                    success: false,
+                    data: null,
+                    error: { message: `URL Parse Error: ${err.message}` },
+                });
+            }
+        });
+    }
+    /**
+     * 获取客户端真实 IP
+     * 按优先级依次检查各类代理 header，最终回退到 socket.remoteAddress
+     */
+    static getClientIp(req) {
+        var _a, _b;
+        const headers = req.headers;
+        // 安全地提取 header 值（处理 string | string[] | undefined）
+        const getHeader = (name) => {
+            const val = headers[name];
+            if (typeof val === 'string')
+                return val.trim();
+            if (Array.isArray(val) && val.length > 0)
+                return String(val[0]).trim();
+            return '';
+        };
+        // 依次检查各代理 header
+        const candidates = [
+            getHeader('x-real-ip'),
+            getHeader('cf-connecting-ip'), // Cloudflare
+            getHeader('true-client-ip'), // Akamai / Cloudflare Enterprise
+            getHeader('x-client-ip'),
+            getHeader('x-forwarded-for'), // 通用代理，可能含多个 IP
+            getHeader('proxy-client-ip'),
+            getHeader('wl-proxy-client-ip'),
+        ];
+        for (const ip of candidates) {
+            if (ip && ip.length > 0 && ip.toLowerCase() !== 'unknown') {
+                // x-forwarded-for 格式: "client, proxy1, proxy2"，取第一个
+                const first = ip.split(',')[0].trim();
+                if (first)
+                    return first;
+            }
+        }
+        // 回退到 socket 地址
+        return (_b = (_a = req.socket) === null || _a === void 0 ? void 0 : _a.remoteAddress) !== null && _b !== void 0 ? _b : 'unknown';
+    }
+    static get(url, options) {
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'GET' }));
+    }
+    /**
+     * GET 请求（自动将 params 对象拼接到 URL 作为查询参数）
+     */
+    static getWithParams(url, params, options) {
+        if (params && Object.keys(params).length > 0) {
+            const parsedUrl = new URL(url);
+            Object.entries(params).forEach(([key, value]) => {
+                parsedUrl.searchParams.append(key, String(value));
+            });
+            url = parsedUrl.toString();
+        }
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'GET' }));
+    }
+    static post(url, body, options) {
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'POST', body }));
+    }
+    /**
+     * POST 请求（表单编码 body）
+     * 自动设置 Content-Type 为 application/x-www-form-urlencoded
+     */
+    static postForm(url, body, options) {
+        const formBody = this.encodeFormBody(body);
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'POST', headers: Object.assign({ 'Content-Type': 'application/x-www-form-urlencoded' }, options === null || options === void 0 ? void 0 : options.headers), body: formBody }));
+    }
+    static put(url, body, options) {
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'PUT', body }));
+    }
+    /**
+     * PUT 请求（表单编码 body）
+     * 自动设置 Content-Type 为 application/x-www-form-urlencoded
+     */
+    static putForm(url, body, options) {
+        const formBody = this.encodeFormBody(body);
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'PUT', headers: Object.assign({ 'Content-Type': 'application/x-www-form-urlencoded' }, options === null || options === void 0 ? void 0 : options.headers), body: formBody }));
+    }
+    static delete(url, options) {
+        return this.request(url, Object.assign(Object.assign({}, options), { method: 'DELETE' }));
+    }
+    /**
+     * 将普通对象编码为 application/x-www-form-urlencoded 格式字符串
+     */
+    static encodeFormBody(data) {
+        return Object.entries(data)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+            .join('&');
+    }
+}

package/lib/NSimpleHttpServer.d.ts

@@ -0,0 +1,75 @@
+/*******************************************************************************
+文件: NSimpleHttpServer.ts
+创建: 2022年02月17日
+作者: 老张
+描述:
+    基于NodeJS内置http模块实现http(s)服务器，不需要额外的依赖包
+
+文档：
+    http模块api参考：http://nodejs.cn/api/http.html
+
+参考：
+    https://www.cnblogs.com/chuanzi/p/10507919.html
+
+示例：
+    new NSimpleHttpServer()
+        .addPage('/', (req, res) => {
+            res.write('HelloWorld\n');
+            console.log(req.socket.remoteAddress);
+            res.write('远程地址:' + req.socket.remoteAddress + '\n');
+            res.write('本地地址:' + req.socket.localAddress + '\n');
+        }, {contentType: ContentType.TextPlain})
+        .start(3000);
+*******************************************************************************/
+import * as http from 'http';
+export default class NSimpleHttpServer {
+    private server;
+    private pages;
+    /** 单次请求 body 上限（字节），超出则返回 413 */
+    private maxBodyBytes;
+    constructor(params?: {
+        maxBodyBytes?: number;
+    });
+    /** 启动服务 host如果为null那么req.socket.remoteAddress格式如::ffff:127.0.0.1 */
+    start(port: number, host?: string, onListening?: () => void): this;
+    close(): this;
+    /**
+     * 注册页面/路由
+     * @param url 路径，会做规范化（去掉尾斜杠，根路径'/'除外）
+     * @param requestDealer 请求处理函数；内部可主动调用 res.writeHead/res.end 自定义状态码
+     * @param options.contentType 响应头的 Content-Type；兼容旧 enum 整行写法与纯 MIME 写法
+     * @param options.allowCORS 开启简单 CORS，并自动应答 OPTIONS 预检
+     * @param options.method 仅允许指定 HTTP 方法（如 'POST' 或 ['GET','POST']），不传则放行所有方法
+     */
+    addPage(url: string, requestDealer: (req: http.IncomingMessage, res: http.ServerResponse, query: {
+        [key: string]: string;
+    }, body: string) => void, options?: {
+        contentType?: ContentType | string;
+        allowCORS?: boolean;
+        method?: string | string[];
+    }): this;
+    private onRequest;
+    /** 路径规范化：去掉尾部多余斜杠，但保留根路径'/' */
+    private normalizePath;
+    /**
+     * 解析 contentType 配置，同时兼容两种写法：
+     *   1) 旧 enum 整行写法（含 ':'）：'Content-Type: text/html; charset=utf-8;'
+     *   2) 纯 MIME 写法：'application/json'
+     * 修正了原实现 split(':').length===2 才生效的限制（含多冒号会被丢弃）以及尾分号问题
+     */
+    private parseContentType;
+}
+export declare enum ContentType {
+    TextHtml = "Content-Type: text/html; charset=utf-8;",
+    TextPlain = "Content-Type: text/plain; charset=utf-8;",
+    ApplicationJson = "Content-Type: application/json; charset=utf-8;"
+}
+export interface SimplePage {
+    url: string;
+    contentType?: ContentType | string;
+    allowCORS?: boolean;
+    method?: string | string[];
+    requestDealer: (req: http.IncomingMessage, res: http.ServerResponse, query: {
+        [key: string]: string;
+    }, body: string) => void;
+}