升级XORM需替换Sync为Sync2、显式声明主键与自增标签、校准时间字段精度、对齐migrate版本、统一传参为结构体指针、补全LIMIT数值。
升级 XORM 框架版本时，若未检查接口变更、标签行为调整与迁移逻辑兼容性，可能导致 Sync2 失效、字段映射错乱或事务回滚静默失败。
确认当前版本与目标版本的兼容性分界点
执行 go list -m github.com/go-xorm/xorm 查看当前版本；XORM v1.3.0（2024年10月发布）起正式弃用 engine.Sync()，仅保留 engine.Sync2() 作为结构同步唯一入口。v1.2.x 及更早版本中仍可使用 Sync，但行为不一致：Sync 不校验字段非空约束，Sync2 则强制校验并报错。
若项目中存在 engine.Sync(&User{}) 调用，必须全部替换为 engine.Sync2(&User{})，否则升级后新字段可能无法写入数据库且无提示。
检查结构体标签是否符合新版解析规则
方法一：主键与自增字段必须显式声明
v1.3.0+ 版本不再自动推断 Id int64 为主键，必须添加 `xorm:"pk autoincr"` 标签，否则 Sync2 会忽略主键设置，导致 INSERT 报错“Field 'id' doesn't have a default value”。
方法二：时间字段类型需匹配驱动精度
MySQL 驱动在 v1.3.5+ 中默认启用 parseTime=true，若结构体中定义 Created time.Time `xorm:"created"` 但数据库列为 DATETIME（无微秒），Sync2 将拒绝同步——必须将列改为 DATETIME(6) 或在连接串中显式关闭 parseTime=false。
【关键前提】 升级前需运行 SELECT COLUMN_NAME, DATA_TYPE, DATETIME_PRECISION FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'your_db' AND COLUMN_NAME IN ('created', 'updated'); 核对实际精度。
迁移脚本与 xorm/migrate 扩展包协同验证
第一步：检查 xorm/migrate 版本是否与 XORM 主版本对齐
github.com/go-xorm/migrate v1.0.0 仅兼容 XORM v1.2.x；v1.1.0（2025年3月发布）起要求 XORM ≥ v1.3.0，否则 migrate.NewMigrator(engine) 初始化时 panic：“unknown method Sync2”。
第二步：Rollback 函数中禁止混用结构体指针与值
旧版允许 tx.DropTables(Person{})（传值），新版严格要求 &Person{}（传地址），否则 DropTables 内部反射获取表名失败，静默跳过删除操作。
第三步：原生 SQL 迁移中的 LIMIT 子句必须显式限定
v1.3.2+ 对 MySQL 执行 UPDATE ... LIMIT 时，若未指定 LIMIT 数值（如只写 LIMIT），会触发语法错误；此前版本仅警告。所有迁移中含 LIMIT 的语句需补全数值，例如 LIMIT 1000。
