xorm 框架使用 sync2 方法自动同步数据表结构，调用 engine.sync2(models...) 即可。该方法会对比 go 结构体与数据库现有表，自动执行创建新表、添加缺失列或修改列类型等操作，确保数据库 schema 与代码定义一致。
如何初始化引擎并调用 Sync2
在使用 Sync2 前，必须先通过 xorm.NewEngine 创建引擎实例，并将包含 ORM 标签的 Go 结构体作为参数传入。该函数接收可变数量的结构体指针，内部会遍历每个结构体的字段，解析 xorm 标签以生成对应的 SQL 语句（如 CREATE TABLE 或 ALTER TABLE）并执行。
package main
import (
"fmt"
"log"
"time"
"xorm.io/xorm"
_ "github.com/go-sql-driver/mysql"
)
type User struct {
ID int64 `xorm:"pk autoincr"`
Name string `xorm:"varchar(255) notnull"`
Age int `xorm:"int default 0"`
CreatedAt time.Time `xorm:"created"`
}
func main() {
dsn := "user:password@tcp(127.0.0.1:3306)/testdb?charset=utf8mb4"
engine, err := xorm.NewEngine("mysql", dsn)
if err != nil {
log.Fatal(err)
}
defer engine.Close()
// 同步表结构
err = engine.Sync2(new(User))
if err != nil {
log.Fatal(err)
}
fmt.Println("Table synced successfully")
}
上述代码中，User 结构体定义了表结构，engine.Sync2(new(User)) 会检查 user 表是否存在。如果不存在则创建，如果存在但缺少 age 列，则会自动添加该列。注意 new(User) 传递的是结构体实例而非类型，因为 XORM 需要反射获取具体值。
Sync2 如何处理字段变更与冲突
Sync2 在同步过程中会处理字段类型的变更和默认值的调整。当结构体中的字段类型与数据库不一致时，XORM 会尝试执行 ALTER TABLE ... MODIFY COLUMN 来修正类型。对于新增字段，它会添加带有默认值的列；对于删除字段，Sync2 默认不会删除数据库中的列，以保持数据安全。若需完全重置表结构，应结合 DropTables 使用。
// 验证 Sync2 的行为
func testSyncBehavior() {
type Product struct {
ID int64 `xorm:"pk autoincr"`
Name string `xorm:"varchar(100) unique"`
Price float64 `xorm:"decimal(10,2) default 0.00"`
}
// 假设数据库中已有 product 表，且 Price 列为 int 类型
// Sync2 会将 Price 列修改为 decimal(10,2)
err := engine.Sync2(new(Product))
if err != nil {
log.Printf("Sync error: %v", err)
} else {
fmt.Println("Product table structure updated")
}
}
在实际使用中，unique 标签会触发唯一索引的创建或更新。如果数据库中存在重复数据导致唯一约束冲突，Sync2 可能会报错。因此，在生产环境中同步前应确保数据一致性。此外，Sync2 仅同步结构，不迁移数据，旧数据保留在原列中，类型转换失败时需手动处理。
Sync2 返回错误时的常见原因
调用 Sync2 时若遇到错误，通常源于权限不足、连接异常或结构体定义冲突。例如，数据库用户缺乏 ALTER 权限会导致 permission denied 错误。若结构体字段标签语法错误，如 xorm:"pk autoincr" 拼写错误，XORM 可能无法正确解析，进而生成无效 SQL。此外，若多个 Goroutine 同时调用 Sync2 同步同一张表，可能引发锁竞争或状态不一致，建议在主流程初始化阶段串行执行。
