befly 2.3.2 → 3.0.0

package/plugins/tool.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool 插件 - TypeScript 版本
+ * 提供数据处理工具
+ */
+
+import { Tool } from '../utils/tool.js';
+import { Logger } from '../utils/logger.js';
+import type { Plugin } from '../types/plugin.js';
+import type { BeflyContext } from '../types/befly.js';
+
+/**
+ * Tool 插件
+ */
+const toolPlugin: Plugin = {
+    name: '_tool',
+    after: ['_redis', '_db'],
+
+    async onInit(befly: BeflyContext): Promise<Tool> {
+        try {
+            const tool = new Tool(befly);
+            Logger.info('Tool 插件初始化成功');
+            return tool;
+        } catch (error: any) {
+            Logger.error({
+                msg: 'Tool 初始化失败',
+                message: error.message,
+                stack: error.stack
+            });
+            throw error;
+        }
+    }
+};
+
+export default toolPlugin;

package/scripts/syncDb/apply.ts

@@ -0,0 +1,171 @@
+/**
+ * syncDb 变更应用模块
+ *
+ * 包含：
+ * - 比较字段定义变化
+ * - 应用表结构变更计划
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { parseRule } from '../../utils/tableHelper.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, CHANGE_TYPE_LABELS, typeMapping } from './constants.js';
+import { logFieldChange, resolveDefaultValue, isStringOrArrayType } from './helpers.js';
+import { executeDDLSafely, buildIndexSQL } from './ddl.js';
+import { rebuildSqliteTable } from './sqlite.js';
+import type { FieldChange, IndexAction, TablePlan, ColumnInfo } from './types.js';
+import type { SQL } from 'bun';
+
+// 是否为计划模式（从环境变量读取）
+const IS_PLAN = process.argv.includes('--plan');
+
+/**
+ * 比较字段定义变化
+ *
+ * 对比现有列信息和新的字段规则，识别变化类型：
+ * - 长度变化（string/array 类型）
+ * - 注释变化（MySQL/PG）
+ * - 数据类型变化
+ * - 默认值变化
+ *
+ * @param existingColumn - 现有列信息
+ * @param newRule - 新的字段规则字符串
+ * @param colName - 列名（未使用，保留参数兼容性）
+ * @returns 变化数组
+ */
+export function compareFieldDefinition(existingColumn: ColumnInfo, newRule: string, colName: string): FieldChange[] {
+    const parsed = parseRule(newRule);
+    const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+    const changes: FieldChange[] = [];
+
+    // 检查长度变化（string和array类型） - SQLite 不比较长度
+    if (!IS_SQLITE && isStringOrArrayType(fieldType)) {
+        if (existingColumn.length !== fieldMax) {
+            changes.push({
+                type: 'length',
+                current: existingColumn.length,
+                expected: fieldMax
+            });
+        }
+    }
+
+    // 检查注释变化（MySQL/PG 支持列注释）
+    if (!IS_SQLITE) {
+        const currentComment = existingColumn.comment || '';
+        if (currentComment !== fieldName) {
+            changes.push({
+                type: 'comment',
+                current: currentComment,
+                expected: fieldName
+            });
+        }
+    }
+
+    // 检查数据类型变化（按方言）
+    if (existingColumn.type.toLowerCase() !== typeMapping[fieldType].toLowerCase()) {
+        changes.push({
+            type: 'datatype',
+            current: existingColumn.type,
+            expected: typeMapping[fieldType].toLowerCase()
+        });
+    }
+
+    // 使用公共函数处理默认值
+    const expectedDefault = resolveDefaultValue(fieldDefault, fieldType);
+
+    // 检查默认值变化
+    if (String(existingColumn.defaultValue) !== String(expectedDefault)) {
+        changes.push({
+            type: 'default',
+            current: existingColumn.defaultValue,
+            expected: expectedDefault
+        });
+    }
+
+    return changes;
+}
+
+/**
+ * 将表结构计划应用到数据库（执行 DDL/索引/注释等）
+ *
+ * 根据数据库方言和计划内容，执行相应的 DDL 操作：
+ * - SQLite: 新增字段直接 ALTER，其他操作需要重建表
+ * - MySQL: 尝试在线 DDL（INSTANT/INPLACE）
+ * - PostgreSQL: 直接 ALTER
+ *
+ * @param sql - SQL 客户端实例
+ * @param tableName - 表名
+ * @param fields - 字段定义对象
+ * @param plan - 表结构变更计划
+ * @param globalCount - 全局统计对象（用于计数）
+ */
+export async function applyTablePlan(sql: SQL, tableName: string, fields: Record<string, string>, plan: TablePlan, globalCount: Record<string, number>): Promise<void> {
+    if (!plan || !plan.changed) return;
+
+    // SQLite: 仅支持部分 ALTER；需要时走重建
+    if (IS_SQLITE) {
+        if (plan.modifyClauses.length > 0 || plan.defaultClauses.length > 0) {
+            if (IS_PLAN) Logger.info(`[计划] 重建表 ${tableName} 以应用列修改/默认值变化`);
+            else await rebuildSqliteTable(sql, tableName, fields);
+        } else {
+            for (const c of plan.addClauses) {
+                const stmt = `ALTER TABLE "${tableName}" ${c}`;
+                if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+                else await sql.unsafe(stmt);
+            }
+        }
+    } else {
+        const clauses = [...plan.addClauses, ...plan.modifyClauses];
+        if (clauses.length > 0) {
+            const suffix = IS_MYSQL ? ', ALGORITHM=INSTANT, LOCK=NONE' : '';
+            const stmt = IS_MYSQL ? `ALTER TABLE \`${tableName}\` ${clauses.join(', ')}${suffix}` : `ALTER TABLE "${tableName}" ${clauses.join(', ')}`;
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 默认值专用 ALTER（SQLite 不支持）
+    if (plan.defaultClauses.length > 0) {
+        if (IS_SQLITE) {
+            Logger.warn(`SQLite 不支持修改默认值，表 ${tableName} 的默认值变更已跳过`);
+        } else {
+            const suffix = IS_MYSQL ? ', ALGORITHM=INSTANT, LOCK=NONE' : '';
+            const stmt = IS_MYSQL ? `ALTER TABLE \`${tableName}\` ${plan.defaultClauses.join(', ')}${suffix}` : `ALTER TABLE "${tableName}" ${plan.defaultClauses.join(', ')}`;
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else if (IS_MYSQL) await executeDDLSafely(sql, stmt);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 索引操作
+    for (const act of plan.indexActions) {
+        const stmt = buildIndexSQL(tableName, act.indexName, act.fieldName, act.action);
+        if (IS_PLAN) {
+            Logger.info(`[计划] ${stmt}`);
+        } else {
+            try {
+                await sql.unsafe(stmt);
+                if (act.action === 'create') {
+                    Logger.info(`[索引变化] 新建索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                } else {
+                    Logger.info(`[索引变化] 删除索引 ${tableName}.${act.indexName} (${act.fieldName})`);
+                }
+            } catch (error: any) {
+                Logger.error(`${act.action === 'create' ? '创建' : '删除'}索引失败: ${error.message}`);
+                Logger.error(`表名: ${tableName}, 索引名: ${act.indexName}, 字段: ${act.fieldName}`);
+                throw error;
+            }
+        }
+    }
+
+    // PG 列注释
+    if (IS_PG && plan.commentActions && plan.commentActions.length > 0) {
+        for (const stmt of plan.commentActions) {
+            if (IS_PLAN) Logger.info(`[计划] ${stmt}`);
+            else await sql.unsafe(stmt);
+        }
+    }
+
+    // 计数
+    globalCount.modifiedTables++;
+}

package/scripts/syncDb/constants.ts

@@ -0,0 +1,70 @@
+/**
+ * syncDb 常量定义模块
+ *
+ * 包含：
+ * - 数据库版本要求
+ * - 系统字段定义
+ * - 索引字段配置
+ * - 字段变更类型标签
+ */
+
+import { Env } from '../../config/env.js';
+
+/**
+ * 数据库版本要求
+ */
+export const DB_VERSION_REQUIREMENTS = {
+    MYSQL_MIN_MAJOR: 8,
+    POSTGRES_MIN_MAJOR: 17,
+    SQLITE_MIN_VERSION: '3.50.0',
+    SQLITE_MIN_VERSION_NUM: 35000 // 3 * 10000 + 50 * 100
+} as const;
+
+/**
+ * 系统字段定义（所有表都包含的固定字段）
+ */
+export const SYSTEM_FIELDS = {
+    ID: { name: 'id', comment: '主键ID' },
+    CREATED_AT: { name: 'created_at', comment: '创建时间' },
+    UPDATED_AT: { name: 'updated_at', comment: '更新时间' },
+    DELETED_AT: { name: 'deleted_at', comment: '删除时间' },
+    STATE: { name: 'state', comment: '状态字段' }
+} as const;
+
+/**
+ * 需要创建索引的系统字段
+ */
+export const SYSTEM_INDEX_FIELDS = ['created_at', 'updated_at', 'state'] as const;
+
+/**
+ * 字段变更类型的中文标签映射
+ */
+export const CHANGE_TYPE_LABELS = {
+    length: '长度',
+    datatype: '类型',
+    comment: '注释',
+    default: '默认值'
+} as const;
+
+/**
+ * MySQL 表配置（支持环境变量自定义）
+ */
+export const MYSQL_TABLE_CONFIG = {
+    ENGINE: Env.MYSQL_ENGINE || 'InnoDB',
+    CHARSET: Env.MYSQL_CHARSET || 'utf8mb4',
+    COLLATE: Env.MYSQL_COLLATE || 'utf8mb4_0900_as_cs'
+} as const;
+
+// 数据库类型判断
+export const DB = (Env.DB_TYPE || 'mysql').toLowerCase();
+export const IS_MYSQL = DB === 'mysql';
+export const IS_PG = DB === 'postgresql' || DB === 'postgres';
+export const IS_SQLITE = DB === 'sqlite';
+
+// 字段类型映射（按方言）
+export const typeMapping = {
+    number: IS_SQLITE ? 'INTEGER' : 'BIGINT',
+    string: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR',
+    text: IS_MYSQL ? 'MEDIUMTEXT' : 'TEXT',
+    array: IS_SQLITE ? 'TEXT' : IS_PG ? 'character varying' : 'VARCHAR'
+};

package/scripts/syncDb/ddl.ts

@@ -0,0 +1,182 @@
+/**
+ * syncDb DDL 构建模块
+ *
+ * 包含：
+ * - 构建索引 SQL
+ * - 生成 DDL 子句（添加/修改列）
+ * - 安全执行 DDL（MySQL 降级策略）
+ * - 构建系统列和业务列定义
+ */
+
+import { Logger } from '../../utils/logger.js';
+import { parseRule } from '../../utils/tableHelper.js';
+import { IS_MYSQL, IS_PG, IS_SQLITE, SYSTEM_INDEX_FIELDS, typeMapping } from './constants.js';
+import { quoteIdentifier, resolveDefaultValue, generateDefaultSql, getSqlType, escapeComment } from './helpers.js';
+import type { SQL } from 'bun';
+
+/**
+ * 构建索引操作 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 PRIMARY KEY AUTO_INCREMENT COMMENT "主键ID"', '`created_at` BIGINT NOT NULL DEFAULT 0 COMMENT "创建时间"', '`updated_at` BIGINT NOT NULL DEFAULT 0 COMMENT "更新时间"', '`deleted_at` BIGINT NOT NULL DEFAULT 0 COMMENT "删除时间"', '`state` BIGINT 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, string>): string[] {
+    const colDefs: string[] = [];
+
+    for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        const parsed = parseRule(fieldRule);
+        const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+        const sqlType = getSqlType(fieldType, fieldMax);
+
+        // 使用公共函数处理默认值
+        const actualDefault = resolveDefaultValue(fieldDefault, fieldType);
+        const defaultSql = generateDefaultSql(actualDefault, fieldType);
+
+        if (IS_MYSQL) {
+            colDefs.push(`\`${fieldKey}\` ${sqlType} NOT NULL${defaultSql} COMMENT "${escapeComment(fieldName)}"`);
+        } else {
+            colDefs.push(`"${fieldKey}" ${sqlType} NOT NULL${defaultSql}`);
+        }
+    }
+
+    return colDefs;
+}
+
+/**
+ * 生成字段 DDL 子句（不含 ALTER TABLE 前缀）
+ *
+ * @param fieldKey - 字段键名
+ * @param fieldRule - 字段规则字符串
+ * @param isAdd - 是否为添加字段（true）还是修改字段（false）
+ * @returns DDL 子句
+ */
+export function generateDDLClause(fieldKey: string, fieldRule: string, isAdd: boolean = false): string {
+    const parsed = parseRule(fieldRule);
+    const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
+    const sqlType = getSqlType(fieldType, fieldMax);
+
+    // 使用公共函数处理默认值
+    const actualDefault = resolveDefaultValue(fieldDefault, fieldType);
+    const defaultSql = generateDefaultSql(actualDefault, fieldType);
+
+    if (IS_MYSQL) {
+        return `${isAdd ? 'ADD COLUMN' : 'MODIFY COLUMN'} \`${fieldKey}\` ${sqlType} NOT NULL${defaultSql} COMMENT "${escapeComment(fieldName)}"`;
+    }
+    if (IS_PG) {
+        if (isAdd) return `ADD COLUMN IF NOT EXISTS "${fieldKey}" ${sqlType} NOT NULL${defaultSql}`;
+        // PG 修改：类型与非空可分条执行，生成 TYPE 改变；非空另由上层统一控制
+        return `ALTER COLUMN "${fieldKey}" TYPE ${sqlType}`;
+    }
+    // SQLite 仅支持 ADD COLUMN（>=3.50.0：支持 IF NOT EXISTS）
+    if (isAdd) return `ADD COLUMN IF NOT EXISTS "${fieldKey}" ${sqlType} NOT NULL${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/scripts/syncDb/helpers.ts

@@ -0,0 +1,172 @@
+/**
+ * syncDb 辅助函数模块
+ *
+ * 包含：
+ * - SQL 标识符引用
+ * - 日志格式化
+ * - 类型判断工具
+ * - 默认值处理
+ */
+
+import { IS_MYSQL, IS_PG, typeMapping } from './constants.js';
+import { isType } from '../../utils/typeHelper.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' 字符串转换为对应类型的默认值
+ *
+ * @param fieldDefault - 字段默认值（可能是 'null' 字符串）
+ * @param fieldType - 字段类型（number/string/text/array）
+ * @returns 实际默认值
+ *
+ * @example
+ * resolveDefaultValue('null', 'string') // => ''
+ * resolveDefaultValue('null', 'number') // => 0
+ * resolveDefaultValue('null', 'array') // => '[]'
+ * resolveDefaultValue('null', 'text') // => 'null'
+ * resolveDefaultValue('admin', 'string') // => 'admin'
+ */
+export function resolveDefaultValue(fieldDefault: any, fieldType: 'number' | 'string' | 'text' | 'array'): any {
+    if (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 (isType(actualDefault, 'number')) {
+            return ` DEFAULT ${actualDefault}`;
+        } else {
+            // 字符串需要转义单引号：' -> ''
+            const escaped = String(actualDefault).replace(/'/g, "''");
+            return ` DEFAULT '${escaped}'`;
+        }
+    }
+
+    return '';
+}
+
+/**
+ * 判断是否为字符串或数组类型（需要长度限制的类型）
+ *
+ * @param fieldType - 字段类型
+ * @returns 是否为 string 或 array
+ *
+ * @example
+ * isStringOrArrayType('string') // => true
+ * isStringOrArrayType('array') // => true
+ * isStringOrArrayType('number') // => false
+ * isStringOrArrayType('text') // => false
+ */
+export function isStringOrArrayType(fieldType: string): boolean {
+    return fieldType === 'string' || fieldType === 'array';
+}
+
+/**
+ * 获取 SQL 数据类型
+ *
+ * @param fieldType - 字段类型（number/string/text/array）
+ * @param fieldMax - 最大长度（string/array 类型需要）
+ * @returns SQL 类型字符串
+ *
+ * @example
+ * getSqlType('string', 100) // => 'VARCHAR(100)'
+ * getSqlType('number', null) // => 'BIGINT'
+ * getSqlType('text', null) // => 'TEXT'
+ * getSqlType('array', 500) // => 'VARCHAR(500)'
+ */
+export function getSqlType(fieldType: string, fieldMax: number | null): string {
+    if (isStringOrArrayType(fieldType)) {
+        return `${typeMapping[fieldType]}(${fieldMax})`;
+    }
+    return typeMapping[fieldType];
+}
+
+/**
+ * 转义 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 {
+    console.log(`   修改表 ${tableName} 的字段 ${fieldName} 的${changeLabel}: ${oldValue} -> ${newValue}`);
+}
+
+/**
+ * 格式化字段列表为可读字符串
+ *
+ * @param fields - 字段名数组
+ * @returns 格式化的字符串（逗号分隔）
+ */
+export function formatFieldList(fields: string[]): string {
+    return fields.map((f) => quoteIdentifier(f)).join(', ');
+}