尚拙
Search K

Appearance

Cordis 入门 01：从零跑起第一个插件 ​

学 Cordis 最容易卡住的地方，不是 API 多，而是它的入口不像常见 Web 框架。你不会一上来写 Controller、Route 或 Component，而是先创建一个 Context，再把一个函数安装成插件。

这篇先不讲论文里的“时空可组合性”，也不读源码。目标只有一个：把第一个 Cordis 插件跑起来，并理解 Context、Plugin、Fiber 这三个词。

这篇要练什么 ​

练完本文，你会得到一个最小 cordis-demo 项目：

text
cordis-demo
├─ package.json
└─ index.mjs

你会掌握三件事：

  • 用 new Context() 创建 Cordis 运行时。
  • 用 ctx.plugin() 安装一个插件。
  • 用 Fiber 理解插件安装后的运行实例。

准备项目 ​

创建项目目录并安装 Cordis。

bash
mkdir cordis-demo
cd cordis-demo
npm init -y
npm install cordis@4.0.0-rc.8

本文示例基于 cordis@4.0.0-rc.8 验证。Cordis 当前仍是 rc 版本，跟练时建议先锁定版本，避免未来 API 调整影响学习过程。

当前 npm 上的 cordis 是 ESM 包。为了降低入门成本，本文示例统一使用 .mjs 文件。

创建 index.mjs：

js
import { Context } from 'cordis'

const ctx = new Context()

function helloPlugin(ctx) {
  console.log('hello cordis')
}

await ctx.plugin(helloPlugin)

运行：

bash
node index.mjs

如果输出下面这行，说明第一个插件已经跑起来了。

text
hello cordis

这段代码到底发生了什么 ​

先把代码拆成三层。

Context 是 Cordis 的运行时上下文。插件需要事件、服务、子插件、生命周期能力时，都会从 ctx 进去。

Plugin 在这个例子里就是 helloPlugin 函数。Cordis 支持函数、类和带 apply 方法的对象作为插件。入门阶段先用函数插件最清楚。

Fiber 是插件被安装后的生命周期实例。你可以先把它理解成“这个插件这一次运行的身份”。后面插件卸载、副作用清理、依赖等待，都会围绕 Fiber 展开。

拿到 Fiber ​

ctx.plugin() 会返回一个 Fiber。这个 Fiber 也可以被 await。

把 index.mjs 改成下面这样：

js
import { Context } from 'cordis'

const ctx = new Context()

function helloPlugin(ctx) {
  console.log('hello cordis')
}

const fiber = ctx.plugin(helloPlugin)
await fiber

console.log('plugin is ready')

运行：

bash
node index.mjs

输出：

text
hello cordis
plugin is ready

这个例子里插件很简单，所以 await fiber 几乎立刻结束。后面当插件依赖某个服务时，await fiber 就会变得重要：它表示等待插件真正进入可用状态。

插件可以接收配置 ​

大多数插件都需要配置。Cordis 会把第二个参数传给插件函数。

js
import { Context } from 'cordis'

const ctx = new Context()

function greetPlugin(ctx, config) {
  console.log(`hello ${config.name}`)
}

await ctx.plugin(greetPlugin, {
  name: 'cordis',
})

运行后输出：

text
hello cordis

配置对象现在只是普通对象。更严格的配置校验可以以后再学。入门阶段先把插件函数的两个参数记住：

text
plugin(ctx, config)

一个小练习 ​

把 greetPlugin 改成下面的需求：

  • 配置里传入 name。
  • 配置里传入 times。
  • 插件按次数打印问候语。

参考实现：

js
import { Context } from 'cordis'

const ctx = new Context()

function greetPlugin(ctx, config) {
  for (let i = 0; i < config.times; i++) {
    console.log(`hello ${config.name} #${i + 1}`)
  }
}

await ctx.plugin(greetPlugin, {
  name: 'cordis',
  times: 3,
})

输出：

text
hello cordis #1
hello cordis #2
hello cordis #3

入门检查点 ​

现在你可以把 Cordis 先理解成下面这句话：

text
Cordis = Context + Plugin + Fiber

Context 是运行环境，Plugin 是功能单元，Fiber 是插件运行后的生命周期实例。

这一篇还没有体现 Cordis 最强的地方。真正的插件不只打印日志，它会注册事件、启动定时器、打开连接、提供服务。下一篇我们就处理第一个关键问题：插件产生副作用以后，卸载时怎么清理。

系列导航：