befly 3.2.1 → 3.3.1

package/util.ts

@@ -0,0 +1,299 @@
+/**
+ * Befly 核心工具函数集合
+ *
+ * 本文件整合了框架核心工具函数：
+ * - API 响应工具（Yes, No）
+ * - 对象操作（pickFields, fieldClear）
+ * - 日期时间（calcPerfTime）
+ * - 表定义工具（parseRule）
+ * - Addon 管理（scanAddons, getAddonDir 等）
+ *
+ * 注意：
+ * - JWT 工具位于 lib/jwt.ts
+ * - Logger 位于 lib/logger.ts
+ * - Validator 位于 lib/validator.ts
+ * - Database 管理位于 lib/database.ts
+ */
+
+import fs from 'node:fs';
+import { join } from 'pathe';
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
+import { isEmpty, isPlainObject } from 'es-toolkit/compat';
+import { snakeCase, camelCase, kebabCase } from 'es-toolkit/string';
+import { Env } from './config/env.js';
+import { Logger } from './lib/logger.js';
+import { paths } from './paths.js';
+import type { KeyValue } from './types/common.js';
+import type { JwtPayload, JwtSignOptions, JwtVerifyOptions } from './types/jwt';
+import type { Plugin } from './types/plugin.js';
+import type { ParsedFieldRule } from './types/common.js';
+
+// ========================================
+// API 响应工具
+// ========================================
+
+/**
+ * 成功响应
+ */
+export const Yes = <T = any>(msg: string = '', data: T | {} = {}, other: KeyValue = {}): { code: 0; msg: string; data: T | {} } & KeyValue => {
+    return {
+        ...other,
+        code: 0,
+        msg: msg,
+        data: data
+    };
+};
+
+/**
+ * 失败响应
+ */
+export const No = <T = any>(msg: string = '', data: T | {} = {}, other: KeyValue = {}): { code: 1; msg: string; data: T | {} } & KeyValue => {
+    return {
+        ...other,
+        code: 1,
+        msg: msg,
+        data: data
+    };
+};
+
+// ========================================
+// 字段转换工具（重新导出 lib/convert.ts）
+// ========================================
+
+/**
+ * 对象字段名转下划线
+ * @param obj - 源对象
+ * @returns 字段名转为下划线格式的新对象
+ *
+ * @example
+ * keysToSnake({ userId: 123, userName: 'John' }) // { user_id: 123, user_name: 'John' }
+ * keysToSnake({ createdAt: 1697452800000 }) // { created_at: 1697452800000 }
+ */
+export const keysToSnake = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const snakeKey = snakeCase(key);
+        result[snakeKey] = value;
+    }
+    return result;
+};
+
+/**
+ * 对象字段名转小驼峰
+ * @param obj - 源对象
+ * @returns 字段名转为小驼峰格式的新对象
+ *
+ * @example
+ * keysToCamel({ user_id: 123, user_name: 'John' }) // { userId: 123, userName: 'John' }
+ * keysToCamel({ created_at: 1697452800000 }) // { createdAt: 1697452800000 }
+ */
+export const keysToCamel = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = camelCase(key);
+        result[camelKey] = value;
+    }
+    return result;
+};
+
+/**
+ * 数组对象字段名批量转小驼峰
+ * @param arr - 源数组
+ * @returns 字段名转为小驼峰格式的新数组
+ *
+ * @example
+ * arrayKeysToCamel([
+ *   { user_id: 1, user_name: 'John' },
+ *   { user_id: 2, user_name: 'Jane' }
+ * ])
+ * // [{ userId: 1, userName: 'John' }, { userId: 2, userName: 'Jane' }]
+ */
+export const arrayKeysToCamel = <T = any>(arr: Record<string, any>[]): T[] => {
+    if (!arr || !Array.isArray(arr)) return arr as T[];
+    return arr.map((item) => keysToCamel<T>(item));
+};
+
+// ========================================
+// 对象操作工具
+// ========================================
+
+/**
+ * 挑选指定字段
+ */
+export const pickFields = <T extends Record<string, any>>(obj: T, keys: string[]): Partial<T> => {
+    if (!obj || (!isPlainObject(obj) && !Array.isArray(obj))) {
+        return {};
+    }
+
+    const result: any = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+
+    return result;
+};
+
+/**
+ * 字段清理
+ */
+export const fieldClear = <T extends Record<string, any> = any>(data: T, excludeValues: any[] = [null, undefined], keepValues: Record<string, any> = {}): Partial<T> => {
+    if (!data || !isPlainObject(data)) {
+        return {};
+    }
+
+    const result: any = {};
+
+    for (const [key, value] of Object.entries(data)) {
+        if (key in keepValues) {
+            if (Object.is(keepValues[key], value)) {
+                result[key] = value;
+                continue;
+            }
+        }
+
+        const shouldExclude = excludeValues.some((excludeVal) => Object.is(excludeVal, value));
+        if (shouldExclude) {
+            continue;
+        }
+
+        result[key] = value;
+    }
+
+    return result;
+};
+
+// ========================================
+// 日期时间工具
+// ========================================
+
+/**
+ * 计算性能时间差
+ */
+export const calcPerfTime = (startTime: number, endTime: number = Bun.nanoseconds()): string => {
+    const elapsedMs = (endTime - startTime) / 1_000_000;
+
+    if (elapsedMs < 1000) {
+        return `${elapsedMs.toFixed(2)} 毫秒`;
+    } else {
+        const elapsedSeconds = elapsedMs / 1000;
+        return `${elapsedSeconds.toFixed(2)} 秒`;
+    }
+};
+
+// ========================================
+// 表定义工具
+// ========================================
+
+/**
+ * 解析字段规则字符串
+ * 格式："字段名|类型|最小值|最大值|默认值|必填|正则"
+ * 注意：只分割前6个|，第7个|之后的所有内容（包括|）都属于正则表达式
+ */
+export const parseRule = (rule: string): ParsedFieldRule => {
+    const parts: string[] = [];
+    let currentPart = '';
+    let pipeCount = 0;
+
+    for (let i = 0; i < rule.length; i++) {
+        if (rule[i] === '|' && pipeCount < 6) {
+            parts.push(currentPart);
+            currentPart = '';
+            pipeCount++;
+        } else {
+            currentPart += rule[i];
+        }
+    }
+    parts.push(currentPart);
+
+    const [fieldName = '', fieldType = 'string', fieldMinStr = 'null', fieldMaxStr = 'null', fieldDefaultStr = 'null', fieldIndexStr = '0', fieldRegx = 'null'] = parts;
+
+    const fieldIndex = Number(fieldIndexStr) as 0 | 1;
+    const fieldMin = fieldMinStr !== 'null' ? Number(fieldMinStr) : null;
+    const fieldMax = fieldMaxStr !== 'null' ? Number(fieldMaxStr) : null;
+
+    let fieldDefault: any = fieldDefaultStr;
+    if (fieldType === 'number' && fieldDefaultStr !== 'null') {
+        fieldDefault = Number(fieldDefaultStr);
+    }
+
+    return {
+        name: fieldName,
+        type: fieldType as 'string' | 'number' | 'text' | 'array_string' | 'array_text',
+        min: fieldMin,
+        max: fieldMax,
+        default: fieldDefault,
+        index: fieldIndex,
+        regex: fieldRegx !== 'null' ? fieldRegx : null
+    };
+};
+
+// ========================================
+// Addon 管理工具
+// ========================================
+
+/**
+ * 扫描所有可用的 addon
+ */
+export const scanAddons = (): string[] => {
+    const beflyDir = join(paths.projectDir, 'node_modules', '@befly-addon');
+
+    if (!existsSync(beflyDir)) {
+        return [];
+    }
+
+    try {
+        return fs
+            .readdirSync(beflyDir)
+            .filter((name) => {
+                // addon 名称格式：admin, demo 等（不带 addon- 前缀）
+                const fullPath = join(beflyDir, name);
+                try {
+                    const stat = statSync(fullPath);
+                    return stat.isDirectory();
+                } catch {
+                    return false;
+                }
+            })
+            .sort();
+    } catch {
+        return [];
+    }
+};
+
+/**
+ * 获取 addon 的指定子目录路径
+ */
+export const getAddonDir = (addonName: string, subDir: string): string => {
+    return join(paths.projectDir, 'node_modules', '@befly-addon', addonName, subDir);
+};
+
+/**
+ * 检查 addon 子目录是否存在
+ */
+export const addonDirExists = (addonName: string, subDir: string): boolean => {
+    const dir = getAddonDir(addonName, subDir);
+    return existsSync(dir) && statSync(dir).isDirectory();
+};
+
+/**
+ * 获取插件目录列表
+ * @param addonsDir - addons 根目录路径
+ * @returns 插件名称数组
+ */
+export function getAddonDirs(addonsDir: string): string[] {
+    // try {
+    return readdirSync(addonsDir).filter((name) => {
+        const addonPath = path.join(addonsDir, name);
+        return statSync(addonPath).isDirectory() && !name.startsWith('_');
+    });
+    // } catch (error: any) {
+    //     Logger.error(`读取插件目录失败: ${addonsDir}`, error.message);
+    //     return [];
+    // }
+}

