befly 3.74.2 → 3.75.0

package/utils/is.js

@@ -1,11 +1,5 @@
-import { statSync } from "node:fs";
-
-import { join } from "pathe";
-
-import { DECIMAL_KIND_TYPES, ENUM_KIND_TYPES, FLOAT_KIND_TYPES, INT_KIND_TYPES, JSON_KIND_TYPES, STRING_KIND_TYPES, TEXT_KIND_TYPES } from "../configs/constConfig.js";
-
 /**
- * 判断值是否为 plain object（原型为 Object.prototype 或 null）123。
+ * 判断值是否为 plain object（原型为 Object.prototype 或 null）。
  */
 export function isPlainObject(value) {
     if (typeof value !== "object" || value === null) {
@@ -26,61 +20,6 @@ export function isJsonPrimitive(value) {
     return typeof value === "string" || isNumber(value) || isBoolean(value);
 }
 
-/**
- * 判断值是否为 JSON 对象（plain object，且非数组/非 Date）。
- */
-export function isJsonObject(value) {
-    if (!value || typeof value !== "object") {
-        return false;
-    }
-    if (value instanceof Date) {
-        return false;
-    }
-    if (Array.isArray(value)) {
-        return false;
-    }
-    return true;
-}
-
-/**
- * 判断值是否为 JSON 结构（数组或对象）。
- */
-export function isJsonStructure(value) {
-    return Array.isArray(value) || isJsonObject(value);
-}
-
-/**
- * 判断值是否为可 JSON 序列化结构（递归）。
- */
-export function isJsonValue(value) {
-    if (isJsonPrimitive(value)) {
-        return true;
-    }
-
-    if (Array.isArray(value)) {
-        for (const item of value) {
-            if (!isJsonValue(item)) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    if (isJsonObject(value)) {
-        for (const v of Object.values(value)) {
-            if (v === undefined) {
-                continue;
-            }
-            if (!isJsonValue(v)) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    return false;
-}
-
 /**
  * 判断值是否为有限数值。
  */
@@ -173,12 +112,12 @@ export function isNoTrimStringAllowEmpty(value) {
         return true;
     }
 
-    const firstCharCode = value.charCodeAt(0);
+    const firstCharCode = value.codePointAt(0);
     if (isWhitespaceCharCode(firstCharCode)) {
         return false;
     }
 
-    const lastCharCode = value.charCodeAt(value.length - 1);
+    const lastCharCode = value.codePointAt(value.length - 1);
     if (isWhitespaceCharCode(lastCharCode)) {
         return false;
     }
@@ -290,131 +229,15 @@ export function isRegexInput(input) {
     return isRegexLiteral(trimmed) || trimmed.startsWith("@");
 }
 
-/**
- * 判断输入是否为枚举规则（首字符非 / 且包含 |）。
- */
-export function isEnumInput(input) {
-    const trimmed = String(input || "").trim();
-    if (trimmed.length === 0) {
-        return false;
-    }
-    return !trimmed.startsWith("/") && trimmed.includes("|");
-}
-
-/**
- * 判断输入是否为规则别名（@ 开头）。
- */
-export function isAliasInput(input) {
-    return String(input || "")
-        .trim()
-        .startsWith("@");
-}
-
-/**
- * 激进空值判断（项目约定）。
- */
-export function isEmpty(value) {
-    if (isNullable(value)) {
-        return true;
-    }
-
-    if (typeof value === "string") {
-        return value.trim().length === 0;
-    }
-
-    if (isNumber(value)) {
-        return value === 0 || Number.isNaN(value);
-    }
-
-    if (isBoolean(value)) {
-        return value === false;
-    }
-
-    if (Array.isArray(value)) {
-        return value.length === 0;
-    }
-
-    if (value instanceof Map || value instanceof Set) {
-        return value.size === 0;
-    }
-
-    if (isPlainObject(value)) {
-        return Object.keys(value).length === 0;
-    }
-
-    return false;
-}
-
 /**
  * 判断当前进程是否为主进程。
- * PM2 cluster 的实例 0 是主进程；未由 PM2 启动时视为主进程。
+ * bm2 的实例 0 是主进程；未由 bm2 启动时视为主进程。
  */
 export function isPrimaryProcess() {
-    const instance = Bun.env.NODE_APP_INSTANCE;
+    const instance = Bun.env.BM2_APP_INSTANCE;
     return instance === "0" || instance === 0 || instance === undefined;
 }
 
-export const isDirentDirectory = (parentDir, entry) => {
-    if (entry.isDirectory()) {
-        return true;
-    }
-
-    // 兼容 Windows 下的 junction / workspace link：Dirent.isDirectory() 可能为 false，但它实际指向目录。
-    if (!entry.isSymbolicLink()) {
-        return false;
-    }
-
-    try {
-        const stats = statSync(join(parentDir, entry.name));
-        return stats.isDirectory();
-    } catch {
-        return false;
-    }
-};
-
-/**
- * 数据库类型判定
- */
-export function isStringDbType(dbType) {
-    return STRING_KIND_TYPES.includes(dbType);
-}
-
-export function isTextDbType(dbType) {
-    return TEXT_KIND_TYPES.includes(dbType);
-}
-
-export function isIntDbType(dbType) {
-    return INT_KIND_TYPES.includes(dbType);
-}
-
-export function isDecimalDbType(dbType) {
-    return DECIMAL_KIND_TYPES.includes(dbType);
-}
-
-export function isFloatDbType(dbType) {
-    return FLOAT_KIND_TYPES.includes(dbType);
-}
-
-export function isJsonDbType(dbType) {
-    return JSON_KIND_TYPES.includes(dbType);
-}
-
-export function isEnumDbType(dbType) {
-    return ENUM_KIND_TYPES.includes(dbType);
-}
-
-export function isNumericDbType(dbType) {
-    return INT_KIND_TYPES.includes(dbType) || DECIMAL_KIND_TYPES.includes(dbType) || FLOAT_KIND_TYPES.includes(dbType);
-}
-
-/**
- * SQL Value 判定
- */
-export function isSqlValue(value) {
-    if (value instanceof Date) return true;
-    return isJsonValue(value);
-}
-
 /**
  * 日志敏感键判定
  */

package/utils/loggerUtils.js

@@ -1,3 +1,4 @@
+import { errorChainSummary } from "./error.js";
 import { isBoolean, isNullable, isNumber, isPlainObject, isSensitiveKey, isString } from "./is.js";
 
 export function buildSensitiveKeyMatcher(options) {
@@ -34,7 +35,8 @@ export function buildSensitiveKeyMatcher(options) {
 function sanitizeErrorValue(err, options) {
     const out = {
         name: err.name || "Error",
-        message: err.message || ""
+        message: err.message || "",
+        chain: errorChainSummary(err)
     };
     const state = { nodes: 0 };
     const visited = new WeakSet();

package/utils/response.js

@@ -13,11 +13,16 @@ import { isString } from "./is.js";
  * @returns Response 对象
  */
 export function ErrorResponse(ctx, msg, code = 1, data = null, detail = null, reason = null) {
-    // 记录拦截日志
+    // 记录拦截日志（带请求上下文，便于排查被拦截请求）
     if (ctx.requestId) {
-        // requestId/apiPath/user/duration 等字段由调用方显式写入日志上下文，避免在 msg 中重复拼接
         Logger.info("请求已拦截", {
             event: "request_blocked",
+            requestId: ctx.requestId,
+            apiPath: ctx.apiPath,
+            apiName: ctx.apiName,
+            ip: ctx.ip,
+            userId: ctx.userId,
+            roleCode: ctx.roleCode,
             msg: msg,
             reason: reason,
             code: code,
@@ -62,8 +67,8 @@ export function FinalResponse(ctx) {
                 msg: result
             };
         }
-        // 如果是对象，自动补充 code: 0
-        else if (result && typeof result === "object") {
+        // 如果是对象，自动补充 code: 0（数组保持原样）
+        else if (result && typeof result === "object" && !Array.isArray(result)) {
             if (!("code" in result)) {
                 const merged = { code: 0 };
                 for (const key of Object.keys(result)) {
@@ -87,11 +92,10 @@ export function FinalResponse(ctx) {
             return new Response(jsonString, {
                 headers: headers
             });
-        } else {
-            return Response.json(result, {
-                headers: ctx.corsHeaders
-            });
         }
+        return Response.json(result, {
+            headers: ctx.corsHeaders
+        });
     }
 
     // 3. 默认响应：没有生成响应

package/utils/scanFiles.js

@@ -2,58 +2,10 @@ import { existsSync } from "node:fs";
 
 import { relative, normalize, parse, join } from "pathe";
 
+import { createError } from "./error.js";
 import { importDefault } from "./importDefault.js";
 import { isPlainObject } from "./is.js";
 
-// [ hooks ]-112 {
-//   source: "core",
-//   type: "hook",
-//   filePath: "D:/codes/befly/packages/core/hooks/auth.js",
-//   relativePath: "auth",
-//   fileName: "auth",
-//   apiPath: "/api/core/auth",
-//   name: "auth",
-//   order: 1,
-//   handler: [AsyncFunction: handler],
-// }
-// 🔥[ plugins ]-112 {
-//   source: "core",
-//   type: "plugin",
-//   filePath: "D:/codes/befly/packages/core/plugins/cache.js",
-//   relativePath: "cache",
-//   fileName: "cache",
-//   apiPath: "/api/core/cache",
-//   name: "cache",
-//   order: 1,
-//   handler: [AsyncFunction: handler],
-// }
-// 🔥[ tables ]-112 {
-//   source: "core",
-//   type: "table",
-//   filePath: "D:/codes/befly/packages/core/tables/admin.json",
-//   relativePath: "admin",
-//   fileName: "admin",
-//   apiPath: "/api/core/admin",
-//     "lastLoginTime", "lastLoginIp"
-//   ],
-//   name: "admin",
-// }
-// 🔥[ apis ]-112 {
-//   source: "core",
-//   type: "api",
-//   filePath: "D:/codes/befly/packages/core/apis/sysConfig/all.js",
-//   relativePath: "sysConfig/all",
-//   fileName: "all",
-//   apiPath: "/api/core/sysConfig/all",
-//   name: "all",
-//   method: "POST",
-//   body: "none",
-//   auth: true,
-//   fields: {},
-//   required: [],
-//   handler: [AsyncFunction: handler],
-// }
-
 /**
  * 扫描指定目录下的文件
  * @param dir 目录路径
@@ -116,9 +68,6 @@ export async function scanFiles(dir, source, type, pattern) {
         }
         return results;
     } catch (error) {
-        throw new Error(`扫描失败: source=${source} type=${type} dir=${dir} pattern=${pattern}`, {
-            cause: error,
-            code: "runtime"
-        });
+        throw createError(`扫描失败: source=${source} type=${type} dir=${dir} pattern=${pattern}`, { cause: error, code: "runtime" });
     }
 }

package/utils/scanSources.js

@@ -9,6 +9,7 @@ import {
     coreApiDir,
     appApiDir
 } from "../paths.js";
+import { createError } from "./error.js";
 import { scanFiles } from "./scanFiles.js";
 
 export const scanSources = async () => {
@@ -54,6 +55,14 @@ export const scanSources = async () => {
     }
     const allAppApis = await scanFiles(appApiDir, "app", "api", "**/*.js");
     for (const item of allAppApis) {
+        // 禁止 app 接口目录下的 core 一级目录：会与框架内置 /api/core 命名空间冲突，从源头保证 apiPath 唯一
+        if (item.relativePath.split("/")[0] === "core") {
+            throw createError(`app 接口目录下禁止存在 core 一级目录：${item.filePath}`, {
+                code: "policy",
+                subsystem: "scan",
+                operation: "scanSources"
+            });
+        }
         apis.push(item);
     }
 

package/utils/util.js

@@ -4,7 +4,26 @@
  * - 仅在 packages/core 内部使用；core 对外不承诺这些路径导出。
  */
 
-import { isBoolean, isNullable, isNumber, isPlainObject } from "./is.js";
+import { createError } from "./error.js";
+import { isPlainObject } from "./is.js";
+
+/**
+ * 通用等待工具：轮询直到条件满足或超时（while + sleep 实现，无定时器句柄，无泄漏风险）
+ * @param {string} label - 等待说明（用于超时错误信息）
+ * @param {Function} check - 异步条件函数，返回 true 表示就绪
+ * @param {number} [intervalMs=200] - 轮询间隔（毫秒）
+ * @param {number} [timeoutMs=60000] - 超时时间（毫秒）
+ */
+export async function waitFor({ label, check, intervalMs = 200, timeoutMs = 60000 }) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await check()) {
+            return;
+        }
+        await Bun.sleep(intervalMs);
+    }
+    throw createError(`等待${label}超时`, { code: "runtime", subsystem: "start", operation: "waitFor" });
+}
 
 /**
  * 判断 bigint 是否可安全转换为 number。
@@ -32,43 +51,6 @@ export function canConvertToNumber(value) {
     return asNumber;
 }
 
-/**
- * 安全格式化值用于日志预览（截断长文本，避免抛错）。
- */
-export function formatValuePreview(value) {
-    if (value === null) {
-        return "null";
-    }
-    if (value === undefined) {
-        return "undefined";
-    }
-
-    if (typeof value === "string") {
-        const s = value.length > 80 ? `${value.slice(0, 80)}...` : value;
-        return JSON.stringify(s);
-    }
-
-    if (isNumber(value) || isBoolean(value) || typeof value === "bigint") {
-        return String(value);
-    }
-
-    if (typeof value === "function") {
-        return "[Function]";
-    }
-
-    try {
-        const s = JSON.stringify(value);
-        if (typeof s === "string") {
-            return s.length > 120 ? `${s.slice(0, 120)}...` : s;
-        }
-    } catch {
-        // ignore
-    }
-
-    const s = String(value);
-    return s.length > 120 ? `${s.slice(0, 120)}...` : s;
-}
-
 /**
  * 获取值的类型标识（数组/对象等做细分）。
  */
@@ -88,16 +70,6 @@ export function getTypeTag(value) {
     return "object";
 }
 
-// 正则字符转义列表
-const REGEXP_SPECIAL = /[\^$.*+?()[\]{}|]/g;
-
-/**
- * 转义字符串中的正则特殊字符。
- */
-export function escapeRegExp(input) {
-    return String(input).replace(REGEXP_SPECIAL, "\\$&");
-}
-
 /**
  * 归一化正整数：非法值回退，超出范围裁剪。
  */
@@ -109,24 +81,6 @@ export function normalizePositiveInt(value, fallback, min, max) {
     return v;
 }
 
-/**
- * 遍历 plain object 的自有字段。
- */
-export function forOwn(obj, iteratee) {
-    if (typeof iteratee !== "function") {
-        return;
-    }
-
-    if (!isPlainObject(obj)) {
-        return;
-    }
-
-    const record = obj;
-    for (const key of Object.keys(record)) {
-        iteratee(record[key], key);
-    }
-}
-
 // 将字符串拆分为词段（用于 camelCase/snakeCase）
 function toWordParts(input) {
     const normalized = String(input)
@@ -170,19 +124,6 @@ export function camelCase(input) {
     return [first].concat(rest).join("");
 }
 
-/**
- * 字段名专用小驼峰转换。
- * - 只要原始值包含下划线，就直接保留原字段名。
- * - 其余场景继续走普通小驼峰转换。
- */
-export function camelCaseKeepUnderscore(input) {
-    if (input.includes("_")) {
-        return input;
-    }
-
-    return camelCase(input);
-}
-
 /**
  * 把字符串转为 snake_case。
  * - 主要用于表名/字段名（例如 userId -> user_id）。
@@ -196,22 +137,6 @@ export function snakeCase(input) {
     return parts.map((p) => p.toLowerCase()).join("_");
 }
 
-/**
- * 对象字段名转小驼峰
- * @param obj - 源对象
- * @returns 字段名转为小驼峰格式的新对象
- */
-export const keysToCamel = (obj) => {
-    if (!obj || !isPlainObject(obj)) return obj;
-
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        const camelKey = camelCase(key);
-        result[camelKey] = value;
-    }
-    return result;
-};
-
 /**
  * 对象字段名转下划线
  * @param obj - 源对象
@@ -229,134 +154,12 @@ export const keysToSnake = (obj) => {
 };
 
 /**
- * 数组对象字段名批量转小驼峰
- * @param arr - 源数组
- * @returns 字段名转为小驼峰格式的新数组
- */
-export const arrayKeysToCamel = (arr) => {
-    if (!arr || !Array.isArray(arr)) return arr;
-    return arr.map((item) => keysToCamel(item));
-};
-
-/**
- * 根据点路径读取对象字段（不存在则返回 undefined）。
- */
-export function getByPath(obj, path) {
-    if (!path) {
-        return obj;
-    }
-
-    const parts = path.split(".");
-    let cur = obj;
-
-    for (const part of parts) {
-        if (isNullable(cur)) {
-            return undefined;
-        }
-        if (typeof cur !== "object") {
-            return undefined;
-        }
-        const record = cur;
-        cur = record[part];
-    }
-
-    return cur;
-}
-
-/**
- * 根据点路径写入对象字段（中间层自动补空对象）。
- */
-export function setByPath(target, path, value) {
-    const parts = path.split(".");
-    // 避免无效 path（如 a..b）导致部分写入
-    for (const part of parts) {
-        if (!part) {
-            return;
-        }
-    }
-    let cur = target;
-
-    for (let i = 0; i < parts.length; i++) {
-        const key = parts[i];
-        if (!key) {
-            return;
-        }
-
-        const isLast = i === parts.length - 1;
-        if (isLast) {
-            cur[key] = value;
-            return;
-        }
-
-        const nextVal = cur[key];
-        if (!isPlainObject(nextVal)) {
-            cur[key] = {};
-        }
-
-        cur = cur[key];
-    }
-}
-
-/**
- * 生成移除指定字段后的浅拷贝。
- */
-export function omit(obj, keys) {
-    if (!isPlainObject(obj)) {
-        return {};
-    }
-
-    const keySet = new Set(Array.isArray(keys) ? keys : []);
-    const out = {};
-
-    for (const [k, v] of Object.entries(obj)) {
-        if (keySet.has(k)) {
-            continue;
-        }
-        out[k] = v;
-    }
-
-    return out;
-}
-
-/**
- * 从对象中挑选指定字段。
- */
-export const pickFields = (obj, keys) => {
-    if (!obj || (!isPlainObject(obj) && !Array.isArray(obj))) {
-        return {};
-    }
-
-    const record = obj;
-    const result = {};
-
-    for (const key of keys) {
-        if (key in record) {
-            result[key] = record[key];
-        }
-    }
-
-    return result;
-};
-
-/**
- * 根据 key 生成对象映射。
+ * 获取运行模式（开发/正式的统一判断，仅以 NODE_ENV 为准）
+ * - 线上部署（bm2 等）注入 NODE_ENV=production
+ * - 本地开发未设置 NODE_ENV，默认 "development"
  */
-export function keyBy(items, getKey) {
-    const out = {};
-
-    if (!Array.isArray(items) || typeof getKey !== "function") {
-        return out;
-    }
-
-    for (const item of items) {
-        const key = getKey(item);
-        if (typeof key !== "string" || key === "") {
-            continue;
-        }
-        out[key] = item;
-    }
-
-    return out;
+export function getRunMode() {
+    return Bun.env.NODE_ENV || "development";
 }
 
 /**

package/checks/hook.js

@@ -1,39 +0,0 @@
-import { Logger } from "../lib/logger.js";
-import { formatValidationIssues } from "../utils/formatValidationIssues.js";
-import { isFiniteNumber, isFunction, isPlainObject, isString } from "../utils/is.js";
-
-const hookKeys = new Set(["source", "type", "filePath", "relativePath", "fileName", "apiPath", "handler", "order"]);
-
-function checkHookItem(hook) {
-    const issues = [];
-    if (!isPlainObject(hook)) {
-        issues.push({ path: [], message: "必须是对象格式" });
-        return issues;
-    }
-
-    for (const key of Object.keys(hook)) {
-        if (!hookKeys.has(key)) issues.push({ path: [key], message: "不允许出现" });
-    }
-    for (const key of ["source", "type", "filePath", "relativePath", "fileName", "apiPath"]) {
-        if (!isString(hook[key]) || hook[key].length === 0 || hook[key].trim() !== hook[key]) issues.push({ path: [key], message: "必须是非空且无首尾空格的字符串" });
-    }
-    if (!isFunction(hook.handler)) issues.push({ path: ["handler"], message: "必须是函数" });
-    if (!isFiniteNumber(hook.order)) issues.push({ path: ["order"], message: "必须是有限数字" });
-    return issues;
-}
-
-export async function checkHook(hooks) {
-    if (!Array.isArray(hooks)) {
-        Logger.warn("钩子校验失败", { errors: formatValidationIssues([{ path: [], message: "必须是数组" }], { item: hooks, itemLabel: "hook" }) }, false);
-        return true;
-    }
-
-    let hasError = false;
-    for (const hook of hooks) {
-        const issues = checkHookItem(hook);
-        if (issues.length === 0) continue;
-        Logger.warn("钩子校验失败", { errors: formatValidationIssues(issues, { item: hook, itemLabel: "hook" }) }, false);
-        hasError = true;
-    }
-    return hasError;
-}