跳到主要内容
版本：0.5.x(Latest)

基本介绍​

生命周期声明覆盖插件在安装、升级、禁用、卸载等治理操作中的回调注册。源码插件通过pluginhost.Declarations.Lifecycle()注册Go回调函数，动态插件通过LifecycleContract声明生命周期回调契约。

能力阶段：声明期

类型支持：源码插件、动态插件

能力设计​

生命周期钩子分类​

生命周期钩子分为前置钩子（Before）和后置钩子（After）两类。前置钩子可以否决操作，后置钩子用于观测和清理。

生命周期钩子列表​

钩子类型可否决说明
BeforeInstall前置是安装前校验，返回ok=false可阻止安装
AfterInstall后置否安装后初始化，用于创建默认数据或配置
BeforeUpgrade前置是升级前校验，返回ok=false可阻止升级
Upgrade自定义否执行自定义升级逻辑
AfterUpgrade后置否升级后清理或观测
BeforeDisable前置是禁用前校验，返回ok=false可阻止禁用
AfterDisable后置否禁用后清理
BeforeUninstall前置是卸载前校验，返回ok=false可阻止卸载
Uninstall自定义否执行卸载清理逻辑，例如清除插件数据
AfterUninstall后置否卸载后观测
BeforeTenantDisable前置是租户禁用前校验
AfterTenantDisable后置否租户禁用后清理
BeforeTenantDelete前置是租户删除前校验
AfterTenantDelete后置否租户删除后清理
BeforeInstallModeChange前置是安装模式变更前校验
AfterInstallModeChange后置否安装模式变更后清理

回调超时​

参数默认值说明
单个回调超时5秒单个生命周期回调的最大执行时间
聚合超时10秒同一钩子所有插件回调的总执行时间

输入参数​

输入接口适用钩子关键字段
SourcePluginLifecycleInput安装、禁用、卸载PluginID()、Operation()、StartupAutoEnable()、PurgeStorageData()
SourcePluginUpgradeInput升级PluginID()、FromVersion()、ToVersion()、FromManifest()、ToManifest()
SourcePluginTenantLifecycleInput租户禁用、租户删除Operation()、TenantID()
SourcePluginInstallModeChangeInput安装模式变更PluginID()、Operation()、FromMode()、ToMode()
SourcePluginUninstallInput卸载清理PluginID()、PurgeStorageData()、Services()

接口定义​

源码插件接口​

源码插件通过Lifecycle()注册生命周期回调：

方法回调类型说明
RegisterBeforeInstallHandlerSourcePluginBeforeLifecycleHandler安装前校验
RegisterAfterInstallHandlerSourcePluginAfterLifecycleHandler安装后初始化
RegisterBeforeUpgradeHandlerSourcePluginBeforeUpgradeHandler升级前校验
RegisterUpgradeHandlerSourcePluginUpgradeHandler自定义升级逻辑
RegisterAfterUpgradeHandlerSourcePluginUpgradeHandler升级后清理
RegisterBeforeDisableHandlerSourcePluginBeforeLifecycleHandler禁用前校验
RegisterAfterDisableHandlerSourcePluginAfterLifecycleHandler禁用后清理
RegisterBeforeUninstallHandlerSourcePluginBeforeLifecycleHandler卸载前校验
RegisterAfterUninstallHandlerSourcePluginAfterLifecycleHandler卸载后清理
RegisterBeforeTenantDisableHandlerSourcePluginBeforeTenantLifecycleHandler租户禁用前校验
RegisterAfterTenantDisableHandlerSourcePluginAfterTenantLifecycleHandler租户禁用后清理
RegisterBeforeTenantDeleteHandlerSourcePluginBeforeTenantLifecycleHandler租户删除前校验
RegisterAfterTenantDeleteHandlerSourcePluginAfterTenantLifecycleHandler租户删除后清理
RegisterBeforeInstallModeChangeHandlerSourcePluginBeforeInstallModeChangeHandler安装模式变更前校验
RegisterAfterInstallModeChangeHandlerSourcePluginAfterInstallModeChangeHandler安装模式变更后清理
RegisterUninstallHandlerSourcePluginUninstallHandler卸载清理逻辑

动态插件接口​

动态插件通过LifecycleContract声明生命周期回调契约。每个契约定义一个操作和对应的WASM入口：

字段类型说明
operationstring生命周期操作名称
requestTypestring请求DTO名称
internalPathstring内部路由路径
timeoutMsint回调超时（毫秒）

支持的operation值：BeforeInstall、AfterInstall、BeforeUpgrade、Upgrade、AfterUpgrade、BeforeDisable、AfterDisable、BeforeUninstall、Uninstall、AfterUninstall、BeforeTenantDisable、AfterTenantDisable、BeforeTenantDelete、AfterTenantDelete、BeforeInstallModeChange、AfterInstallModeChange。

能力使用​

源码插件使用​

源码插件在init()中通过Lifecycle()分组入口注册生命周期回调：

func init() {
    plugin := pluginhost.NewDeclarations("my-author-my-domain-my-cap")

    if err := plugin.Lifecycle().RegisterBeforeInstallHandler(beforeInstall); err != nil {
        panic(err)
    }
    if err := plugin.Lifecycle().RegisterAfterInstallHandler(afterInstall); err != nil {
        panic(err)
    }

    if err := pluginhost.RegisterSourcePlugin(plugin); err != nil {
        panic(err)
    }
}

前置钩子返回ok=false和reason可以否决操作：

func beforeInstall(ctx context.Context, input pluginhost.SourcePluginLifecycleInput) (ok bool, reason string, err error) {
    // 校验依赖是否满足
    if !checkDependencies() {
        return false, "缺少必要依赖", nil
    }
    return true, "", nil
}

后置钩子用于初始化或清理：

func afterInstall(ctx context.Context, input pluginhost.SourcePluginLifecycleInput) error {
    // 创建默认配置
    return createDefaultConfig(ctx)
}

动态插件使用​

动态插件在WASM产物中嵌入LifecycleContract。构建工具自动从backend/目录中的控制器提取生命周期契约：

// backend/lifecycle.go
//go:build wasm

package backend

// 控制器方法对应生命周期操作
func (c *LifecycleController) BeforeInstall(ctx context.Context, req *BeforeInstallReq) (*LifecycleDecision, error) {
    // 安装前校验
    return &LifecycleDecision{OK: true}, nil
}

func (c *LifecycleController) AfterInstall(ctx context.Context, req *AfterInstallReq) (*LifecycleDecision, error) {
    // 安装后初始化
    return &LifecycleDecision{OK: true}, nil
}

构建工具会自动生成LifecycleContract并嵌入.wasm产物的lina.plugin.backend.lifecycle自定义段。

设计约束​

  • 前置钩子可以否决操作。 返回ok=false时，宿主会阻止后续操作执行。
  • 后置钩子不能否决操作。 后置钩子在操作完成后执行，失败只记录日志，不回滚操作。
  • 卸载清理是独立钩子。 Uninstall钩子用于执行数据清理，与BeforeUninstall和AfterUninstall分离。
  • 超时机制保护宿主。 单个回调超时5秒，聚合超时10秒，超时后回调被终止。
  • 动态插件生命周期走桥接契约。 动态插件的生命周期回调通过WASM桥接执行，不通过hostServices暴露。
  • PurgeStorageData控制数据清理。 卸载时宿主通过此标志通知插件是否需要清除持久化数据。

相关文档​