befly 3.8.18 → 3.8.20

package/sync/syncDb/ddl.ts

@@ -0,0 +1,194 @@
+/**
+ * syncDb DDL 构建模块
+ *
+ * 包含：
+ * - 构建索引 SQL
+ * - 生成 DDL 子句（添加/修改列）
+ * - 安全执行 DDL（MySQL 降级策略）
+ * - 构建系统列和业务列定义
+ */
+
+import { snakeCase } from 'es-toolkit/string';
+import { Logger } from '../../lib/logger.js';
+import { IS_MYSQL, IS_PG, typeMapping } from './constants.js';
+import { quoteIdentifier, resolveDefaultValue, generateDefaultSql, getSqlType, escapeComment } from './helpers.js';
+
+import type { SQL } from 'bun';
+import type { FieldDefinition, AnyObject } from 'befly/types/common.js';
+
+/**
+ * 构建索引操作 SQL（统一使用在线策略）
+ *
+ * @param tableName - 表名
+ * @param indexName - 索引名
+ * @param fieldName - 字段名
+ * @param action - 操作类型（create/drop）
+ * @returns SQL 语句
+ */
+export function buildIndexSQL(tableName: string, indexName: string, fieldName: string, action: 'create' | 'drop'): string {
+    const tableQuoted = quoteIdentifier(tableName);
+    const indexQuoted = quoteIdentifier(indexName);
+    const fieldQuoted = quoteIdentifier(fieldName);
+
+    if (IS_MYSQL) {
+        const parts = [];
+        if (action === 'create') {
+            parts.push(`ADD INDEX ${indexQuoted} (${fieldQuoted})`);
+        } else {
+            parts.push(`DROP INDEX ${indexQuoted}`);
+        }
+        // 始终使用在线算法
+        parts.push('ALGORITHM=INPLACE');
+        parts.push('LOCK=NONE');
+        return `ALTER TABLE ${tableQuoted} ${parts.join(', ')}`;
+    }
+
+    if (IS_PG) {
+        if (action === 'create') {
+            // 始终使用 CONCURRENTLY
+            return `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${indexQuoted} ON ${tableQuoted}(${fieldQuoted})`;
+        }
+        return `DROP INDEX CONCURRENTLY IF EXISTS ${indexQuoted}`;
+    }
+
+    // SQLite
+    if (action === 'create') {
+        return `CREATE INDEX IF NOT EXISTS ${indexQuoted} ON ${tableQuoted}(${fieldQuoted})`;
+    }
+    return `DROP INDEX IF EXISTS ${indexQuoted}`;
+}
+
+/**
+ * 构建系统字段列定义
+ *
+ * @returns 系统字段的列定义数组
+ */
+export function buildSystemColumnDefs(): string[] {
+    if (IS_MYSQL) {
+        return ['`id` BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT COMMENT "主键ID"', '`created_at` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT "创建时间"', '`updated_at` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT "更新时间"', '`deleted_at` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT "删除时间"', '`state` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT "状态字段"'];
+    }
+    return ['"id" INTEGER PRIMARY KEY', '"created_at" INTEGER NOT NULL DEFAULT 0', '"updated_at" INTEGER NOT NULL DEFAULT 0', '"deleted_at" INTEGER NOT NULL DEFAULT 0', '"state" INTEGER NOT NULL DEFAULT 0'];
+}
+
+/**
+ * 构建业务字段列定义
+ *
+ * @param fields - 字段定义对象
+ * @returns 业务字段的列定义数组
+ */
+export function buildBusinessColumnDefs(fields: Record<string, FieldDefinition>): string[] {
+    const colDefs: string[] = [];
+
+    for (const [fieldKey, fieldDef] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = snakeCase(fieldKey);
+
+        const sqlType = getSqlType(fieldDef.type, fieldDef.max, fieldDef.unsigned);
+
+        // 使用公共函数处理默认值
+        const actualDefault = resolveDefaultValue(fieldDef.default, fieldDef.type);
+        const defaultSql = generateDefaultSql(actualDefault, fieldDef.type);
+
+        // 构建约束
+        const uniqueSql = fieldDef.unique ? ' UNIQUE' : '';
+        const nullableSql = fieldDef.nullable ? ' NULL' : ' NOT NULL';
+
+        if (IS_MYSQL) {
+            colDefs.push(`\`${dbFieldName}\` ${sqlType}${uniqueSql}${nullableSql}${defaultSql} COMMENT "${escapeComment(fieldDef.name)}"`);
+        } else {
+            colDefs.push(`"${dbFieldName}" ${sqlType}${uniqueSql}${nullableSql}${defaultSql}`);
+        }
+    }
+
+    return colDefs;
+}
+
+/**
+ * 生成字段 DDL 子句（不含 ALTER TABLE 前缀）
+ *
+ * @param fieldKey - 字段键名
+ * @param fieldDef - 字段定义对象
+ * @param isAdd - 是否为添加字段（true）还是修改字段（false）
+ * @returns DDL 子句
+ */
+export function generateDDLClause(fieldKey: string, fieldDef: FieldDefinition, isAdd: boolean = false): string {
+    // 转换字段名为下划线格式
+    const dbFieldName = snakeCase(fieldKey);
+
+    const sqlType = getSqlType(fieldDef.type, fieldDef.max, fieldDef.unsigned);
+
+    // 使用公共函数处理默认值
+    const actualDefault = resolveDefaultValue(fieldDef.default, fieldDef.type);
+    const defaultSql = generateDefaultSql(actualDefault, fieldDef.type);
+
+    // 构建约束
+    const uniqueSql = fieldDef.unique ? ' UNIQUE' : '';
+    const nullableSql = fieldDef.nullable ? ' NULL' : ' NOT NULL';
+
+    if (IS_MYSQL) {
+        return `${isAdd ? 'ADD COLUMN' : 'MODIFY COLUMN'} \`${dbFieldName}\` ${sqlType}${uniqueSql}${nullableSql}${defaultSql} COMMENT "${escapeComment(fieldDef.name)}"`;
+    }
+    if (IS_PG) {
+        if (isAdd) return `ADD COLUMN IF NOT EXISTS "${dbFieldName}" ${sqlType}${uniqueSql}${nullableSql}${defaultSql}`;
+        // PG 修改：类型与非空可分条执行，生成 TYPE 改变；非空另由上层统一控制
+        return `ALTER COLUMN "${dbFieldName}" TYPE ${sqlType}`;
+    }
+    // SQLite 仅支持 ADD COLUMN（>=3.50.0：支持 IF NOT EXISTS）
+    if (isAdd) return `ADD COLUMN IF NOT EXISTS "${dbFieldName}" ${sqlType}${uniqueSql}${nullableSql}${defaultSql}`;
+    return '';
+}
+
+/**
+ * 安全执行 DDL 语句（MySQL 降级策略）
+ *
+ * 执行 DDL 时按以下顺序尝试：
+ * 1. ALGORITHM=INSTANT (最快，无表锁)
+ * 2. ALGORITHM=INPLACE (在线 DDL)
+ * 3. 传统 DDL (可能需要表锁)
+ *
+ * @param sql - SQL 客户端实例
+ * @param stmt - DDL 语句
+ * @returns 是否执行成功
+ * @throws {Error} 如果所有尝试都失败
+ */
+export async function executeDDLSafely(sql: SQL, stmt: string): Promise<boolean> {
+    try {
+        await sql.unsafe(stmt);
+        return true;
+    } catch (error: any) {
+        // MySQL 专用降级路径
+        if (stmt.includes('ALGORITHM=INSTANT')) {
+            const inplaceSql = stmt.replace(/ALGORITHM=INSTANT/g, 'ALGORITHM=INPLACE');
+            try {
+                await sql.unsafe(inplaceSql);
+                return true;
+            } catch (inplaceError) {
+                // 最后尝试传统DDL：移除 ALGORITHM/LOCK 附加子句后执行
+                const traditionSql = stmt
+                    .replace(/,\s*ALGORITHM=INPLACE/g, '')
+                    .replace(/,\s*ALGORITHM=INSTANT/g, '')
+                    .replace(/,\s*LOCK=(NONE|SHARED|EXCLUSIVE)/g, '');
+                await sql.unsafe(traditionSql);
+                return true;
+            }
+        } else {
+            throw error;
+        }
+    }
+}
+
+/**
+ * PG 兼容类型变更识别：无需数据重写的宽化型变更
+ *
+ * @param currentType - 当前类型
+ * @param newType - 新类型
+ * @returns 是否为兼容变更
+ */
+export function isPgCompatibleTypeChange(currentType: string, newType: string): boolean {
+    const c = String(currentType || '').toLowerCase();
+    const n = String(newType || '').toLowerCase();
+    // varchar -> text 视为宽化
+    if (c === 'character varying' && n === 'text') return true;
+    // text -> character varying 非宽化（可能截断），不兼容
+    return false;
+}