package/config/fields.ts

@@ -1,55 +0,0 @@
-/**
- * 通用字段定义
- *
- * 用于在 API 和表定义中复用常见字段规则
- *
- * 格式：`字段标签|数据类型|最小值|最大值|默认值|是否必填|正则表达式`
- *
- * 说明：
- * - 字段标签：用于显示的中文名称
- * - 数据类型：string、number、boolean、array_string、array_text 等
- * - 最小值：string 类型表示最小长度，number 类型表示最小数值，array 类型表示最小元素个数
- * - 最大值：string 类型表示最大长度，number 类型表示最大数值，array 类型表示最大元素个数
- * - 默认值：字段的默认值，无默认值时填 null
- * - 是否必填：0 表示非必填，1 表示必填
- * - 正则表达式：用于验证字段值的正则表达式，无验证时填 null
- *
- * 类型说明：
- * - array_string: 短数组，存储为 VARCHAR，建议设置 max 限制（如 0-100）
- * - array_text: 长数组，存储为 MEDIUMTEXT，min/max 可设为 null 表示不限制
- *
- * 正则表达式别名：
- * - 使用 @ 前缀可以引用内置正则表达式别名，例如：
- *   - @number: 纯数字
- *   - @alphanumeric: 字母+数字
- *   - @email: 邮箱格式
- *   - @phone: 中国手机号
- *   - @chinese: 纯中文
- * - 完整别名列表见 config/regexAliases.ts
- *
- * 示例：
- * - '用户ID|array_text|null|null|null|0|@number' - 数字数组
- * - '标签|array_string|0|50|null|0|@alphanumeric' - 字母数字数组
- */
-
-export const Fields = {
-    _id: 'ID|number|1|null|null|1|null',
-    email: '邮箱|string|5|100|null|1|^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
-    phone: '手机号|string|11|11|null|1|^1[3-9]\\d{9}$',
-    page: '页码|number|1|9999|1|0|null',
-    limit: '每页数量|number|1|100|10|0|null',
-    title: '标题|string|1|200|null|0|null',
-    description: '描述|string|0|500|null|0|null',
-    keyword: '关键词|string|1|50|null|1|null',
-    keywords: '关键词列表|array_string|0|50|null|0|null',
-    enabled: '启用状态|number|0|1|1|0|^(0|1)$',
-    date: '日期|string|10|10|null|0|^\\d{4}-\\d{2}-\\d{2}$',
-    datetime: '日期时间|string|19|25|null|0|^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}',
-    filename: '文件名|string|1|255|null|0|null',
-    url: '网址|string|5|500|null|0|^https?://',
-    tag: '标签|array_string|0|10|null|0|null',
-    startTime: '开始时间|number|0|9999999999999|null|0|null',
-    endTime: '结束时间|number|0|9999999999999|null|0|null'
-} as const;
-
-export default Fields;

