befly 3.75.3 → 3.76.0

package/checks/corns.js

@@ -0,0 +1,54 @@
+import { Logger } from "../lib/logger.js";
+import { formatValidationIssues } from "../utils/formatValidationIssues.js";
+import { isFunction, isPlainObject, isValidCronSchedule } from "../utils/is.js";
+
+// scanFiles 基础字段 + 定时器业务字段（schedule/handler；时区统一走 config.tz）
+const cornKeys = new Set(["source", "type", "filePath", "relativePath", "fileName", "apiPath", "schedule", "handler"]);
+
+export const checkCorn = (corns) => {
+    if (!Array.isArray(corns)) {
+        const errors = formatValidationIssues([{ path: [], message: "必须是数组" }], { item: corns, itemLabel: "corn" });
+        Logger.warn(`定时器校验失败`, { errors: errors });
+        return errors;
+    }
+
+    const errors = [];
+
+    // 任务名唯一性：文件名即任务名（core + app 合并后全局唯一，防止同名任务被 register 静默去重）
+    const nameMap = new Map();
+    for (const corn of corns) {
+        if (!corn?.fileName) continue;
+        nameMap.set(corn.fileName, (nameMap.get(corn.fileName) || 0) + 1);
+    }
+    const duplicateNames = [...nameMap].filter(([, count]) => count > 1).map(([name]) => name);
+    if (duplicateNames.length > 0) {
+        const duplicateCorns = corns.filter((corn) => duplicateNames.includes(corn.fileName));
+        errors.push(
+            ...formatValidationIssues(
+                duplicateCorns.map((corn, index) => ({ path: [index], message: `任务名 ${corn.fileName} 重复，请显式区分` })),
+                { items: duplicateCorns, itemLabel: "corn" }
+            )
+        );
+    }
+
+    for (const [index, corn] of corns.entries()) {
+        if (!isPlainObject(corn)) {
+            errors.push(...formatValidationIssues([{ path: [index], message: "必须是对象格式" }], { items: corns, itemLabel: "corn" }));
+            continue;
+        }
+
+        const issues = [];
+        for (const key of Object.keys(corn)) {
+            if (!cornKeys.has(key)) issues.push({ path: [key], message: "不允许出现" });
+        }
+        if (!isFunction(corn.handler)) issues.push({ path: ["handler"], message: "必须是函数" });
+        if (!isValidCronSchedule(corn.schedule)) issues.push({ path: ["schedule"], message: "必须是可注册的 cron 表达式" });
+        if (issues.length === 0) continue;
+        errors.push(...formatValidationIssues(issues, { items: corns, itemLabel: "corn" }));
+    }
+
+    if (errors.length > 0) {
+        Logger.warn(`定时器校验失败`, { errors: errors });
+    }
+    return errors;
+};

package/index.js

@@ -6,6 +6,7 @@
 // 检查
 import { checkApi } from "#befly/checks/api.js";
 import { checkConfig } from "#befly/checks/config.js";
+import { checkCorn } from "#befly/checks/corns.js";
 import { checkHook, checkPlugin } from "#befly/checks/items.js";
 import { checkMenu } from "#befly/checks/menu.js";
 import { checkTable } from "#befly/checks/table.js";