package/sync/syncDb/helpers.ts

@@ -0,0 +1,200 @@
+/**
+ * syncDb 辅助工具模块
+ *
+ * 包含：
+ * - 标识符引用（反引号/双引号转义）
+ * - 默认值处理
+ * - 日志输出格式化
+ */
+
+import { IS_MYSQL, IS_PG, typeMapping } from './constants.js';
+import { Logger } from '../../lib/logger.js';
+
+/**
+ * 根据数据库类型引用标识符
+ *
+ * @param identifier - 标识符（表名、列名等）
+ * @returns 引用后的标识符
+ *
+ * @example
+ * quoteIdentifier('user_table')
+ * // MySQL: `user_table`
+ * // PostgreSQL: "user_table"
+ * // SQLite: user_table
+ */
+export function quoteIdentifier(identifier: string): string {
+    if (IS_MYSQL) return `\`${identifier}\``;
+    if (IS_PG) return `"${identifier}"`;
+    return identifier; // SQLite 无需引用
+}
+
+/**
+ * 处理默认值：将 null 或 'null' 字符串转换为对应类型的默认值
+ *
+ * @param fieldDefault - 字段默认值（可能是 null 或 'null' 字符串）
+ * @param fieldType - 字段类型（number/string/text/array）
+ * @returns 实际默认值
+ *
+ * @example
+ * resolveDefaultValue(null, 'string') // => ''
+ * resolveDefaultValue(null, 'number') // => 0
+ * resolveDefaultValue('null', 'number') // => 0
+ * resolveDefaultValue(null, 'array') // => '[]'
+ * resolveDefaultValue(null, 'text') // => 'null'
+ * resolveDefaultValue('admin', 'string') // => 'admin'
+ * resolveDefaultValue(0, 'number') // => 0
+ */
+export function resolveDefaultValue(fieldDefault: any, fieldType: 'number' | 'string' | 'text' | 'array'): any {
+    // null 或字符串 'null' 都表示使用类型默认值
+    if (fieldDefault !== null && fieldDefault !== 'null') {
+        return fieldDefault;
+    }
+
+    // null 表示使用类型默认值
+    switch (fieldType) {
+        case 'number':
+            return 0;
+        case 'string':
+            return '';
+        case 'array':
+            return '[]';
+        case 'text':
+            // text 类型不设置默认值，保持 'null'
+            return 'null';
+        default:
+            return fieldDefault;
+    }
+}
+
+/**
+ * 生成 SQL DEFAULT 子句
+ *
+ * @param actualDefault - 实际默认值（已经过 resolveDefaultValue 处理）
+ * @param fieldType - 字段类型
+ * @returns SQL DEFAULT 子句字符串（包含前导空格），如果不需要则返回空字符串
+ *
+ * @example
+ * generateDefaultSql(0, 'number') // => ' DEFAULT 0'
+ * generateDefaultSql('admin', 'string') // => " DEFAULT 'admin'"
+ * generateDefaultSql('', 'string') // => " DEFAULT ''"
+ * generateDefaultSql('null', 'text') // => ''
+ */
+export function generateDefaultSql(actualDefault: any, fieldType: 'number' | 'string' | 'text' | 'array'): string {
+    // text 类型不设置默认值
+    if (fieldType === 'text' || actualDefault === 'null') {
+        return '';
+    }
+
+    // 仅 number/string/array 类型设置默认值
+    if (fieldType === 'number' || fieldType === 'string' || fieldType === 'array') {
+        if (typeof actualDefault === 'number' && !Number.isNaN(actualDefault)) {
+            return ` DEFAULT ${actualDefault}`;
+        } else {
+            // 字符串需要转义单引号：' -> ''
+            const escaped = String(actualDefault).replace(/'/g, "''");
+            return ` DEFAULT '${escaped}'`;
+        }
+    }
+
+    return '';
+}
+
+/**
+ * 判断是否为字符串或数组类型（需要长度参数）
+ *
+ * @param fieldType - 字段类型
+ * @returns 是否为字符串或数组类型
+ *
+ * @example
+ * isStringOrArrayType('string') // => true
+ * isStringOrArrayType('array_string') // => true
+ * isStringOrArrayType('array_text') // => false
+ * isStringOrArrayType('number') // => false
+ * isStringOrArrayType('text') // => false
+ */
+export function isStringOrArrayType(fieldType: string): boolean {
+    return fieldType === 'string' || fieldType === 'array_string';
+}
+
+/**
+ * 获取 SQL 数据类型
+ *
+ * @param fieldType - 字段类型（number/string/text/array_string/array_text）
+ * @param fieldMax - 最大长度（string/array_string 类型需要）
+ * @param unsigned - 是否无符号（仅 MySQL number 类型有效）
+ * @returns SQL 类型字符串
+ *
+ * @example
+ * getSqlType('string', 100) // => 'VARCHAR(100)'
+ * getSqlType('number', null, true) // => 'BIGINT UNSIGNED'
+ * getSqlType('text', null) // => 'MEDIUMTEXT'
+ * getSqlType('array_string', 500) // => 'VARCHAR(500)'
+ * getSqlType('array_text', null) // => 'MEDIUMTEXT'
+ */
+export function getSqlType(fieldType: string, fieldMax: number | null, unsigned: boolean = false): string {
+    if (isStringOrArrayType(fieldType)) {
+        return `${typeMapping[fieldType]}(${fieldMax})`;
+    }
+    // 处理 UNSIGNED 修饰符（仅 MySQL number 类型）
+    const baseType = typeMapping[fieldType] || 'TEXT';
+    if (IS_MYSQL && fieldType === 'number' && unsigned) {
+        return `${baseType} UNSIGNED`;
+    }
+    return baseType;
+}
+
+/**
+ * 转义 SQL 注释中的双引号
+ *
+ * @param str - 注释字符串
+ * @returns 转义后的字符串
+ *
+ * @example
+ * escapeComment('用户名称') // => '用户名称'
+ * escapeComment('用户"昵称"') // => '用户\\"昵称\\"'
+ */
+export function escapeComment(str: string): string {
+    return String(str).replace(/"/g, '\\"');
+}
+
+/**
+ * 记录字段变更信息（紧凑格式）
+ *
+ * @param tableName - 表名
+ * @param fieldName - 字段名
+ * @param changeType - 变更类型（length/datatype/comment/default）
+ * @param oldValue - 旧值
+ * @param newValue - 新值
+ * @param changeLabel - 变更类型的中文标签
+ */
+export function logFieldChange(tableName: string, fieldName: string, changeType: string, oldValue: any, newValue: any, changeLabel: string): void {
+    Logger.debug(`  ~ 修改 ${fieldName} ${changeLabel}: ${oldValue} -> ${newValue}`);
+}
+
+/**
+ * 格式化字段列表为可读字符串
+ *
+ * @param fields - 字段名数组
+ * @returns 格式化的字符串（逗号分隔）
+ */
+export function formatFieldList(fields: string[]): string {
+    return fields.map((f) => quoteIdentifier(f)).join(', ');
+}
+
+/**
+ * 为字段定义应用默认值
+ *
+ * @param fieldDef - 字段定义对象
+ */
+export function applyFieldDefaults(fieldDef: any): void {
+    fieldDef.detail = fieldDef.detail ?? '';
+    fieldDef.min = fieldDef.min ?? 0;
+    fieldDef.max = fieldDef.max ?? 100;
+    fieldDef.default = fieldDef.default ?? null;
+    fieldDef.index = fieldDef.index ?? false;
+    fieldDef.unique = fieldDef.unique ?? false;
+    fieldDef.comment = fieldDef.comment ?? '';
+    fieldDef.nullable = fieldDef.nullable ?? false;
+    fieldDef.unsigned = fieldDef.unsigned ?? true;
+    fieldDef.regexp = fieldDef.regexp ?? null;
+}

package/sync/syncDb/index.ts

@@ -0,0 +1,164 @@
+/**
+ * syncDb 主入口文件
+ *
+ * 功能：
+ * - 协调所有模块，执行数据库表结构同步
+ * - 处理核心表、项目表、addon 表
+ * - 提供统计信息和错误处理
+ */
+
+import { basename, resolve } from 'pathe';
+import { existsSync } from 'node:fs';
+import { snakeCase } from 'es-toolkit/string';
+import { Database } from '../../lib/database.js';
+import { RedisHelper } from '../../lib/redisHelper.js';
+import { checkTable } from '../../checks/checkTable.js';
+import { scanFiles, scanAddons, addonDirExists, getAddonDir } from 'befly-util';
+import { Logger } from '../../lib/logger.js';
+import { projectDir } from '../../paths.js';
+
+// 导入模块化的功能
+import { ensureDbVersion } from './version.js';
+import { tableExists } from './schema.js';
+import { modifyTable } from './table.js';
+import { createTable } from './tableCreate.js';
+import { applyFieldDefaults } from './helpers.js';
+import type { SQL } from 'bun';
+import type { BeflyOptions, SyncDbOptions } from '../../types/index.js';
+
+// 全局 SQL 客户端实例
+let sql: SQL | null = null;
+
+// 记录处理过的表名（用于清理缓存）
+const processedTables: string[] = [];
+
+/**
+ * 主同步函数
+ *
+ * 流程：
+ * 1. 验证表定义文件
+ * 2. 建立数据库连接并检查版本
+ * 3. 扫描表定义文件（核心表、项目表、addon表）
+ * 4. 对比并应用表结构变更
+ */
+export const SyncDb = async (config: BeflyOptions, options: SyncDbOptions = {}): Promise<void> => {
+    try {
+        // 清空处理记录
+        processedTables.length = 0;
+
+        // 验证表定义文件
+        await checkTable();
+
+        // 建立数据库连接并检查版本
+        sql = await Database.connectSql({ max: 1 });
+        await ensureDbVersion(sql);
+
+        // 初始化 Redis 连接（用于清理缓存）
+        await Database.connectRedis();
+
+        // 扫描表定义文件
+        const directories: Array<{ path: string; type: 'app' | 'addon'; addonName?: string; addonNameSnake?: string }> = [];
+
+        // 1. 项目表（无前缀）- 如果 tables 目录存在
+        const projectTablesDir = resolve(projectDir, 'tables');
+        if (existsSync(projectTablesDir)) {
+            directories.push({ path: projectTablesDir, type: 'app' });
+        }
+
+        // 添加所有 addon 的 tables 目录（addon_{name}_ 前缀）
+        const addons = scanAddons();
+        for (const addon of addons) {
+            if (addonDirExists(addon, 'tables')) {
+                directories.push({
+                    path: getAddonDir(addon, 'tables'),
+                    type: 'addon',
+                    addonName: addon,
+                    addonNameSnake: snakeCase(addon) // 提前转换，避免每个文件都转换
+                });
+            }
+        }
+
+        // 处理表文件
+        for (const dirConfig of directories) {
+            const { path: dir, type, addonName } = dirConfig;
+            const dirType = type === 'addon' ? `组件${addonName}` : '项目';
+
+            const files = await scanFiles(dir, '*.json');
+
+            for (const { filePath: file, fileName } of files) {
+                // 确定表名：
+                // - addon 表：{addonName}_{表名}
+                //   例如：admin addon 的 user.json → admin_user
+                // - 项目表：{表名}
+                //   例如：user.json → user
+                let tableName = snakeCase(fileName);
+                if (type === 'addon' && dirConfig.addonNameSnake) {
+                    // addon 表，使用提前转换好的名称
+                    tableName = `addon_${dirConfig.addonNameSnake}_${tableName}`;
+                }
+
+                // 如果指定了表名，则只同步该表
+                if (options.table && options.table !== tableName) {
+                    continue;
+                }
+
+                const tableDefinitionModule = await import(file, { with: { type: 'json' } });
+                const tableDefinition = tableDefinitionModule.default;
+
+                // 为字段属性设置默认值
+                for (const fieldDef of Object.values(tableDefinition)) {
+                    applyFieldDefaults(fieldDef);
+                }
+
+                const dbName = config.plugins?.db?.database;
+                const existsTable = await tableExists(sql!, tableName, dbName);
+
+                // 读取 force 参数
+                const force = options.force || false;
+
+                if (existsTable) {
+                    await modifyTable(sql!, tableName, tableDefinition, force, dbName);
+                } else {
+                    await createTable(sql!, tableName, tableDefinition);
+                }
+
+                // 记录处理过的表名（用于清理缓存）
+                processedTables.push(tableName);
+            }
+        }
+
+        // 清理 Redis 缓存（如果有表被处理）
+        if (processedTables.length > 0) {
+            Logger.debug(`🧹 清理 ${processedTables.length} 个表的字段缓存...`);
+
+            const redisHelper = new RedisHelper();
+            for (const tableName of processedTables) {
+                const cacheKey = `table:columns:${tableName}`;
+                try {
+                    await redisHelper.del(cacheKey);
+                } catch (error: any) {
+                    Logger.warn(`清理表 ${tableName} 的缓存失败: ${error.message}`);
+                }
+            }
+
+            Logger.debug(`✓ 已清理表字段缓存`);
+        }
+    } catch (error: any) {
+        Logger.error(`数据库同步失败`, error);
+        throw error;
+    } finally {
+        if (sql) {
+            try {
+                await Database.disconnectSql();
+            } catch (error: any) {
+                Logger.warn(`关闭数据库连接时出错: ${error.message}`);
+            }
+        }
+
+        try {
+            await Database.disconnectRedis();
+        } catch (error: any) {
+            Logger.warn(`关闭 Redis 连接时出错: ${error.message}`);
+        }
+    }
+};