ARTICLE · 1359041
Cordis 插件生命周期与状态机
目录
为什么插件需要状态机 六种运行状态 状态转换全景 3.1 正常循环:PENDING 与 ACTIVE 之间的往返 3.2 惰性状态:LOADING 与 UNLOADING 3.3 失败与移除:FAILED 与 DISPOSED fiber API 与生命周期交互 4.1 fiber.effect():登记副作用 4.2 fiber.update() 与配置更新 4.3 fiber.dispose() 与 fiber.then() 小结参考文献
插件的加载不是一次性的:依赖可能迟到、服务可能被热重载、配置可能随时更新。Cordis 用一个清晰的状态机管理这些情况,本文拆解每个状态的语义、转换规则,以及通过 fiber API 与生命周期交互的方式。框架整体介绍见 [[Cordis:一个 TypeScript 插件框架]]。
1. 为什么插件需要状态机
回想 [[Cordis 入门:构建你的第一个插件]] 中的服务依赖机制:声明了 inject 的插件会等待所需服务就绪,服务失效时自动回滚,恢复后再重新加载。这意味着一个插件在运行期间可能多次经历「加载—停用—再加载」的循环。如果用简单的布尔量(已加载/未加载)描述,就无法区分「正在停用」「停用失败」「已被移除」这些对调度至关重要的中间态。状态机把这些中间态显式建模,是 Cordis 插件可组合、可热重载的基础。
2. 六种运行状态
插件运行状态共有六个可能值:
可以通过 ctx.fiber.state 读取当前插件的状态。
3. 状态转换全景
各状态之间的转换关系如下图所示:

3.1 正常循环:PENDING 与 ACTIVE 之间的往返
对于正常运行的插件,状态会在 PENDING 和 ACTIVE 之间往返:
PENDING是所有插件的初始状态,表示插件尚无法访问所需的全部依赖ACTIVE表示插件已经顺利启用完成作用域会持续监听所有依赖的变动。一旦全部依赖可用(或插件没有依赖),插件经由 LOADING进入ACTIVE;对已经ACTIVE的插件,如果某些依赖变得不可用,插件会经由UNLOADING再次回到PENDING除了依赖变动,配置更新也可能导致状态在 PENDING和ACTIVE之间往返
3.2 惰性状态:LOADING 与 UNLOADING
LOADING 和 UNLOADING 是两个具有**惰性(Inert State)**的状态:
如果插件正处于 LOADING,此时某些依赖变得不可用,插件会在启用到下一个检查点后再进入UNLOADING;如果在此期间依赖再次可用(且与之前相同),插件将在启用完成后正常进入ACTIVE反之,如果插件正处于 UNLOADING,此时所有依赖变得可用,插件也会等整个停用过程完成后再进入LOADING;如果在此期间依赖再次不可用,插件将在停用完成后正常进入PENDING
换言之,当插件正处于某个方向上的惰性状态时,反方向的状态转移要等到插件即将进入下一个非惰性状态时才被执行或丢弃。这个设计避免了「启停交错」导致的副作用交错回收。
3.3 失败与移除:FAILED 与 DISPOSED
当 LOADING或UNLOADING执行过程中发生错误,插件会回收所有残存的副作用,随后进入FAILED状态。插件无法从FAILED恢复到正常流程中当插件被移除时,先进行副作用回收,随后进入 DISPOSED状态
4. fiber API 与生命周期交互
Fiber 是插件的作用域对象,承载了与生命周期相关的 API。通过 ctx.fiber 获取当前作用域,通过 ctx.plugin() 创建新作用域。
4.1 fiber.effect():登记副作用
fiber.effect(callback, label?) 立即执行 callback 并收集其产生的副作用,返回用于回收副作用的函数:
1 2 3 4 5 6
const dispose = fiber.effect(function* () {yield () => console.log('副作用 1')yieldasync () => console.log('副作用 2')})awaitdispose() // 依次输出:副作用 2, 副作用 1
回调的返回值既可以是清理函数(或其 Promise),也可以是生成器——生成器中每个 yield 交出一个清理函数。存在多个清理函数时,回收按倒序且异步执行,这正是状态机「回收所有残存副作用」的底层机制。此外,如果回调是异步的,可以 await fiber.effect(callback) 等它执行完毕;对异步生成器调用回收函数时,迭代器会先执行到下一个 yield 处,再回收到此为止的副作用。
4.2 fiber.update() 与配置更新
fiber.update(config) 更新插件配置。默认情况下,插件会检测新旧配置是否 deepEqual,发生变化则停用并重新启用作用域;也可以通过 internal/update 事件(返回 true 表示无需重启)手动控制这一行为。实验性的 fiber.restart() 则无条件停用并重新启用作用域。
4.3 fiber.dispose() 与 fiber.then()
fiber.dispose() 停用并移除插件;如果在根作用域上调用,会回收根作用域上的所有副作用(相当于回到 new Context() 的状态),但不会把自身状态置为 DISPOSED。
fiber.then(onFulfilled, onRejected) 让 fiber 天然可被 await:它等待插件进入非惰性状态(LOADING/UNLOADING 以外),如果最终状态是 FAILED 则 Promise 被拒绝。于是最常见的写法是:
1 2
// 等待插件启用完成,失败则抛出错误await ctx.plugin(plugin)
5. 小结
状态机的核心循环是 PENDING ⇄ ACTIVE,驱动因素是依赖可用性与配置更新LOADING/UNLOADING是惰性状态,反向转移必须等当前方向的过渡完成,避免副作用交错FAILED不可恢复,DISPOSED是终点;副作用的登记与回收统一由fiber.effect()承担await fiber是判断插件是否成功启用的惯用法
参考文献
[1] 插件生命周期(Cordis 官方文档·指南):https://github.com/cordiverse/docs/blob/main/zh-CN/guide/advanced/lifecycle.md
[2] 作用域 Fiber(Cordis 官方文档·API):https://github.com/cordiverse/docs/blob/main/zh-CN/api/core/fiber.md
[3] 服务与依赖(Cordis 官方文档·指南):https://github.com/cordiverse/docs/blob/main/zh-CN/guide/essential/service.md















































