@@ -18,6 +19,8 @@ import { BEFLY_ADMIN_TABLE, BEFLY_API_TABLE, BEFLY_MENU_TABLE, BEFLY_ROLE_TABLE
 import { Connect } from "#befly/lib/connect.js";
 // oxlint-disable-next-line unicorn/prefer-export-from -- Logger 同时被本文件大量使用，不能合并为 re-export
 import { Logger } from "#befly/lib/logger.js";
+// 定时任务
+import { registerCorns } from "#befly/plugins/cron.js";
 // 路由处理
 import { apiHandler } from "#befly/router/api.js";
 import { staticHandler } from "#befly/router/static.js";
@@ -108,7 +111,7 @@ export async function createBefly(config = {}, menus = []) {
     Logger.info(`启动 检查配置 耗时 ${calcPerfTime(stageStartTime)}`);
 
     stageStartTime = Bun.nanoseconds();
-    const { apis, tables, plugins, hooks } = await scanSources();
+    const { apis, tables, plugins, hooks, corns } = await scanSources();
     Logger.info(`启动 扫描源码 耗时 ${calcPerfTime(stageStartTime)}`);
 
     stageStartTime = Bun.nanoseconds();
@@ -127,6 +130,10 @@ export async function createBefly(config = {}, menus = []) {
     const hookErrors = await checkHook(hooks);
     Logger.info(`启动 检查钩子 耗时 ${calcPerfTime(stageStartTime)}`);
 
+    stageStartTime = Bun.nanoseconds();
+    const cornErrors = await checkCorn(corns);
+    Logger.info(`启动 检查定时器 耗时 ${calcPerfTime(stageStartTime)}`);
+
     stageStartTime = Bun.nanoseconds();
     const menuErrors = await checkMenu(mergedMenus);
     Logger.info(`启动 检查菜单 耗时 ${calcPerfTime(stageStartTime)}`);
@@ -138,6 +145,7 @@ export async function createBefly(config = {}, menus = []) {
         { check: "表结构", errors: tableErrors },
         { check: "插件", errors: pluginErrors },
         { check: "钩子", errors: hookErrors },
+        { check: "定时器", errors: cornErrors },
         { check: "菜单", errors: menuErrors }
     ].filter((entry) => entry.errors.length > 0);
 
@@ -161,6 +169,7 @@ export async function createBefly(config = {}, menus = []) {
         apis: apis,
         hooks: hooks,
         plugins: plugins,
+        corns: corns,
         createdByFactory: true
     });
 }
@@ -179,6 +188,7 @@ export class Befly {
         this.hooks = Array.isArray(init.hooks) ? init.hooks : [];
         this.apis = Array.isArray(init.apis) ? init.apis : [];
         this.plugins = Array.isArray(init.plugins) ? init.plugins : [];
+        this.corns = Array.isArray(init.corns) ? init.corns : [];
         this.createdByFactory = init.createdByFactory === true;
     }
 
@@ -217,6 +227,11 @@ export class Befly {
                 Logger.info(`启动 插件 ${item.fileName} 耗时 ${calcPerfTime(pluginStartTime)}`);
             }
 
+            // 注册定时器（依赖插件加载完成的 ctx.cron，非主进程自动跳过）
+            stageStartTime = Bun.nanoseconds();
+            registerCorns(this.context, this.corns);
+            Logger.info(`启动 注册定时器 耗时 ${calcPerfTime(stageStartTime)}`);
+
             stageStartTime = Bun.nanoseconds();
             await syncReady(this.context);
             Logger.info(`启动 同步就绪 耗时 ${calcPerfTime(stageStartTime)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.75.3",
+    "version": "3.76.0",
     "gitHead": "49c39d36695036e85fc64083cc43c1652fff96cb",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",

package/paths.js

@@ -46,6 +46,13 @@ export const coreCheckDir = join(moduleDir, "checks");
  */
 export const corePluginDir = join(moduleDir, "plugins");
 
+/**
+ * Core 框架定时器目录
+ * @description packages/core/corns/
+ * @usage 存放框架内置定时任务（每文件一个定时器）
+ */
+export const coreCornDir = join(moduleDir, "corns");
+
 /**
  * Core 框架钩子目录
  * @description packages/core/hooks/
@@ -90,6 +97,13 @@ export const appCheckDir = join(appDir, "checks");
  */
 export const appPluginDir = join(appDir, "plugins");
 
+/**
+ * 项目定时器目录
+ * @description {appDir}/corns/
+ * @usage 存放用户业务定时任务（每文件一个定时器）
+ */
+export const appCornDir = join(appDir, "corns");
+
 /**
  * 项目钩子目录
  * @description {appDir}/hooks/

package/plugins/cron.js

@@ -4,7 +4,8 @@ import { PLUGIN_ORDER } from "../configs/constConfig.js";
  * 基于 Bun.cron 提供进程内定时任务能力。
  */
 import { Logger } from "../lib/logger.js";
-import { isPrimaryProcess } from "../utils/is.js";
+import { createError } from "../utils/error.js";
+import { isPrimaryProcess, isValidCronSchedule } from "../utils/is.js";
 
 const jobs = new Map();
 
@@ -24,15 +25,26 @@ function register(context, name, schedule, task) {
         return jobs.get(name);
     }
 
-    const job = Bun.cron(schedule, async function () {
-        Logger.info(`[定时任务] ${name} 开始执行`);
-        try {
-            await task(context);
-            Logger.info(`[定时任务] ${name} 执行完成`);
-        } catch (error) {
-            Logger.error(`[定时任务] ${name} 执行失败`, error);
-        }
-    });
+    // 前置校验：表达式非法时启动即报错，避免 Bun.cron 注册时抛裸错
+    if (!isValidCronSchedule(schedule)) {
+        throw createError(`定时任务 ${name} 的 schedule 不是合法的 cron 表达式`, { code: "validation", subsystem: "cron", operation: "register" });
+    }
+
+    // 时区统一走 config.tz（checkConfig 已校验 IANA 合法性），未配置时使用系统时区
+    const tz = context.config?.tz;
+    const job = Bun.cron(
+        schedule,
+        async function () {
+            Logger.info(`[定时任务] ${name} 开始执行`);
+            try {
+                await task(context);
+                Logger.info(`[定时任务] ${name} 执行完成`);
+            } catch (error) {
+                Logger.error(`[定时任务] ${name} 执行失败`, error);
+            }
+        },
+        tz ? { tz: tz } : undefined
+    );
 
     jobs.set(name, job);
     return job;
@@ -73,6 +85,15 @@ function second(context, name, seconds, task) {
     return job;
 }
 
+/**
+ * 批量注册扫描到的定时器（corns/*.js），任务名取文件名
+ */
+export function registerCorns(context, corns) {
+    for (const corn of corns) {
+        register(context, corn.fileName, corn.schedule, corn.handler);
+    }
+}
+
 /**
  * 停止所有已注册的定时任务
  */

package/utils/is.js

@@ -187,6 +187,20 @@ export function isValidTimeZone(value) {
     }
 }
 
+/**
+ * 判断值是否为可注册的 cron 表达式（与 Bun.cron 注册行为一致：
+ * parse 抛异常或 8 年内无匹配都视为非法，避免启动后才报错）。
+ */
+export function isValidCronSchedule(value) {
+    if (!isString(value)) return false;
+
+    try {
+        return Bun.cron.parse(value) !== null;
+    } catch {
+        return false;
+    }
+}
+
 /**
  * 判断值是否为有限整数。
  */

package/utils/scanSources.js

@@ -7,7 +7,9 @@ import {
     coreHookDir,
     appHookDir,
     coreApiDir,
-    appApiDir
+    appApiDir,
+    coreCornDir,
+    appCornDir
 } from "../paths.js";
 import { createError } from "./error.js";
 import { scanFiles } from "./scanFiles.js";
@@ -17,6 +19,7 @@ export const scanSources = async () => {
     const plugins = [];
     const hooks = [];
     const tables = {};
+    const corns = [];
 
     // 处理表格
     const allCoreTables = await scanFiles(coreTableDir, "core", "table", "*.json");
@@ -48,6 +51,16 @@ export const scanSources = async () => {
         hooks.push(item);
     }
 
+    // 处理定时器
+    const allCoreCorns = await scanFiles(coreCornDir, "core", "corn", "*.js");
+    for (const item of allCoreCorns) {
+        corns.push(item);
+    }
+    const allAppCorns = await scanFiles(appCornDir, "app", "corn", "*.js");
+    for (const item of allAppCorns) {
+        corns.push(item);
+    }
+
     // 处理接口
     const allCoreApis = await scanFiles(coreApiDir, "core", "api", "**/*.js");
     for (const item of allCoreApis) {
@@ -70,6 +83,7 @@ export const scanSources = async () => {
         hooks: hooks,
         plugins: plugins,
         apis: apis,
-        tables: tables
+        tables: tables,
+        corns: corns
     };
 };