befly 3.74.2 → 3.75.0

package/lib/dbUtil.js

@@ -1,3 +1,4 @@
+import { validationError } from "../utils/error.js";
 import { isFiniteNumber, isNonEmptyString, isNullable, isString } from "../utils/is.js";
 import { snakeCase } from "../utils/util.js";
 
@@ -11,57 +12,36 @@ export function assertNoExprField(field) {
 
     const trimmed = field.trim();
     if (trimmed.includes("(") || trimmed.includes(")")) {
-        throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`);
     }
 }
 
 export function parseTableRef(tableRef) {
     if (!isString(tableRef)) {
-        throw new Error(`tableRef 必须是字符串 (tableRef: ${String(tableRef)})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`tableRef 必须是字符串 (tableRef: ${String(tableRef)})`);
     }
 
     const trimmed = tableRef.trim();
     if (!trimmed) {
-        throw new Error("tableRef 不能为空", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("tableRef 不能为空");
     }
 
     const parts = trimmed.split(/\s+/);
     if (parts.length > 2) {
-        throw new Error(`不支持的表引用格式（包含过多片段）。请使用最简形式：table 或 table alias 或 schema.table 或 schema.table alias (tableRef: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`不支持的表引用格式（包含过多片段）。请使用最简形式：table 或 table alias 或 schema.table 或 schema.table alias (tableRef: ${trimmed})`);
     }
 
     const nameSegments = parts[0].split(".");
     if (nameSegments.length > 2) {
-        throw new Error(`不支持的表引用格式（schema 层级过深） (tableRef: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`不支持的表引用格式（schema 层级过深） (tableRef: ${trimmed})`);
     }
 
     if (nameSegments.length === 2) {
         if (!nameSegments[0]) {
-            throw new Error(`tableRef 解析失败：schema 为空 (tableRef: ${trimmed})`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`tableRef 解析失败：schema 为空 (tableRef: ${trimmed})`);
         }
         if (!nameSegments[1]) {
-            throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`);
         }
 
         return {
@@ -72,10 +52,7 @@ export function parseTableRef(tableRef) {
     }
 
     if (!nameSegments[0]) {
-        throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`);
     }
 
     return {
@@ -92,7 +69,7 @@ function isQuotedIdentPaired(value) {
     }
 
     const first = trimmed[0];
-    const last = trimmed[trimmed.length - 1];
+    const last = trimmed.at(-1);
     return (first === "`" && last === "`") || (first === '"' && last === '"');
 }
 
@@ -124,10 +101,7 @@ export function parseFieldAliasParts(field) {
     }
 
     if (/\s+AS\s+/i.test(trimmed)) {
-        throw new Error(`字段别名不支持 AS，请使用单个空格分隔字段与别名 (field: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`字段别名不支持 AS，请使用单个空格分隔字段与别名 (field: ${trimmed})`);
     }
 
     if (!/\s/.test(trimmed)) {
@@ -135,10 +109,7 @@ export function parseFieldAliasParts(field) {
     }
 
     if (!/^[^\s]+ [^\s]+$/.test(trimmed)) {
-        throw new Error(`字段别名必须使用单个空格分隔字段与别名 (field: ${trimmed})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`字段别名必须使用单个空格分隔字段与别名 (field: ${trimmed})`);
     }
 
     const parts = trimmed.split(" ");
@@ -399,10 +370,7 @@ export async function fieldsToSnake(table, classified, getTableColumns) {
         const excludeSnakeFields = classified.fields.map((field) => snakeCase(field));
         const resultFields = allColumns.filter((column) => !excludeSnakeFields.includes(column));
         if (resultFields.length === 0) {
-            throw new Error(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`排除字段后没有剩余字段可查询。表: ${table}, 排除: ${excludeSnakeFields.join(", ")}`);
         }
         return resultFields;
     }
@@ -415,7 +383,7 @@ export function normalizeQualifierField(field) {
         return snakeCase(field);
     }
 
-    const fieldName = parts[parts.length - 1].trim();
+    const fieldName = parts.at(-1).trim();
     const qualifier = parts
         .slice(0, parts.length - 1)
         .map((item) => snakeCase(item.trim()))
@@ -469,10 +437,7 @@ function buildFlatWhereKey(field, operator, orGroup) {
 
 export function parseFlatWhereKey(key) {
     if (!isNonEmptyString(key)) {
-        throw new Error("where 字段名不能为空", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("where 字段名不能为空");
     }
 
     assertNoExprField(key);
@@ -481,24 +446,18 @@ export function parseFlatWhereKey(key) {
     const field = rawParts[0];
 
     if (!isNonEmptyString(field)) {
-        throw new Error(`where 字段名不能为空 (field: ${key})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`where 字段名不能为空 (field: ${key})`);
     }
 
     const suffixParts = rawParts.slice(1);
     let orGroup = null;
 
-    if (suffixParts.length > 0 && isFlatWhereOrGroupToken(suffixParts[suffixParts.length - 1])) {
+    if (suffixParts.length > 0 && isFlatWhereOrGroupToken(suffixParts.at(-1))) {
         orGroup = suffixParts.pop();
     }
 
     if (suffixParts.length > 1) {
-        throw new Error(`where 字段后缀格式无效，请使用 field、field$op、field$or、field$op$orN (field: ${key})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`where 字段后缀格式无效，请使用 field、field$op、field$or、field$op$orN (field: ${key})`);
     }
 
     if (suffixParts.length === 0) {
@@ -512,10 +471,7 @@ export function parseFlatWhereKey(key) {
     const operatorToken = suffixParts[0];
 
     if (!flatWhereOperatorTokens.has(operatorToken)) {
-        throw new Error(`where 操作符无效，请使用受支持的扁平操作符 (field: ${key}, operator: ${operatorToken})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`where 操作符无效，请使用受支持的扁平操作符 (field: ${key}, operator: ${operatorToken})`);
     }
 
     return {

package/lib/logger.js

@@ -6,6 +6,7 @@ import { createWriteStream, existsSync, mkdirSync, rmSync, statSync } from "node
 import { join as nodePathJoin, resolve as nodePathResolve } from "node:path";
 
 import { formatYmdHms } from "../utils/datetime.js";
+import { createError } from "../utils/error.js";
 import { isPlainObject } from "../utils/is.js";
 import { buildSensitiveKeyMatcher, sanitizeLogObject } from "../utils/loggerUtils.js";
 import { normalizePositiveInt } from "../utils/util.js";
@@ -32,7 +33,9 @@ let errorFileSink = null;
 let config = {
     debug: 0,
     dir: "",
-    runtimeEnv: "production"
+    runtimeEnv: "production",
+    // bm2 多实例标识（BM2_INSTANCE_ID 优先，BM2_APP_INSTANCE 兜底）；无 bm2 环境为空串，文件名不带后缀
+    instanceId: ""
 };
 
 function safeWriteStderr(msg) {
@@ -48,6 +51,8 @@ class LogFileSink {
         this.streamIndex = 0;
         this.streamSizeBytes = 0;
         this.disabled = false;
+        // 最近一次 write 的完成回调（write 回调按提交顺序触发，等待它即等待全部已提交数据排空）
+        this.lastWriteDone = null;
     }
 
     write(line) {
@@ -55,13 +60,20 @@ class LogFileSink {
 
         this.ensureStreamReady(line.length);
         if (this.stream) {
-            this.stream.write(line);
             this.streamSizeBytes += line.length;
+            this.lastWriteDone = new Promise((resolve) => {
+                this.stream.write(line, resolve);
+            });
         }
     }
 
+    /**
+     * 等待已提交数据排空（不关闭流）
+     */
     async flushNow() {
-        return this.closeStream();
+        if (this.lastWriteDone) {
+            await this.lastWriteDone;
+        }
     }
 
     async shutdown() {
@@ -73,8 +85,10 @@ class LogFileSink {
             return nodePathJoin(config.dir, "dev.log");
         }
 
+        // bm2 多实例时按实例分文件，避免多进程写同一文件（例：app.2026-08-01.0.1.log）
         const suffix = index > 0 ? `.${index}` : "";
-        const filename = this.prefix === "app" ? `${date}${suffix}.log` : `${this.prefix}.${date}${suffix}.log`;
+        const instanceSuffix = config.instanceId ? `.${config.instanceId}` : "";
+        const filename = this.prefix === "app" ? `${date}${instanceSuffix}${suffix}.log` : `${this.prefix}.${date}${instanceSuffix}${suffix}.log`;
         return nodePathJoin(config.dir, filename);
     }
 
@@ -155,7 +169,7 @@ class LogFileSink {
     }
 }
 
-export async function flush() {
+async function flush() {
     if (mockInstance) return;
 
     for (const sink of [appFileSink, errorFileSink]) {
@@ -165,7 +179,7 @@ export async function flush() {
     }
 }
 
-export async function shutdown() {
+async function shutdown() {
     if (mockInstance) return;
 
     const currentAppFileSink = appFileSink;
@@ -190,7 +204,7 @@ function getRuntimeLogDir() {
 }
 
 function prepareLogDir(runtimeEnv, shouldClearDev = false) {
-    const logDir = getRuntimeLogDir(runtimeEnv);
+    const logDir = getRuntimeLogDir();
     const devLogPath = nodePathResolve(logDir, "dev.log");
 
     try {
@@ -201,10 +215,7 @@ function prepareLogDir(runtimeEnv, shouldClearDev = false) {
             rmSync(devLogPath, { force: true });
         }
     } catch (error) {
-        throw new Error(`创建日志目录失败: ${logDir}. ${error?.message || error}`, {
-            cause: error,
-            code: "runtime"
-        });
+        throw createError(`创建日志目录失败: ${logDir}. ${error?.message || error}`, { cause: error, code: "runtime" });
     }
 
     return logDir;
@@ -217,19 +228,21 @@ function ensureLogDirExists() {
 /**
  * 配置日志
  */
-export function configure(cfg) {
+function configure(cfg) {
     shutdown();
 
-    config = Object.assign(
-        {
-            debug: 0,
-            dir: "",
-            runtimeEnv: "production"
-        },
-        cfg
-    );
+    config = {
+        debug: 0,
+        dir: "",
+        runtimeEnv: "production",
+        instanceId: "",
+        ...cfg
+    };
+
+    // 实例 ID 来自运行环境（bm2 注入），不允许配置覆盖
+    config.instanceId = Bun.env.BM2_INSTANCE_ID || Bun.env.BM2_APP_INSTANCE || "";
 
-    config.dir = getRuntimeLogDir(config.runtimeEnv);
+    config.dir = getRuntimeLogDir();
     prepareLogDir(config.runtimeEnv, true);
 
     appFileSink = null;
@@ -247,7 +260,7 @@ export function configure(cfg) {
  * 设置 Mock Logger（用于测试）
  * @param mock - Mock Logger 实例（形如 {info/warn/error/debug}），传 null 清除 mock
  */
-export function setMockLogger(mock) {
+function setMockLogger(mock) {
     mockInstance = mock;
 }
 
@@ -379,10 +392,20 @@ function buildLogMethod(level) {
 
 /**
  * 日志实例（延迟初始化）
+ * 方法签名约定：
+ * - info/warn/debug: (msg, data) —— msg 为字符串或直接传对象（对象时作为完整 record）
+ * - error: (msg, err, data) —— err 为 Error 或任意附加信息，data 为可选附加数据
+ * - 输出统一为 JSONL 单行：{ level, time, pid, msg, ...record }
  */
 export const Logger = {
     info: buildLogMethod("info"),
     warn: buildLogMethod("warn"),
+    /**
+     * 错误日志
+     * @param msg - 错误说明（字符串；传对象时作为完整 record）
+     * @param err - 错误对象（Error 实例会被序列化并附带 chain 摘要）或任意附加信息
+     * @param data - 可选附加数据
+     */
     error: function (msg, err, data) {
         if (isPlainObject(msg)) {
             logWrite("error", msg);