插件升级开发文档
UpgradeUpgrade应该怎么写extensions/<identifier>/1. 先记住插件升级的基本模型
migration -> Upgrade -> data/versions/<version>你的升级代码必须先被构建到 build 目录,主程序启动时才看得见。packages/api/src/core/database/extension-upgrade/extension-upgrade-orchestrator.service.tspackages/api/src/core/database/extension-upgrade/extension-version-manager.service.ts2. 插件 migration 和 Upgrade 怎么分
2.1 什么时候写插件 migration
如果你的插件 schema 结构变了,就写 migration。2.2 什么时候写插件 Upgrade
Upgrade。如果你需读取旧数据、判断旧状态、再写回去,就写 Upgrade。2.3 什么场景两者都要写
status字段,同时要把旧文章统一补成draft:1.
2.
2.4 什么场景通常都不用写
3. 插件 migration 写在哪里
extensions/<identifier>/src/api/db/migrations/extensions/<identifier>/build/db/migrations/{timestamp}-{version}-{description}.js1776000000000-0.0.3-add-article-status.tsextensions_migrations_historyextension_identifier区分不同插件。4. 插件 migration 有哪些生成命令
@chatbuddy-ai/db包里。4.1 手工创建插件 migration 模板
1.
src/api/db/migrations/下创建模板文件2.
3.
4.2 根据插件实体自动生成 migration
1.
2.
3.
4.
src/api/db/migrations/build/db/entities5. 插件 Upgrade 写在哪里
extensions/<identifier>/src/api/upgrade/<version>/index.tsextensions/<identifier>/build/upgrade/<version>/index.jsextensions/simple-blog/src/api/upgrade/0.0.2/index.tsextensions/simple-blog/src/api/upgrade/0.0.2/index.tstemplates/extension-starter/src/api/upgrade/0.0.2/index.ts6. 插件 Upgrade 有没有生成命令
Upgrade:需你自己手工创建目录和index.ts7. 插件 Upgrade 的最小写法
Upgrade类就能。import { DataSource } from "@chatbuddy-ai/db/typeorm";
import { Logger } from "@nestjs/common"; export class Upgrade { private readonly logger = new Logger(Upgrade.name); constructor(private readonly dataSource: DataSource) {} async execute: Promise<void> { this.logger.log("Start plugin upgrade 0.0.3"); await this.dataSource.query(` UPDATE "simple_blog"."article" SET "status" = 'draft' WHERE "status" IS NULL `); this.logger.log("Plugin upgrade 0.0.3 completed"); }
}1.
2.
Upgrade类3.
execute4.
DataSourcenew Upgrade(this.dataSource).execute8. 插件 Upgrade 里常用的方法怎么写
dataSource。8.1 直接执行 SQL
await this.dataSource.query( ` UPDATE "simple_blog"."article" SET "status" = $1 WHERE "status" IS NULL `, ["draft"],
);8.2 用 Repository
const repo = this.dataSource.getRepository("Article");
const rows = await repo.find; for (const row of rows) { row.status = row.status || "draft";
} await repo.save(rows);8.3 用事务
const queryRunner = this.dataSource.createQueryRunner;
await queryRunner.connect;
await queryRunner.startTransaction; try { await queryRunner.query(` UPDATE "simple_blog"."article" SET "status" = 'draft' WHERE "status" IS NULL `); await queryRunner.query(` INSERT INTO "simple_blog"."setting" ("key", "value") VALUES ('default_status', 'draft') `); await queryRunner.commitTransaction;
} catch (error) { await queryRunner.rollbackTransaction; throw error;
} finally { await queryRunner.release;
}9. 插件开发里最常见的判断题
| 场景 | 应该写什么 |
|---|---|
| 插件表新增字段 | migration |
| 插件旧数据补默认值 | Upgrade |
| 新字段 + 旧数据回填 | migration + Upgrade |
| 新版本初始化默认配置 | Upgrade |
| 只改插件页面 | 都不用 |
10. 插件 Upgrade 设计时的硬规则
10.1 尽量幂等
UPDATE ... WHERE xxx IS NULL10.2 不要把表结构修改塞进 Upgrade
Upgrade。10.3 升级代码要和插件版本绑定
extensions/<identifier>/package.json0.0.3的升级代码,但插件版本还停留在0.0.2,升级器不会按你预期打开这个版本。11. 写完以后怎么让插件升级器识别
1.
extensions/extensions.json2.
3.
build/是否存在4.
Upgrade1.
2.
3.
12. 插件开发者最容易踩的坑
12.1 只写了src/api/upgrade,没重新构建
build/upgrade/<version>/index.js12.2 写了 Upgrade,但没升级插件版本号
package.json.version为当前目标版本。12.3 用migration:generate:extension前没先构建 API
build/db/entities12.4 把旧数据修复写在 service 正常运行逻辑里
Upgrade。13. 推荐开发流程
1.
2.
3.
src/api/upgrade/<version>/index.ts4.
package.json.version5.
6.
7.
extensions/<identifier>/data/versions/<version>已写入14. 你能够直接照抄的结论
UpgradeUpgradeUpgrade没有命令生成,需手工创建共 319 篇文档 · 内容同步自官方帮助中心