package/config/regexAliases.ts

@@ -1,51 +0,0 @@
-/**
- * 内置正则表达式别名
- *
- * 使用方式：在字段定义的 regex 位置使用 @别名 格式
- * 例如：'字段名|array_text|null|null|null|0|@number'
- */
-
-export const RegexAliases = {
-    // 数字类型
-    number: '^\\d+$', // 纯数字
-    integer: '^-?\\d+$', // 整数（含负数）
-    float: '^-?\\d+(\\.\\d+)?$', // 浮点数
-    positive: '^[1-9]\\d*$', // 正整数（不含0）
-
-    // 字符串类型
-    word: '^[a-zA-Z]+$', // 纯字母
-    alphanumeric: '^[a-zA-Z0-9]+$', // 字母+数字
-    alphanumeric_: '^[a-zA-Z0-9_]+$', // 字母+数字+下划线
-    lowercase: '^[a-z]+$', // 小写字母
-    uppercase: '^[A-Z]+$', // 大写字母
-
-    // 中文
-    chinese: '^[\\u4e00-\\u9fa5]+$', // 纯中文
-    chinese_word: '^[\\u4e00-\\u9fa5a-zA-Z]+$', // 中文+字母
-
-    // 常用格式
-    email: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$', // 邮箱
-    phone: '^1[3-9]\\d{9}$', // 中国手机号
-    url: '^https?://', // URL
-    ip: '^((25[0-5]|2[0-4]\\d|[01]?\\d\\d?)\\.){3}(25[0-5]|2[0-4]\\d|[01]?\\d\\d?)$', // IPv4
-
-    // 特殊格式
-    uuid: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', // UUID
-    hex: '^[0-9a-fA-F]+$', // 十六进制
-    base64: '^[A-Za-z0-9+/=]+$', // Base64
-
-    // 日期时间
-    date: '^\\d{4}-\\d{2}-\\d{2}$', // YYYY-MM-DD
-    time: '^\\d{2}:\\d{2}:\\d{2}$', // HH:MM:SS
-    datetime: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}', // ISO 8601
-
-    // 代码相关
-    variable: '^[a-zA-Z_][a-zA-Z0-9_]*$', // 变量名
-    constant: '^[A-Z][A-Z0-9_]*$', // 常量名（大写）
-
-    // 空值
-    empty: '^$', // 空字符串
-    notempty: '.+' // 非空
-} as const;
-
-export type RegexAliasName = keyof typeof RegexAliases;

