befly 3.9.38 → 3.9.40

package/README.md

@@ -37,10 +37,10 @@ bunx befly init
 
 ```typescript
 // main.ts
-import { Befly } from 'befly';
+import { Befly } from "befly";
 
 const app = new Befly({
-    appName: 'My API',
+    appName: "My API",
     appPort: 3000
 });
 
@@ -57,15 +57,15 @@ bun run main.ts
 
 ```typescript
 // apis/user/hello.ts
-import type { ApiRoute } from 'befly/types/index';
+import type { ApiRoute } from "befly/types/api";
 
 export default {
-    name: '问候接口',
+    name: "问候接口",
     auth: false, // 公开接口
     fields: {},
     handler: async (befly, ctx) => {
         return {
-            msg: 'Hello, Befly!',
+            msg: "Hello, Befly!",
             data: {
                 timestamp: Date.now()
             }
@@ -81,26 +81,27 @@ export default {
 ### TypeScript 全面支持
 
 ```typescript
-import type { ApiRoute, BeflyContext } from 'befly/types/index';
-import type { User } from './types/models';
+import type { ApiRoute } from "befly/types/api";
+import type { BeflyContext } from "befly/types/befly";
+import type { User } from "./types/models";
 
 export default {
-    name: '获取用户',
+    name: "获取用户",
     auth: true,
     fields: {
-        id: '用户ID|number|1|999999|null|1|null'
+        id: "用户ID|number|1|999999|null|1|null"
     },
-    required: ['id'],
+    required: ["id"],
     handler: async (befly: BeflyContext, ctx) => {
         const { id } = ctx.body;
 
         // 类型安全的数据库查询
         const user = await befly.db.getOne<User>({
-            table: 'user',
+            table: "user",
             where: { id }
         });
 
-        return { msg: '查询成功', data: user };
+        return { msg: "查询成功", data: user };
     }
 } as ApiRoute;
 ```
@@ -110,40 +111,40 @@ export default {
 ```typescript
 // 查询单条
 const user = await befly.db.getOne<User>({
-    table: 'user',
+    table: "user",
     where: { id: 1 }
 });
 
 // 分页列表
 const result = await befly.db.getList<Product>({
-    table: 'product',
-    where: { category: 'electronics' },
+    table: "product",
+    where: { category: "electronics" },
     page: 1,
     limit: 10,
-    orderBy: ['createdAt#DESC']
+    orderBy: ["createdAt#DESC"]
 });
 
 // 插入数据
 await befly.db.insData({
-    table: 'user',
+    table: "user",
     data: {
-        username: 'john',
-        email: 'john@example.com'
+        username: "john",
+        email: "john@example.com"
     }
 });
 
 // 更新数据
 await befly.db.updData({
-    table: 'user',
+    table: "user",
     where: { id: 1 },
     data: {
-        nickname: 'John Doe'
+        nickname: "John Doe"
     }
 });
 
 // 删除数据
 await befly.db.delData({
-    table: 'user',
+    table: "user",
     where: { id: 1 }
 });
 ```
@@ -164,9 +165,7 @@ await befly.db.delData({
 
 同步到数据库：
 
-```bash
-bun run scripts/syncDb.ts
-```
+请参考：`docs/reference/sync.md`（`syncDb` / `syncAll` 等同步流程说明）。
 
 ## 🗄️ 数据库配置
 
@@ -203,37 +202,37 @@ Befly 使用 `befly.config.ts` 作为统一配置文件：
 ```typescript
 // befly.config.ts
 export const beflyConfig = {
-    appName: '我的应用',
+    appName: "我的应用",
     appPort: 3000,
-    appHost: '0.0.0.0',
+    appHost: "0.0.0.0",
 
     // 数据库配置（优先使用环境变量）
     db: {
-        type: 'mysql',
-        host: '127.0.0.1',
+        type: "mysql",
+        host: "127.0.0.1",
         port: 3306,
-        username: 'root',
-        password: 'password',
-        database: 'my_database'
+        username: "root",
+        password: "password",
+        database: "my_database"
     },
 
     // Redis 配置
     redis: {
-        host: '127.0.0.1',
+        host: "127.0.0.1",
         port: 6379,
-        prefix: 'befly:'
+        prefix: "befly:"
     },
 
     // CORS 跨域配置
     cors: {
-        origin: ['http://localhost:5173'],
-        methods: ['GET', 'POST', 'PUT', 'DELETE']
+        origin: ["http://localhost:5173"],
+        methods: ["GET", "POST", "PUT", "DELETE"]
     },
 
     // Addon 插件配置
     addons: {
         admin: {
-            email: { host: 'smtp.qq.com' }
+            email: { host: "smtp.qq.com" }
         }
     }
 };
@@ -244,7 +243,7 @@ export const beflyConfig = {
 框架会自动从 `beflyConfig` 获取配置并建立连接，无需手动传参：
 
 ```typescript
-import { Connect } from 'befly/lib/connect';
+import { Connect } from "befly/lib/connect";
 
 // 连接 SQL 数据库（配置自动从 beflyConfig.db 获取）
 await Connect.connectSql();

package/befly.config.ts

@@ -1,69 +1,80 @@
 /**
  * Befly 配置模块
  * 自动加载 configs 目录下的配置文件并与默认配置合并
- * 支持环境分离：befly.common.json + befly.dev/prod.json + befly.local.json
+ * 支持环境分离：befly.common.json + befly.development/production.json
  */
-import { scanConfig } from 'befly-shared/scanConfig';
+import type { BeflyOptions } from "./types/befly.js";
 
-import type { BeflyOptions } from './types/befly.js';
+import { scanConfig } from "./utils/scanConfig.js";
 
 /** 默认配置 */
 const defaultOptions: BeflyOptions = {
     // ========== 核心参数 ==========
-    nodeEnv: (process.env.NODE_ENV as any) || 'development',
-    appName: '野蜂飞舞',
+    nodeEnv: "development",
+    appName: "野蜂飞舞",
     appPort: 3000,
-    appHost: '127.0.0.1',
-    devEmail: 'dev@qq.com',
-    devPassword: 'beflydev123456',
+    appHost: "127.0.0.1",
+    devEmail: "dev@qq.com",
+    devPassword: "beflydev123456",
     bodyLimit: 1048576, // 1MB
-    tz: 'Asia/Shanghai',
+    tz: "Asia/Shanghai",
 
     // ========== 日志配置 ==========
     logger: {
         debug: 1,
-        excludeFields: 'password,token,secret',
-        dir: './logs',
+        excludeFields: ["password", "token", "secret"],
+        dir: "./logs",
         console: 1,
         maxSize: 10485760 // 10MB
     },
 
     // ========== 数据库配置 ==========
     db: {
-        type: 'mysql',
-        host: '127.0.0.1',
+        type: "mysql",
+        host: "127.0.0.1",
         port: 3306,
-        username: 'root',
-        password: 'root',
-        database: 'befly_demo',
+        username: "root",
+        password: "root",
+        database: "befly_demo",
         poolMax: 10
     },
 
     // ========== Redis 配置 ==========
     redis: {
-        host: '127.0.0.1',
+        host: "127.0.0.1",
         port: 6379,
-        username: '',
-        password: '',
+        username: "",
+        password: "",
         db: 0,
-        prefix: 'befly_demo:'
+        prefix: "befly_demo:"
     },
 
     // ========== 认证配置 ==========
     auth: {
-        secret: 'befly-secret',
-        expiresIn: '7d',
-        algorithm: 'HS256'
+        secret: "befly-secret",
+        expiresIn: "7d",
+        algorithm: "HS256"
     },
 
     // ========== CORS 配置 ==========
     cors: {
-        origin: '*',
-        methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
-        allowedHeaders: 'Content-Type,Authorization',
-        exposedHeaders: '',
+        origin: "*",
+        methods: "GET,HEAD,PUT,PATCH,POST,DELETE",
+        allowedHeaders: "Content-Type,Authorization",
+        exposedHeaders: "",
         maxAge: 86400,
-        credentials: 'true'
+        credentials: "true"
+    },
+
+    // ========== Hook：全局限流 ==========
+    rateLimit: {
+        enable: 1,
+        // 默认兜底规则：所有接口按 IP 限流（如需更细粒度请配置 rules）
+        defaultLimit: 1000,
+        defaultWindow: 60,
+        key: "ip",
+        skipRoutes: [],
+        rules: []
     },
 
     // ========== 禁用配置 ==========
@@ -75,16 +86,27 @@ const defaultOptions: BeflyOptions = {
     addons: {}
 };
 
-// 确定环境
-const nodeEnv = process.env.NODE_ENV || 'development';
-const envSuffix = nodeEnv === 'production' ? 'prod' : 'dev';
+export type LoadBeflyConfigOptions = {
+    cwd?: string;
+    nodeEnv?: string;
+};
+
+export async function loadBeflyConfig(options: LoadBeflyConfigOptions = {}): Promise<BeflyOptions> {
+    const nodeEnv = options.nodeEnv || process.env.NODE_ENV || "development";
+    const envSuffix = nodeEnv === "production" ? "production" : "development";
+
+    // 使用 scanConfig 一次性加载并合并所有配置文件
+    // 合并顺序：defaultOptions ← befly.common.json ← befly.development/production.json
+    const config = await scanConfig({
+        cwd: options.cwd,
+        dirs: ["configs"],
+        files: ["befly.common", `befly.${envSuffix}`],
+        extensions: [".json"],
+        mode: "merge",
+        defaults: defaultOptions
+    });
+
+    return config as BeflyOptions;
+}
 
-// 使用 scanConfig 一次性加载并合并所有配置文件
-// 合并顺序：defaultOptions ← befly.common.json ← befly.dev/prod.json ← befly.local.json
-export const beflyConfig = (await scanConfig({
-    dirs: ['configs'],
-    files: ['befly.common', `befly.${envSuffix}`, 'befly.local'],
-    extensions: ['.json'],
-    mode: 'merge',
-    defaults: defaultOptions
-})) as BeflyOptions;
+export const beflyConfig = await loadBeflyConfig();

package/checks/checkApi.ts

@@ -1,14 +1,14 @@
 // 内部依赖
-import { existsSync } from 'node:fs';
+import { existsSync } from "node:fs";
 
 // 外部依赖
-import { isPlainObject } from 'es-toolkit/compat';
-import { scanFiles } from 'befly-shared/scanFiles';
-import { scanAddons, getAddonDir, addonDirExists } from 'befly-shared/addonHelper';
+import { isPlainObject } from "es-toolkit/compat";
 
+import { Logger } from "../lib/logger.js";
+import { projectApiDir } from "../paths.js";
+import { scanAddons, getAddonDir, addonDirExists } from "../utils/addonHelper.js";
 // 相对导入
-import { Logger } from '../lib/logger.js';
-import { projectApiDir } from '../paths.js';
+import { scanFiles } from "../utils/scanFiles.js";
 
 /**
  * 检查所有 API 定义
@@ -24,7 +24,7 @@ export async function checkApi(): Promise<void> {
             for (const { filePath, relativePath } of files) {
                 allApiFiles.push({
                     file: filePath,
-                    displayName: '用户',
+                    displayName: "用户",
                     apiPath: relativePath
                 });
             }
@@ -33,8 +33,8 @@ export async function checkApi(): Promise<void> {
         // 收集组件 API 文件
         const addons = scanAddons();
         for (const addon of addons) {
-            if (!addonDirExists(addon, 'apis')) continue;
-            const addonApiDir = getAddonDir(addon, 'apis');
+            if (!addonDirExists(addon, "apis")) continue;
+            const addonApiDir = getAddonDir(addon, "apis");
 
             const files = await scanFiles(addonApiDir);
             for (const { filePath, relativePath } of files) {
@@ -52,26 +52,26 @@ export async function checkApi(): Promise<void> {
 
             try {
                 // Windows 下路径需要转换为正斜杠格式
-                const filePath = item.file.replace(/\\/g, '/');
+                const filePath = item.file.replace(/\\/g, "/");
                 const apiImport = await import(filePath);
                 const api = apiImport.default;
 
                 // 验证必填属性：name 和 handler
-                if (typeof api.name !== 'string' || api.name.trim() === '') {
+                if (typeof api.name !== "string" || api.name.trim() === "") {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 name 属性必须是非空字符串`);
                     continue;
                 }
-                if (typeof api.handler !== 'function') {
+                if (typeof api.handler !== "function") {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 handler 属性必须是函数`);
                     continue;
                 }
 
                 // 验证可选属性的类型（如果提供了）
-                const validMethods = ['GET', 'POST', 'GET,POST', 'POST,GET'];
+                const validMethods = ["GET", "POST", "GET,POST", "POST,GET"];
                 if (api.method && !validMethods.includes(api.method.toUpperCase())) {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 method 属性必须是有效的 HTTP 方法 (GET, POST, GET,POST, POST,GET)`);
                 }
-                if (api.auth !== undefined && typeof api.auth !== 'boolean') {
+                if (api.auth !== undefined && typeof api.auth !== "boolean") {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 auth 属性必须是布尔值 (true=需登录, false=公开)`);
                 }
                 if (api.fields && !isPlainObject(api.fields)) {
@@ -80,7 +80,7 @@ export async function checkApi(): Promise<void> {
                 if (api.required && !Array.isArray(api.required)) {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 required 属性必须是数组`);
                 }
-                if (api.required && api.required.some((item: any) => typeof item !== 'string')) {
+                if (api.required && api.required.some((item: any) => typeof item !== "string")) {
                     Logger.warn(`[${item.displayName}] 接口 ${apiPath} 的 required 属性必须是字符串数组`);
                 }
             } catch (error: any) {
@@ -88,7 +88,7 @@ export async function checkApi(): Promise<void> {
             }
         }
     } catch (error: any) {
-        Logger.error('API 定义检查过程中出错', error);
+        Logger.error("API 定义检查过程中出错", error);
         throw error;
     }
 }

package/checks/checkApp.ts

@@ -1,10 +1,10 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 // 内部依赖
-import { join } from 'node:path';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from "node:path";
 
 // 相对导入
-import { Logger } from '../lib/logger.js';
-import { projectApiDir, projectDir } from '../paths.js';
+import { Logger } from "../lib/logger.js";
+import { projectApiDir, projectDir } from "../paths.js";
 
 /**
  * 检查项目结构
@@ -13,49 +13,43 @@ export async function checkApp(): Promise<void> {
     try {
         // 检查项目 apis 目录下是否存在名为 addon 的目录
         if (existsSync(projectApiDir)) {
-            const addonDir = join(projectApiDir, 'addon');
+            const addonDir = join(projectApiDir, "addon");
             if (existsSync(addonDir)) {
-                throw new Error('项目 apis 目录下不能存在名为 addon 的目录，addon 是保留名称，用于组件接口路由');
+                throw new Error("项目 apis 目录下不能存在名为 addon 的目录，addon 是保留名称，用于组件接口路由");
             }
         }
 
         // 检查并创建 logs 目录
-        const logsDir = join(projectDir, 'logs');
+        const logsDir = join(projectDir, "logs");
         if (!existsSync(logsDir)) {
             mkdirSync(logsDir, { recursive: true });
         }
 
         // 检查并创建 configs 目录和配置文件
-        const configsDir = join(projectDir, 'configs');
+        const configsDir = join(projectDir, "configs");
         if (!existsSync(configsDir)) {
             mkdirSync(configsDir, { recursive: true });
         }
 
         // 检查并创建 befly.common.json
-        const beflyJsonPath = join(configsDir, 'befly.common.json');
+        const beflyJsonPath = join(configsDir, "befly.common.json");
         if (!existsSync(beflyJsonPath)) {
-            writeFileSync(beflyJsonPath, '{}', 'utf-8');
+            writeFileSync(beflyJsonPath, "{}", "utf-8");
         }
 
-        // 检查并创建 befly.dev.json
-        const beflyDevJsonPath = join(configsDir, 'befly.dev.json');
-        if (!existsSync(beflyDevJsonPath)) {
-            writeFileSync(beflyDevJsonPath, '{}', 'utf-8');
+        // 检查并创建 befly.development.json
+        const beflyDevelopmentJsonPath = join(configsDir, "befly.development.json");
+        if (!existsSync(beflyDevelopmentJsonPath)) {
+            writeFileSync(beflyDevelopmentJsonPath, "{}", "utf-8");
         }
 
-        // 检查并创建 befly.prod.json
-        const beflyProdJsonPath = join(configsDir, 'befly.prod.json');
-        if (!existsSync(beflyProdJsonPath)) {
-            writeFileSync(beflyProdJsonPath, '{}', 'utf-8');
-        }
-
-        // 检查并创建 befly.local.json
-        const beflyLocalJsonPath = join(configsDir, 'befly.local.json');
-        if (!existsSync(beflyLocalJsonPath)) {
-            writeFileSync(beflyLocalJsonPath, '{}', 'utf-8');
+        // 检查并创建 befly.production.json
+        const beflyProductionJsonPath = join(configsDir, "befly.production.json");
+        if (!existsSync(beflyProductionJsonPath)) {
+            writeFileSync(beflyProductionJsonPath, "{}", "utf-8");
         }
     } catch (error: any) {
-        Logger.error('项目结构检查过程中出错', error);
+        Logger.error("项目结构检查过程中出错", error);
         throw error;
     }
 }