直接在微服务启动时调用migrate.Up()是高危操作，必须拆分为可观察、可中断、可重试的步骤；应使用migrate create -ext sql -dir migrations -seq init_schema生成首对up/down文件，序号自增不可手动修改，已有线上库需先status再force 1标记版本。
直接在微服务启动时调用 migrate.Up() 是高危操作，尤其当多个实例并发启动、或 MySQL 表数据量大时，极易卡死、锁表、状态错乱。必须把迁移拆成「可观察、可中断、可重试」的步骤，而不是当成初始化黑盒。
用 CLI 初始化迁移目录和首版文件
别在代码里手动生成第一个迁移文件——那会导致团队间版本号不一致。用 migrate create 命令统一入口：
-
migrate create -ext sql -dir migrations -seq init_schema生成000001_init_schema.up.sql和.down.sql，序号由工具自增，禁止手动改数字 - 如果已有线上库，先跑
migrate -path ./migrations -database "$DB_URL" status看当前版本，再用migrate -path ./migrations -database "$DB_URL" force 1标记已存在结构为 v1，否则下次up会重复建表报错 -
.up.sql只放 DDL（CREATE TABLE、ADD COLUMN），别塞INSERT初始化数据——那是 seed，应单独管理
Go 代码中集成 migrate.Up 的避坑要点
在服务启动函数里调 migrate.Up() 很常见，但默认行为在生产环境极不友好：
- 必须传带超时的
context.Context，例如context.WithTimeout(ctx, 30*time.Second)，否则 MySQLALTER TABLE卡住时整个服务起不来 - 检查返回的
err类型：遇到migrate.ErrNoChange（无新迁移）或migrate.ErrLocked（被其他实例抢占锁）要正常处理，不能log.Fatal - MySQL 不支持事务性 DDL，所以
.up.sql里某条ALTER失败时，前面成功的语句不会回滚，.down.sql也不会自动触发——得靠人工干预 - 别把
database.URL写死，从环境变量读：os.Getenv("DB_URL")，并确保含必要参数，如 MySQL 要?parseTime=true&loc=UTC
MySQL ADD COLUMN 卡住的真实原因和解法
本地小表秒级完成，上线后 migrate up 卡住几十秒甚至超时，大概率是 MySQL 在线 DDL 锁表现异常：
立即学习“go语言免费学习笔记（深入）”；
- 避免写
ADD COLUMN x INT这种无位置声明的语句——MySQL 5.6+ 默认可能重排物理行结构，百万级表就锁死 - 显式指定位置：
ADD COLUMN x INT AFTER id，减少重组织开销 - 在 SQL 脚本里强制加在线算法：
ALTER TABLE users ADD COLUMN status TINYINT DEFAULT 0, ALGORITHM=INPLACE, LOCK=NONE;（注意：5.6 仅部分支持，5.7+ 更稳，8.0 基本无锁） - 预发环境必须用真实数据量压测单条迁移耗时，别信本地开发结果
最常被忽略的一点：迁移脚本不是一次性的部署动作，而是长期维护的「数据库契约」。每次改字段、加索引、删列，都得同步更新 .up.sql 和 .down.sql，且 down 必须能真正撤回变更——比如删外键要写在删主表之前，否则生产环境 down 会直接失败卡住。
