SuperAPI AI 工具集

migrating-motoko

编程与开发

查看项目

更新于 10-16 05:06

技能介绍

用途:在 Motoko canister 升级时迁移 actor 状态。每次升级最多一个迁移函数,通过 actor 前的括号表达式挂载。若需 migrations/ 目录的多迁移方式,应改用 migrating-motoko-enhanced。

隐式迁移(无需代码):新增或删除 actor 字段、改变可变性(var ↔ let)、新增 variant 构造器、拓宽类型(Nat → Int)等兼容变更由运行时自动处理。

显式迁移适用:重命名字段、改变字段类型(如 Bool → variant、Int → Float)、拆分或合并字段、转换集合值。

语法:在 actor 前写 (with migration = Migration.run),也可内联函数或使用 import { migration } "migration"; 后写 (with migration)。

迁移函数规则:类型为 func (old : { ... }) : { ... },须为局部、非泛型,两个记录都使用可持久化类型(不能含函数或可变数组)。输入为旧 actor 字段,输出为新 actor 字段且须在新 actor 中存在且类型兼容。仅在升级时运行;全新安装时正常执行初始化器。若迁移 trap,升级中止,canister 保持旧版本。字段语义:同时出现在输入输出则被转换;仅输出为新字段;仅输入则被消费(编译器警告可能数据丢失);都不出现则保留或由声明初始化。

模块模式:把迁移放在单独模块,旧类型内联定义,不要从旧代码路径导入。字段必须有初始化器,因为迁移函数只在升级时运行。

常见模式:加默认字段、加可选字段、Bool 转 variant、重命名字段(消费旧名产生新名)、丢弃字段(输入消费、输出省略,编译器会警告)。

检查清单:判断隐式还是显式;显式则在 migration.mo 内联定义旧类型;迁移类型为 func (old : RecordIn) : RecordOut 且可持久化;用 (with migration = Migration.run) 挂载;不要用 preupgrade/postupgrade 做数据迁移;用 mops check --fix 和 mops build 验证。

限制:资料未提供收费、价格、平台等信息。