wok-server 0.4.13 → 0.5.0

package/dist/log/config.js

@@ -6,11 +6,15 @@ const config_1 = require("../config");
 const validation_1 = require("../validation");
 const level_1 = require("./level");
 const envConfig = (0, config_1.registerConfig)({
+    console: true,
+    format: 'text',
     file: false,
     fileDir: 'logs',
     fileMaxDays: 30,
     level: 'INFO'
 }, 'LOG', {
+    console: [(0, validation_1.notNull)()],
+    format: [(0, validation_1.notNull)()],
     file: [(0, validation_1.notNull)()],
     fileDir: [(0, validation_1.notBlank)()],
     fileMaxDays: [(0, validation_1.min)(1)],
@@ -25,5 +29,7 @@ exports.config = Object.freeze({
     file: envConfig.file,
     fileDir,
     fileMaxDays: envConfig.fileMaxDays,
-    level: (0, level_1.parseLogLevel)(level)
+    level: (0, level_1.parseLogLevel)(level),
+    console: envConfig.console,
+    format: envConfig.format
 });

package/dist/log/file.js

@@ -1,72 +1,198 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileStore = void 0;
+exports.flushLogsToFile = exports.fileStore = void 0;
 const fs_1 = require("fs");
 const promises_1 = require("fs/promises");
 const os_1 = require("os");
 const path_1 = require("path");
-const task_1 = require("../task");
 const config_1 = require("./config");
-let QUEUE = [];
+const log_1 = require("./log");
+// 日志队列
+let LOG_QUEUE = [];
+// 最大缓冲数量
+const MAX_QUEUE_SIZE = 1024;
+// 写入定时器
+let WRITE_TIMER = null;
+// 延迟写入时间（毫秒）
+const WRITE_DELAY = 100;
+// 是否已经安排了清理任务
+let CLEANUP_SCHEDULED = false;
+// 清理任务定时器
+let CLEANUP_TIMER = null;
 /**
  * 文件存储.
- * @param log
+ * @param log 日志对象
+ * @param logConfig 日志配置
  */
-function fileStore(log) {
-    QUEUE.push(log);
-    setTimeout(() => write().catch(e => console.error('Writing log file failed', e)), 0);
+function fileStore(log, logConfig) {
+    // 将日志添加到队列
+    LOG_QUEUE.push(log);
+    // 如果队列超过最大缓冲数量，立即写入
+    if (LOG_QUEUE.length >= MAX_QUEUE_SIZE) {
+        writeLogs(logConfig).catch(e => console.error('Writing log file failed', e));
+        // 在写入前检查是否需要安排清理任务
+        if (!CLEANUP_SCHEDULED) {
+            scheduleCleanupTask(logConfig);
+        }
+        return;
+    }
+    // 安排延迟写入
+    if (!WRITE_TIMER) {
+        WRITE_TIMER = setTimeout(() => {
+            WRITE_TIMER = null;
+            writeLogs(logConfig).catch(e => console.error('Writing log file failed', e));
+        }, WRITE_DELAY);
+    }
+    // 如果启用了文件存储并且还没有安排清理任务，则安排清理任务
+    if (!CLEANUP_SCHEDULED) {
+        scheduleCleanupTask(logConfig);
+    }
 }
 exports.fileStore = fileStore;
-function buildFilePath() {
-    const date = new Date();
-    let fileName = `${date.getFullYear()}-`;
-    const month = date.getMonth() + 1;
-    fileName += month.toFixed(0).padStart(2, '0');
-    fileName += '-';
+/**
+ * 根据日期构建日志文件路径
+ * @param logConfig 日志配置
+ * @param dateKey 数字键 (格式：年*10000 + 月*100 + 日)
+ * @returns 日志文件路径
+ */
+function buildFilePathByDate(logConfig, dateKey) {
+    const fileName = `${dateKey}.log`;
+    // 确保目录是绝对路径
+    let fileDir = logConfig.fileDir;
+    if (!(0, path_1.isAbsolute)(fileDir)) {
+        fileDir = (0, path_1.resolve)(process.cwd(), fileDir);
+    }
+    return (0, path_1.resolve)(fileDir, fileName);
+}
+/**
+ * 根据日期对象计算数字键
+ * @param date 日期对象
+ * @returns 数字键 (格式：年*10000 + 月*100 + 日)
+ */
+function calculateDateKey(date) {
+    const year = date.getFullYear();
+    const month = date.getMonth() + 1; // 转换为1-12
     const day = date.getDate();
-    fileName += day.toFixed(0).padStart(2, '0');
-    fileName += '.log';
-    return (0, path_1.resolve)(config_1.config.fileDir, fileName);
+    return year * 10000 + month * 100 + day;
 }
-async function write() {
-    if (!QUEUE.length) {
+/**
+ * 写入日志到文件
+ * @param logConfig 日志配置
+ */
+async function writeLogs(logConfig) {
+    if (!LOG_QUEUE.length || !logConfig.file) {
         return;
     }
-    const path = buildFilePath();
-    const dir = (0, path_1.dirname)(path);
-    if (!(0, fs_1.existsSync)(dir)) {
-        await (0, promises_1.mkdir)(dir, { recursive: true });
+    // 复制队列并清空原始队列
+    const logsToWrite = [...LOG_QUEUE];
+    LOG_QUEUE = [];
+    // 按日期对日志进行分组 - 使用数字键提升性能
+    const logsByDate = new Map();
+    logsToWrite.forEach(log => {
+        const logDate = new Date(log.time);
+        // 直接使用日期对象计算数字键
+        const dateKey = calculateDateKey(logDate);
+        const dateLogs = logsByDate.get(dateKey);
+        if (dateLogs) {
+            dateLogs.push(log);
+        }
+        else {
+            logsByDate.set(dateKey, [log]);
+        }
+    });
+    // 为每个日期组写入对应的日志文件
+    for (const [dateKey, dateLogs] of logsByDate.entries()) {
+        // 直接使用数字键构建文件路径
+        const filePath = buildFilePathByDate(logConfig, dateKey);
+        const dir = (0, path_1.dirname)(filePath);
+        // 确保目录存在
+        if (!(0, fs_1.existsSync)(dir)) {
+            await (0, promises_1.mkdir)(dir, { recursive: true });
+        }
+        // 格式化并写入该日期的所有日志
+        const lines = dateLogs
+            .map(log => (logConfig.format === 'json' ? (0, log_1.formatLogJson)(log) : (0, log_1.formatLogText)(log)))
+            .join(os_1.EOL);
+        try {
+            await (0, promises_1.appendFile)(filePath, lines);
+        }
+        catch (error) {
+            console.error(`Failed to write logs for date ${dateKey}:`, error);
+            // 继续处理下一个日期的日志，不中断整个写入过程
+        }
     }
-    const lines = QUEUE.join(os_1.EOL);
-    QUEUE = [];
-    await (0, promises_1.appendFile)(path, lines);
 }
-if (config_1.config.file) {
-    /**
-     * 清理任务.
-     */
-    (0, task_1.scheduleDailyTask)(3, 0, {
-        name: 'Log files clear',
-        async run() {
-            const files = await (0, promises_1.readdir)(config_1.config.fileDir);
-            const now = new Date().getTime();
-            for (const file of files) {
-                const dotIdx = file.indexOf('.');
-                if (dotIdx === -1) {
-                    console.warn(`Unable to process the log file: ${file}`);
-                    return;
-                }
-                const dateStr = file.substring(0, dotIdx);
-                const timestamp = Date.parse(dateStr);
-                if (isNaN(timestamp)) {
-                    console.warn(`Unable to process the log file: ${file}`);
-                    return;
-                }
-                if (timestamp + config_1.config.fileMaxDays * 24 * 3600 * 1000 < now) {
+/**
+ * 执行日志清理任务
+ * @param logConfig 日志配置
+ */
+async function performCleanupTask(logConfig) {
+    try {
+        let dir = logConfig.fileDir;
+        if (!(0, path_1.isAbsolute)(dir)) {
+            dir = (0, path_1.resolve)(process.cwd(), dir);
+        }
+        // 确保目录存在
+        if (!(0, fs_1.existsSync)(dir)) {
+            return;
+        }
+        const files = await (0, promises_1.readdir)(dir);
+        const now = new Date().getTime();
+        const maxAge = logConfig.fileMaxDays * 24 * 3600 * 1000;
+        for (const file of files) {
+            try {
+                // 获取文件的完整路径
+                const filePath = (0, path_1.resolve)(dir, file);
+                // 获取文件的最后修改时间
+                const fileStats = (0, fs_1.statSync)(filePath);
+                const lastModifiedTime = fileStats.mtime.getTime();
+                // 检查文件是否过期（最后修改时间早于最大保留天数）
+                if (lastModifiedTime + maxAge < now) {
                     console.warn(`Remove log file： ${file}`);
-                    await (0, promises_1.rm)((0, path_1.resolve)(config_1.config.fileDir, file));
+                    await (0, promises_1.rm)(filePath);
                 }
             }
+            catch (error) {
+                console.error(`Failed to process log file ${file}:`, error);
+                // 继续处理下一个文件，不中断清理过程
+                continue;
+            }
         }
-    });
+    }
+    catch (error) {
+        console.error('Error during log cleanup:', error);
+    }
+    finally {
+        // 清理完成后，重置清理任务安排状态
+        CLEANUP_SCHEDULED = false;
+    }
+}
+/**
+ * 安排日志清理任务
+ * @param logConfig 日志配置
+ */
+function scheduleCleanupTask(logConfig) {
+    CLEANUP_SCHEDULED = true;
+    // 清除现有的清理定时器
+    if (CLEANUP_TIMER) {
+        clearTimeout(CLEANUP_TIMER);
+    }
+    // 设置清理任务在一天后执行
+    const delay = 24 * 60 * 60 * 1000;
+    CLEANUP_TIMER = setTimeout(() => {
+        CLEANUP_TIMER = null;
+        performCleanupTask(logConfig).catch(e => console.error('Cleanup task failed', e));
+    }, delay);
+}
+/**
+ * 确保所有日志都被写入文件
+ * 可以在应用程序关闭时调用
+ */
+async function flushLogsToFile() {
+    if (WRITE_TIMER) {
+        clearTimeout(WRITE_TIMER);
+        WRITE_TIMER = null;
+    }
+    await writeLogs(config_1.config);
 }
+exports.flushLogsToFile = flushLogsToFile;

package/dist/log/index.js

@@ -2,11 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setLogStore = exports.getLogger = void 0;
 const tslib_1 = require("tslib");
-const os_1 = require("os");
 const config_1 = require("./config");
-const date_1 = require("./date");
 const file_1 = require("./file");
 const level_1 = require("./level");
+const log_1 = require("./log");
 const store_1 = require("./store");
 /**
  * 文件存储
@@ -14,92 +13,123 @@ const store_1 = require("./store");
 if (config_1.config.file) {
     (0, store_1.setLogStore)(file_1.fileStore);
 }
-/**
- * 输出日志
- * @param level
- * @param message
- * @param error
- */
-function log(level, message, error) {
-    if (level < config_1.config.level) {
-        return;
+class Logger {
+    prefix;
+    constructor(prefix) {
+        this.prefix = prefix;
     }
-    const date = new Date();
-    // 控制台输出日志
-    let msg = `[${(0, date_1.formatDateTime)(date)}][${level_1.LogLevel[level]}]${message}`;
-    console.log(msg);
-    if (error) {
-        console.log(error);
-    }
-    // 存储中输出日志
-    const store = (0, store_1.getLogStore)();
-    if (store) {
-        if (error) {
-            if (error.stack) {
-                msg += os_1.EOL + error.stack;
-            }
-            else if (error.message) {
-                msg += os_1.EOL + error.message;
+    /**
+     * 输出日志
+     * @param level
+     * @param message
+     * @param error
+     */
+    log(level, message, error) {
+        if (level < config_1.config.level) {
+            return;
+        }
+        const log = {
+            level,
+            content: message,
+            time: new Date(),
+            prefix: this.prefix,
+            error
+        };
+        // 控制台输出日志
+        if (config_1.config.console) {
+            // const msg = config.format === 'text' ? formatLogText(log, true) : formatLogJson(log, true)
+            // 控制台强制使用 text 格式，json 格式只在文件中输出
+            const msg = (0, log_1.formatLogText)(log, true);
+            switch (level) {
+                case level_1.LogLevel.DEBUG:
+                    console.debug(msg);
+                    break;
+                case level_1.LogLevel.INFO:
+                    console.info(msg);
+                    break;
+                case level_1.LogLevel.WARN:
+                    console.warn(msg);
+                    break;
+                case level_1.LogLevel.ERROR:
+                    console.error(msg);
+                    break;
             }
-            else {
-                msg += os_1.EOL + error;
+            if (error) {
+                console.error(error);
             }
         }
-        store(msg);
+        // 自定义存储中输出日志
+        const store = (0, store_1.getLogStore)();
+        if (store) {
+            store(log, config_1.config);
+        }
     }
-}
-const logger = Object.freeze({
     /**
      * debug 日志
      */
     debug(message) {
-        log(level_1.LogLevel.DEBUG, message);
-    },
+        this.log(level_1.LogLevel.DEBUG, message);
+    }
     isDebugEnabled() {
         return level_1.LogLevel.DEBUG >= config_1.config.level;
-    },
+    }
     /**
      * info 日志
      * @param message
      */
     info(message) {
-        log(level_1.LogLevel.INFO, message);
-    },
+        this.log(level_1.LogLevel.INFO, message);
+    }
     isInfoEnabled() {
         return level_1.LogLevel.INFO >= config_1.config.level;
-    },
+    }
     /**
      * 警告日志
      * @param message
      * @param error
      */
     warn(message, error) {
-        log(level_1.LogLevel.WARN, message, error);
-    },
+        this.log(level_1.LogLevel.WARN, message, error);
+    }
+    /**
+     * 等同于 warn
+     * @param message
+     * @param error
+     */
+    warning(message, error) {
+        this.log(level_1.LogLevel.WARN, message, error);
+    }
     isWarnEnabled() {
         return level_1.LogLevel.WARN >= config_1.config.level;
-    },
+    }
     /**
      * 错误日志
      * @param message
      * @param error
      */
     error(message, error) {
-        log(level_1.LogLevel.ERROR, message, error);
-    },
+        this.log(level_1.LogLevel.ERROR, message, error);
+    }
     isErrorEnabled() {
         return level_1.LogLevel.ERROR >= config_1.config.level;
     }
-});
+}
+const defaultLogger = new Logger();
 /**
  * 获取日志对象.
+ *
+ * @param prefix 日志前缀，如果有值，每条日志前都会加上前缀信息
  * @returns
  */
-function getLogger() {
-    return logger;
+function getLogger(prefix) {
+    if (prefix) {
+        return new Logger(prefix);
+    }
+    return defaultLogger;
 }
 exports.getLogger = getLogger;
 tslib_1.__exportStar(require("./config"), exports);
 tslib_1.__exportStar(require("./level"), exports);
+tslib_1.__exportStar(require("./log"), exports);
 var store_2 = require("./store");
 Object.defineProperty(exports, "setLogStore", { enumerable: true, get: function () { return store_2.setLogStore; } });

package/dist/log/log.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLogJson = exports.formatLogText = void 0;
+const os_1 = require("os");
+const date_1 = require("./date");
+const level_1 = require("./level");
+/**
+ * 将日志格式化为简单的文本
+ * @param log
+ * @param ignoreError 忽略异常信息
+ * @returns
+ */
+function formatLogText(log, ignoreError = false) {
+    let str = `[${(0, date_1.formatDateTime)(log.time)}][${level_1.LogLevel[log.level]}]${log.prefix ? `[${log.prefix}]` : ''}${log.content}`;
+    if (log.error && !ignoreError) {
+        if (log.error.stack) {
+            str += os_1.EOL + log.error.stack;
+        }
+        else if (log.error.message) {
+            str += os_1.EOL + log.error.message;
+        }
+        else {
+            str += os_1.EOL + log.error;
+        }
+    }
+    return str;
+}
+exports.formatLogText = formatLogText;
+/**
+ * 将日志格式化为 json
+ * @param log
+ * @param ignoreError 忽略异常信息
+ * @returns
+ */
+function formatLogJson(log, ignoreError = false) {
+    let error;
+    if (log.error && !ignoreError) {
+        error = '';
+        if (log.error.stack) {
+            error += log.error.stack;
+        }
+        else if (log.error.message) {
+            error += log.error.message;
+        }
+        else {
+            error += log.error;
+        }
+    }
+    const json = { ...log };
+    delete json.error;
+    if (error) {
+        json.error = error;
+    }
+    return JSON.stringify(json);
+}
+exports.formatLogJson = formatLogJson;

package/dist/log/store.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLogStore = exports.setLogStore = void 0;
+/**
+ * 日志存储函数
+ */
 let STORE;
 /**
  * 设置日志存储.

package/dist/mysql/manager/base.js

@@ -192,6 +192,14 @@ class BaseMysqlManager {
     find(opts) {
         return this.queryWithConnection(conn => (0, ops_1.find)(this.opts.config, conn, opts));
     }
+    /**
+     * 指定字段条件查询
+     * @param opts
+     * @returns
+     */
+    findSelect(opts) {
+        return this.queryWithConnection(conn => (0, ops_1.findSelect)(this.opts.config, conn, opts));
+    }
     /**
      * 指定条件查询数量
      * @param table 表信息

package/dist/mysql/manager/ops/find.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findFirst = exports.findByIdIn = exports.find = exports.findAll = exports.findById = void 0;
+exports.findFirst = exports.findByIdIn = exports.findSelect = exports.find = exports.findAll = exports.findById = void 0;
 const criteria_1 = require("./criteria");
 const utils_1 = require("../utils");
 /**
@@ -73,6 +73,45 @@ async function find(config, conn, opts) {
     return res;
 }
 exports.find = find;
+/**
+ * 查询指定的字段，返回值类型与选择的字段有关
+ * @param onfig
+ * @param conn
+ * @param opts
+ */
+async function findSelect(config, conn, opts) {
+    let query = opts.criteria ? (0, criteria_1.buildQuery)(opts.criteria) : undefined;
+    const values = [];
+    let sql = `select ${opts.select.map(() => '??').join(',')} from ?? `;
+    values.push(...opts.select, opts.table.tableName);
+    if (query) {
+        sql += ` where ${query.sql} `;
+        values.push(...query.values);
+    }
+    // 排序
+    if (opts.orderBy && opts.orderBy.length) {
+        opts.orderBy.forEach((orderBy, idx) => {
+            const [field, sort] = orderBy;
+            if (idx == 0) {
+                sql += ` order by ?? ${sort} `;
+            }
+            else {
+                sql += ` , ?? ${sort} `;
+            }
+            values.push(field);
+        });
+    }
+    // 数量限制
+    if (opts.limit) {
+        sql += ` limit ${opts.limit} `;
+        if (opts.offset) {
+            sql += ` offset ${opts.offset}`;
+        }
+    }
+    const res = await (0, utils_1.promiseQuery)(config, conn, sql, values);
+    return res;
+}
+exports.findSelect = findSelect;
 /**
  * 根据 id 列表查询记录
  * @param connection

package/dist/mysql/manager/tx-strict.js

@@ -84,6 +84,9 @@ class MysqlStrictTxSession extends tx_1.MysqlTxSession {
     find(opts) {
         throw new exception_1.MysqlException('Prohibited to use find in a strict transaction.');
     }
+    findSelect(opts) {
+        throw new exception_1.MysqlException('Prohibited to use findSelect in a strict transaction.');
+    }
     count(table, criteria) {
         throw new exception_1.MysqlException('Prohibited to use count in a strict transaction.');
     }

package/documentation/zh-cn/engineering.md

@@ -204,7 +204,7 @@ user/create-user.ts 示例：
 
 ```ts
 import { createJsonHandler, getMysqlManager, notBlank, length } from 'wok-server'
-import { User, tableUser } from './user.ts'
+import { User, tableUser } from './user'
 
 /**
  * 请求发送的表单信息

package/documentation/zh-cn/log.md

@@ -4,12 +4,15 @@
 
 ## 环境变量
 
-| 环境变量名称      | 默认值 | 说明                                                                     |
-| :---------------- | :----- | :----------------------------------------------------------------------- |
-| LOG_LEVEL         | info   | 日志级别，低于设定级别的日志将不会输出，取值：DEBUG，INFO，WARN,ERROR    |
-| LOG_FILE          | false  | 取值 true 或 false ，表示是否开启文件                                    |
-| LOG_FILE_MAX_DAYS | 30     | 数文件的保留天数                                                         |
-| LOG_FILE_DIR      | logs   | 日志文件存储路径，支持相对路径和绝对路径，相对路径是相对于进程执行目录的 |
+| 环境变量名称      | 默认值 | 说明                                                                              |
+| :---------------- | :----- | :-------------------------------------------------------------------------------- |
+| LOG_LEVEL         | info   | 日志级别，低于设定级别的日志将不会输出，取值：DEBUG，INFO，WARN,ERROR             |
+| LOG_FILE          | false  | 取值 true 或 false ，表示是否开启文件                                             |
+| LOG_FILE_MAX_DAYS | 30     | 数文件的保留天数                                                                  |
+| LOG_FILE_DIR      | logs   | 日志文件存储路径，支持相对路径和绝对路径，相对路径是相对于进程执行目录的          |
+| LOG_CONSOLE       | true   | 是否输出日志到控制台,0.5 版本新增加                                               |
+| LOG_FORMAT        | text   | 输出日志的格式，可设置为 json 或 text, 0.5 版本新增加，注意控制台是强制输出文本的 |
+
 
 ## 使用
 
@@ -24,17 +27,87 @@ const err = new Error('错误信息测试')
 logger.error('错误日志输出信息', err)
 
 if (logger.isDebugEnabled()) {
-  logger.debug('调试日志输出', JSON.stringify(args))
+  logger.debug(`调试日志输出, args: ${JSON.stringify(args)}`)
+}
+```
+
+## 判定是否支持某个日志级别
+
+日志对象提供了 isDebugEnabled、isInfoEnabled、isWarnEnabled、isErrorEnabled 方法来判定是否支持某个日志级别。
+
+```ts
+if (logger.isDebugEnabled()) {
+  logger.debug('调试日志输出')
 }
 ```
 
+这些方法的作用是判断当前是否支持某个级别，然后再做处理，如果不支持就不构建日志内容。
+一些情况下，可以避免构建日志信息所带来的不必要的开销。
+
+## 给日志增加前缀
+
+0.5 版本开始，getLogger 函数支持增加前缀，比如：
+
+```ts
+const logger = getLogger('my-module')
+```
+
+这样输出的日志会增加前缀 `[my-module]`，方便区分不同模块的日志。
+
+例如，默认无前缀的日志是这样的：
+
+```
+[2024/08/19 16:27:18.214][INFO]Mysql migration
+```
+
+增加前缀后是这样的：
+
+```
+[2024/08/19 16:27:18.214][INFO][my-module]Mysql migration
+```
+
+
 ## 自定义日志存储
 
 通过函数 setLogStore 可以自定义日志的存储，一旦设置，将会覆盖掉文件存储，即使设置了开启文件，日志也不会输出到文件中。
 
+从 0.5 版本开始，日志做了结构化，存储函数的参数是日志对象和配置信息，而不是一个字符串了。
+
+
 ```ts
-setLogStore(log => {
+setLogStore((log: Log, config: LogConfig) => {
+  // log 的类型是 Log
+  // config 的类型是 LogConfig
   // 可以根据需要将日志内容放入消息队列或独立的文件存储系统中
   messageQueue.push(log)
 })
 ```
+
+Log 的定义如下：
+
+```ts
+export interface Log {
+  /**
+   * 日志的时间
+   */
+  time: Date
+  /**
+   * 日志的等级
+   */
+  level: LogLevel
+  /**
+   * 日志的内容
+   */
+  content: string
+  /**
+   * 异常信息
+   */
+  error?: any
+  /**
+   * 前缀信息
+   */
+  prefix?: string
+}
+```
+
+LogConfig 类型则是包含了前面的环境变量配置信息，用于获取配置信息来决定如何处理日志。

package/documentation/zh-cn/mysql.md

@@ -29,7 +29,7 @@ mysql 组件基于 [mysql2](https://www.npmjs.com/package/mysql2) 封装，提
 | MYSQL_SLOW_SQL_MS             | 慢 sql 毫秒数，默认 200                               |
 | MYSQL_TRANSACTION_TIMEOUT     | 事务超时时间，单位毫秒，默认 5000                     |
 | MYSQL_TRANSACTION_STRICT      | 事务严格模式，默认 true，设置为 false 可关闭严格模式  |
-| MYSQL_MAX_OPS_IN_STRICT_TX    | 严格事务中可以执行的操作次数，默认 10  |
+| MYSQL_MAX_OPS_IN_STRICT_TX    | 严格事务中可以执行的操作次数，默认 10                 |
 
 ## 初始化
 
@@ -48,7 +48,7 @@ await enableMysql()
 await enableMysql('d2')
 ```
 
-上传的操作要激活 mysql 　时，会自动映射以 `D2_` 为前缀的环境变量。
+执行上面的操作后，会自动映射以 `D2_` 为前缀的环境变量。
 
 下面是多数据源的环境变量示例：
 
@@ -284,27 +284,28 @@ await manager.modify(`update user set nickname='无名' where nickname='佚名'`
 
 ### 所有操作方法
 
-| 方法          | 功能说明                                                                    |
-| :------------ | :-------------------------------------------------------------------------- |
-| findById      | 按 id 查询                                                                  |
-| findByIdIn    | 按 id 列表查询多条记录                                                      |
-| existsBy      | 判定指定的条件是否存在记录                                                  |
-| existsById    | 判定 id 是否存在                                                            |
-| deleteById    | 按 id 删除                                                                  |
-| deleteMany    | 按指定条件删除，危险操作，建议尽可能设置 limit 参数来限制数量               |
-| findAll       | 查询表下所有记录，危险操作，建议只对数据量非常小的表使用                    |
-| findFirst     | 查询符合条件的第一条记录                                                    |
-| insert        | 插入记录                                                                    |
-| insertMany    | 一次性插入多条记录                                                          |
-| update        | 更新记录，需要完整信息                                                      |
-| partialUpdate | 局部更新，只提供 id 和需要更新的字段信息                                    |
-| updateOne     | 只更新指定条件的第一条记录，必须是相等条件，不支持范围条件                  |
-| updateMany    | 更新所有符合条件的记录，危险操作，建议对条件严加限制，控制受影响的范围      |
-| find          | 按条件查询所有符合条件的记录，危险操作，建议尽可能设置 limit 参数来限制数量 |
-| count         | 统计符合条件的记录数量，危险操作，建议严格限制条件，注意索引的利用          |
-| paginate      | 分页查询 ，危险操作，基于 find 和 count                                     |
-| query         | 自定义 sql 查询，返回记录列表，支持预编译 sql                               |
-| modify        | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                             |
+| 方法          | 功能说明                                                                            |
+| :------------ | :---------------------------------------------------------------------------------- |
+| findById      | 按 id 查询                                                                          |
+| findByIdIn    | 按 id 列表查询多条记录                                                              |
+| existsBy      | 判定指定的条件是否存在记录                                                          |
+| existsById    | 判定 id 是否存在                                                                    |
+| deleteById    | 按 id 删除                                                                          |
+| deleteMany    | 按指定条件删除，危险操作，建议尽可能设置 limit 参数来限制数量                       |
+| findAll       | 查询表下所有记录，危险操作，建议只对数据量非常小的表使用                            |
+| findFirst     | 查询符合条件的第一条记录                                                            |
+| insert        | 插入记录                                                                            |
+| insertMany    | 一次性插入多条记录                                                                  |
+| update        | 更新记录，需要完整信息                                                              |
+| partialUpdate | 局部更新，只提供 id 和需要更新的字段信息                                            |
+| updateOne     | 只更新指定条件的第一条记录，必须是相等条件，不支持范围条件                          |
+| updateMany    | 更新所有符合条件的记录，危险操作，建议对条件严加限制，控制受影响的范围              |
+| find          | 按条件查询所有符合条件的记录，危险操作，建议尽可能设置 limit 参数来限制数量         |
+| findSelect    | 指定字段进行条件查询,与 find 唯一的不同的是多一个参数 select 可以用来指定要返回的列 |
+| count         | 统计符合条件的记录数量，危险操作，建议严格限制条件，注意索引的利用                  |
+| paginate      | 分页查询 ，危险操作，基于 find 和 count                                             |
+| query         | 自定义 sql 查询，返回记录列表，支持预编译 sql                                       |
+| modify        | 执行自定义 sql，返回操作记录数 ，支持预编译 sql                                     |
 
 ### json 类型
 

package/documentation/zh-cn/validate.md

@@ -20,8 +20,8 @@ validate(
 
 | 函数        | 作用                                                 |
 | :---------- | :--------------------------------------------------- |
-| notNull     | 非空校验，不能是 null 或 undefinded                  |
-| notBlank    | 字符非空校验，不能是 null 或 undefinded 或空白字符串 |
+| notNull     | 非空校验，不能是 null 或 undefined                    |
+| notBlank    | 字符非空校验，不能是 null 或 undefined 或空白字符串 |
 | min         | 校验数字最小值                                       |
 | max         | 校验数字最大值                                       |
 | length      | 校验长度，适用于字符串和数组                         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.4.13",
+  "version": "0.5.0",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {

package/types/log/config.d.ts

@@ -3,6 +3,14 @@ import { LogLevel } from './level';
  * 日志配置的定义
  */
 interface EnvConfig {
+    /**
+     * 是否输出日志到控制台
+     */
+    console: boolean;
+    /**
+     * 输出日志的格式
+     */
+    format: 'text' | 'json';
     /**
      * 是否输出到文件，如果为 true ，则会在根目录下生成 logs 目录存放日志文件.
      */

package/types/log/file.d.ts

@@ -1,5 +1,13 @@
+import { LogConfig } from './config';
+import { Log } from './log';
 /**
  * 文件存储.
- * @param log
+ * @param log 日志对象
+ * @param logConfig 日志配置
  */
-export declare function fileStore(log: string): void;
+export declare function fileStore(log: Log, logConfig: LogConfig): void;
+/**
+ * 确保所有日志都被写入文件
+ * 可以在应用程序关闭时调用
+ */
+export declare function flushLogsToFile(): Promise<void>;

package/types/log/index.d.ts

@@ -1,8 +1,13 @@
-/**
- * 获取日志对象.
- * @returns
- */
-export declare function getLogger(): Readonly<{
+declare class Logger {
+    private prefix?;
+    constructor(prefix?: string | undefined);
+    /**
+     * 输出日志
+     * @param level
+     * @param message
+     * @param error
+     */
+    private log;
     /**
      * debug 日志
      */
@@ -20,6 +25,12 @@ export declare function getLogger(): Readonly<{
      * @param error
      */
     warn(message: string, error?: any): void;
+    /**
+     * 等同于 warn
+     * @param message
+     * @param error
+     */
+    warning(message: string, error?: any): void;
     isWarnEnabled(): boolean;
     /**
      * 错误日志
@@ -28,7 +39,15 @@ export declare function getLogger(): Readonly<{
      */
     error(message: string, error?: any): void;
     isErrorEnabled(): boolean;
-}>;
+}
+/**
+ * 获取日志对象.
+ *
+ * @param prefix 日志前缀，如果有值，每条日志前都会加上前缀信息
+ * @returns
+ */
+export declare function getLogger(prefix?: string): Logger;
 export * from './config';
 export * from './level';
+export * from './log';
 export { setLogStore } from './store';

package/types/log/log.d.ts

@@ -0,0 +1,40 @@
+import { LogLevel } from './level';
+/**
+ * 单条日志的信息
+ */
+export interface Log {
+    /**
+     * 日志的时间
+     */
+    time: Date;
+    /**
+     * 日志的等级
+     */
+    level: LogLevel;
+    /**
+     * 日志的内容
+     */
+    content: string;
+    /**
+     * 异常信息
+     */
+    error?: any;
+    /**
+     * 前缀信息
+     */
+    prefix?: string;
+}
+/**
+ * 将日志格式化为简单的文本
+ * @param log
+ * @param ignoreError 忽略异常信息
+ * @returns
+ */
+export declare function formatLogText(log: Log, ignoreError?: boolean): string;
+/**
+ * 将日志格式化为 json
+ * @param log
+ * @param ignoreError 忽略异常信息
+ * @returns
+ */
+export declare function formatLogJson(log: Log, ignoreError?: boolean): string;

package/types/log/store.d.ts

@@ -1,8 +1,15 @@
+import { LogConfig } from './config';
+import { Log } from './log';
 /**
  * 日志存储函数
  */
 export interface LogStore {
-    (log: string): void;
+    /**
+     * 日志存储函数
+     * @param log 日志
+     * @param config 日志配置
+     */
+    (log: Log, config: LogConfig): void;
 }
 /**
  * 设置日志存储.

package/types/mysql/manager/base.d.ts

@@ -1,7 +1,7 @@
 import { Pool, PoolConnection } from 'mysql2';
 import { MysqlConfig } from '../config';
 import { Table } from '../table-info';
-import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater } from './ops';
+import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater, FindSelectOpts } from './ops';
 /**
  * mysql 管理器基类，提供基础的操作方法.
  */
@@ -129,6 +129,12 @@ export declare abstract class BaseMysqlManager {
      * @returns
      */
     find<T>(opts: FindOpts<T>): Promise<T[]>;
+    /**
+     * 指定字段条件查询
+     * @param opts
+     * @returns
+     */
+    findSelect<T, K extends keyof T>(opts: FindSelectOpts<T, K>): Promise<Pick<T, K>[]>;
     /**
      * 指定条件查询数量
      * @param table 表信息

package/types/mysql/manager/ops/find.d.ts

@@ -48,6 +48,22 @@ export interface FindOpts<T> {
  * @returns
  */
 export declare function find<T>(config: MysqlConfig, conn: PoolConnection, opts: FindOpts<T>): Promise<T[]>;
+/**
+ * 指定字段条件查询选项
+ */
+export interface FindSelectOpts<T, K extends keyof T> extends FindOpts<T> {
+    /**
+     * 要查询的字段
+     */
+    select: K[];
+}
+/**
+ * 查询指定的字段，返回值类型与选择的字段有关
+ * @param onfig
+ * @param conn
+ * @param opts
+ */
+export declare function findSelect<T, K extends keyof T>(config: MysqlConfig, conn: PoolConnection, opts: FindSelectOpts<T, K>): Promise<Array<Pick<T, K>>>;
 /**
  * 根据 id 列表查询记录
  * @param connection

package/types/mysql/manager/tx-strict.d.ts

@@ -2,7 +2,7 @@ import { PoolConnection } from 'mysql2';
 import { MysqlConfig } from '../config';
 import { MysqlTxSession } from './tx';
 import { Table } from '../table-info';
-import { DeleteManyOpts, FindOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater } from './ops';
+import { DeleteManyOpts, FindOpts, FindSelectOpts, MixCriteria, MysqlPage, MysqlPaginateOpts, UpdateOpts, Updater } from './ops';
 /**
  * 严格 mysql 事务会话，会禁用一些操作.
  */
@@ -28,6 +28,7 @@ export declare class MysqlStrictTxSession extends MysqlTxSession {
     }>): Promise<boolean>;
     partialUpdate<T>(table: Table<T>, data: Updater<T>): Promise<boolean>;
     find<T>(opts: FindOpts<T>): Promise<T[]>;
+    findSelect<T, K extends keyof T>(opts: FindSelectOpts<T, K>): Promise<Pick<T, K>[]>;
     count<T>(table: Table<T>, criteria?: MixCriteria<T> | undefined): Promise<number>;
     paginate<T>(opts: MysqlPaginateOpts<T>): Promise<MysqlPage<T>>;
     query<T>(sql: string, values?: any[] | undefined): Promise<T[]>;