package/config/reserved.ts

@@ -1,96 +0,0 @@
-/**
- * 核心保留名称配置
- * 定义框架保留的资源名称，防止用户和 addon 使用
- */
-
-/**
- * 保留名称配置
- */
-export const RESERVED_NAMES = {
-    /**
-     * 核心表前缀（禁止用户使用）
-     */
-    tablePrefix: ['sys_'],
-
-    /**
-     * 核心 API 路由前缀（禁止用户使用）
-     */
-    apiRoutes: ['/api/health', '/api/tool'],
-
-    /**
-     * 核心插件名（禁止用户使用）
-     */
-    plugins: ['db', 'logger', 'redis', 'tool'],
-
-    /**
-     * 禁止用作 addon 名称
-     */
-    addonNames: ['app', 'api']
-} as const;
-
-/**
- * 检测表名是否使用了保留前缀
- */
-export function isReservedTableName(tableName: string): boolean {
-    return RESERVED_NAMES.tablePrefix.some((prefix) => tableName.startsWith(prefix));
-}
-
-/**
- * 检测 API 路由是否使用了保留路径
- */
-export function isReservedRoute(route: string): boolean {
-    // 移除方法前缀（如 POST/GET）
-    const path = route.replace(/^(GET|POST|PUT|DELETE|PATCH|OPTIONS|HEAD)\//i, '/');
-    return RESERVED_NAMES.apiRoutes.some((reserved) => path.startsWith(reserved));
-}
-
-/**
- * 检测插件名是否使用了保留名称
- */
-export function isReservedPluginName(pluginName: string): boolean {
-    // 检测核心插件名
-    if (RESERVED_NAMES.plugins.includes(pluginName)) {
-        return true;
-    }
-    // 检测是否使用点号命名空间但前缀是保留名称
-    if (pluginName.includes('.')) {
-        const prefix = pluginName.split('.')[0];
-        return RESERVED_NAMES.plugins.includes(prefix);
-    }
-    return false;
-}
-
-/**
- * 检测 addon 名称是否使用了保留名称
- */
-export function isReservedAddonName(addonName: string): boolean {
-    return RESERVED_NAMES.addonNames.includes(addonName.toLowerCase());
-}
-
-/**
- * 获取保留前缀列表（用于错误提示）
- */
-export function getReservedTablePrefixes(): string[] {
-    return [...RESERVED_NAMES.tablePrefix];
-}
-
-/**
- * 获取保留路由列表（用于错误提示）
- */
-export function getReservedRoutes(): string[] {
-    return [...RESERVED_NAMES.apiRoutes];
-}
-
-/**
- * 获取保留插件名列表（用于错误提示）
- */
-export function getReservedPlugins(): string[] {
-    return [...RESERVED_NAMES.plugins];
-}
-
-/**
- * 获取保留 addon 名称列表（用于错误提示）
- */
-export function getReservedAddonNames(): string[] {
-    return [...RESERVED_NAMES.addonNames];
-}

package/scripts/syncDb/tests/constants.test.ts

@@ -1,105 +0,0 @@
-/**
- * syncDb 常量模块测试
- */
-
-import { describe, test, expect } from 'bun:test';
-import { DB_VERSION_REQUIREMENTS, SYSTEM_FIELDS, SYSTEM_INDEX_FIELDS, CHANGE_TYPE_LABELS, MYSQL_TABLE_CONFIG, IS_MYSQL, IS_PG, IS_SQLITE, typeMapping } from '../constants.js';
-
-describe('syncDb/constants', () => {
-    describe('数据库版本要求', () => {
-        test('应定义 MySQL 最低版本', () => {
-            expect(DB_VERSION_REQUIREMENTS.MYSQL_MIN_MAJOR).toBe(8);
-        });
-
-        test('应定义 PostgreSQL 最低版本', () => {
-            expect(DB_VERSION_REQUIREMENTS.POSTGRES_MIN_MAJOR).toBe(17);
-        });
-
-        test('应定义 SQLite 最低版本', () => {
-            expect(DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION).toBe('3.50.0');
-            expect(DB_VERSION_REQUIREMENTS.SQLITE_MIN_VERSION_NUM).toBe(35000);
-        });
-    });
-
-    describe('系统字段定义', () => {
-        test('应包含 5 个系统字段', () => {
-            const fields = Object.keys(SYSTEM_FIELDS);
-            expect(fields).toHaveLength(5);
-            expect(fields).toContain('ID');
-            expect(fields).toContain('CREATED_AT');
-            expect(fields).toContain('UPDATED_AT');
-            expect(fields).toContain('DELETED_AT');
-            expect(fields).toContain('STATE');
-        });
-
-        test('每个系统字段应有名称和注释', () => {
-            expect(SYSTEM_FIELDS.ID.name).toBe('id');
-            expect(SYSTEM_FIELDS.ID.comment).toBe('主键ID');
-        });
-    });
-
-    describe('系统索引字段', () => {
-        test('应包含 3 个索引字段', () => {
-            expect(SYSTEM_INDEX_FIELDS).toHaveLength(3);
-            expect(SYSTEM_INDEX_FIELDS).toContain('created_at');
-            expect(SYSTEM_INDEX_FIELDS).toContain('updated_at');
-            expect(SYSTEM_INDEX_FIELDS).toContain('state');
-        });
-    });
-
-    describe('变更类型标签', () => {
-        test('应包含所有变更类型', () => {
-            expect(CHANGE_TYPE_LABELS.length).toBe('长度');
-            expect(CHANGE_TYPE_LABELS.datatype).toBe('类型');
-            expect(CHANGE_TYPE_LABELS.comment).toBe('注释');
-            expect(CHANGE_TYPE_LABELS.default).toBe('默认值');
-        });
-    });
-
-    describe('MySQL 表配置', () => {
-        test('应有默认配置', () => {
-            expect(MYSQL_TABLE_CONFIG.ENGINE).toBeDefined();
-            expect(MYSQL_TABLE_CONFIG.CHARSET).toBeDefined();
-            expect(MYSQL_TABLE_CONFIG.COLLATE).toBeDefined();
-        });
-
-        test('默认引擎应为 InnoDB', () => {
-            expect(MYSQL_TABLE_CONFIG.ENGINE).toMatch(/InnoDB/i);
-        });
-
-        test('默认字符集应为 utf8mb4', () => {
-            expect(MYSQL_TABLE_CONFIG.CHARSET).toMatch(/utf8mb4/i);
-        });
-    });
-
-    describe('数据库类型检测', () => {
-        test('IS_MYSQL, IS_PG, IS_SQLITE 三者只有一个为 true', () => {
-            const trueCount = [IS_MYSQL, IS_PG, IS_SQLITE].filter(Boolean).length;
-            expect(trueCount).toBe(1);
-        });
-
-        test('类型映射应包含所有字段类型', () => {
-            expect(typeMapping.number).toBeDefined();
-            expect(typeMapping.string).toBeDefined();
-            expect(typeMapping.text).toBeDefined();
-            expect(typeMapping.array_string).toBeDefined();
-            expect(typeMapping.array_text).toBeDefined();
-        });
-
-        test('不同数据库的类型映射应不同', () => {
-            if (IS_MYSQL) {
-                expect(typeMapping.number).toBe('BIGINT');
-                expect(typeMapping.string).toBe('VARCHAR');
-                expect(typeMapping.text).toBe('MEDIUMTEXT');
-            } else if (IS_PG) {
-                expect(typeMapping.number).toBe('BIGINT');
-                expect(typeMapping.string).toBe('character varying');
-                expect(typeMapping.text).toBe('TEXT');
-            } else if (IS_SQLITE) {
-                expect(typeMapping.number).toBe('INTEGER');
-                expect(typeMapping.string).toBe('TEXT');
-                expect(typeMapping.text).toBe('TEXT');
-            }
-        });
-    });
-});