简介
从 Discourse 版本 3.2.0.beta3 开始,Discourse 主题/组件可以利用迁移(migrations)功能来无缝演进和修改其设置。此功能通过受控方式处理设置变更,确保主题更新不会破坏现有安装。
何时使用迁移
以下常见场景特别需要使用迁移:
- 更改设置的类型(例如,从逗号分隔的字符串更改为列表)。
- 重命名设置。
- 修改存储在设置中的数据结构或格式。
在这些场景中,如果在 settings.yml 文件中更改了设置类型或名称,但未提供配套的迁移文件,那么对于已将设置改为非默认值的现有安装,用户所做的更改将会丢失,并且主题更新后可能会导致功能异常。
为了确保更新主题设置时的平滑过渡,主题开发者应提供一个迁移文件,指导 Discourse 核心如何将符合旧版 settings.yml 的现有状态迁移至新版。
迁移文件
迁移是位于主题的 migrations/settings 目录中的 JavaScript 文件,遵循 XXXX-migration-name.js 的命名约定。XXXX 前缀是版本号,从 0001 开始按顺序递增,用于确定执行顺序。
名称应简明扼要地描述迁移目的,仅限使用字母、数字、连字符和下划线,且长度不超过 150 个字符。迁移根据其版本号数值按升序执行。
我们建议第一个迁移从 0001 开始,第二个迁移从 0002 开始,依此类推。请注意,如果迁移版本低于 1000,则必须在前面补零以凑足 4 位数,因为迁移文件名必须以 4 位数字开头。基于同样的原因,目前每个主题最多只能有 9999 个迁移,但未来可能会改变这一限制。
迁移函数
标准 JavaScript 特性(如类、函数、数组、映射等)均可在迁移中使用。Discourse 核心唯一的期望是:每个迁移文件必须导出一个作为入口点的默认函数。该函数接收一个 Map 对象,该对象代表修改后的主题设置,并返回一个反映所有设置最终期望状态的 Map 对象。
示例
重命名主题设置:
// 文件名: 0001-rename-old-setting.js
export default function migrate(settings) {
if (settings.has("old_setting_name")) {
settings.set("new_setting_name", settings.get("old_setting_name"));
settings.delete("old_setting_name");
}
return settings;
}
此迁移应伴随 settings.yml 文件中设置重命名的操作。
将逗号分隔的字符串设置转换为适当的列表:
// 文件名: 0001-convert-string-setting-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split(",");
settings.set("list_setting", list.join("|"));
}
return settings;
}
与上一个示例类似,此迁移应伴随在 settings.yml 文件中将设置类型从 string 更改为 list 的操作。
重命名枚举(enum)设置中的选项:
// 文件名: 0001-rename-enum-choice.js
export default function migrate(settings) {
if (settings.get("enum_setting") === "old_option") {
settings.set("enum_setting", "new_option");
}
return settings;
}
向列表设置中添加新项:
// 文件名: 0001-add-item-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split("|");
list.push("new_item");
settings.set("list_setting", list.join("|"));
} else {
settings.set("list_setting", "new_item");
}
return settings;
}
将文本设置移至主题翻译
当用主题翻译替换字符串设置时,使用 helpers.migrateSettingToTranslation(settingName, translationKey):
// 文件名: 0002-migrate-heading.js
export default function migrate(settings, helpers) {
helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
return settings;
}
在相同的更新中,从 settings.yml 中移除 heading_text,并在 locales/en.yml 中声明目标:
en:
homepage:
heading: ""
此辅助函数将已保存的设置移至英语主题翻译覆盖层,并移除该设置。英语是其他语言的后备(fallback)区域设置,因此访问者将继续看到已保存的文本,直到为其区域设置提供了翻译。声明了相同键但值为空的区域设置文件会针对其区域隐藏该已保存的英语文本。这也适用于未来更新中添加的区域设置文件。
- 辅助函数从传递给迁移的
settings映射中读取数据。仅迁移已保存的设置。如果旧设置具有非空的默认值,请在en.yml中使用该默认值,以确保未保存值的站点保留其文本。 - 设置值必须是字符串,且目标必须是已声明的文本键。空字符串将被保留。
- 现有的英语覆盖层(包括空值)不会被覆盖。如果多个迁移针对同一键,则先迁移的值生效。
- 运行器会暂存翻译更改而不会写入数据库。Discourse 会在与设置和迁移记录相同的事务中保存这些更改;失败的更新会回滚所有内容。
- 迁移日志会保留已删除设置的值。还原主题代码不会将翻译覆盖层移回设置中。
执行与错误处理
迁移在主题安装和更新期间自动运行。它们只执行一次;如果迁移在成功执行后被修改,将不会再次运行。如果迁移失败,更新过程将停止,并提供出错原因的错误消息。
如果迁移中存在导致设置状态损坏的 bug,则正确的修复方法是创建一个新迁移来纠正损坏的状态,而不是修改原始迁移。
本文档受版本控制 - 请在 github 上提出修改建议。