【Cordis学习第五课】配置——给插件戴上“紧箍咒”,干同样的活,却不做同样的事

改行为只能改代码？

代码不变，行为可变

配置机制实战

Config · Schemastery · !!js

PART 01

会问好的插件

config-demo.ts

PART 02

在 YAML 中喂配置

默认值补齐

PART 03

配置错误不启动

FAILED 状态

PART 04

动态配置 !!js

环境变量

PART 05

配置 vs 服务

边界在哪

PART ///

写在最后

五课知识树

01

PART

从一个“会问好”的插件开始

FIRST CONFIG PLUGIN

import type { Context } from '@deepseek-ai/cordis'

import Schema from '@deepseek-ai/schemastery'

export const name = 'config-demo'

// 声明配置项的类型（编译时类型检查）

export interface Config {

　　greeting: string

　　targets: string[]

}

// 声明配置项的运行时校验规则

export const Config: Schema<Config> = Schema.object({

　　greeting: Schema.string().default('Hello'),

　　targets: Schema.array(String).default(['world']),

})

// apply函数多了一个参数：config

export function apply(ctx: Context, config: Config) {

　　for (const target of config.targets) {

　　　　console.log(`${config.greeting}, ${target}!`)

　　}

}

export interface Config：这只是给TypeScript看的，让编辑器有类型提示。

export const Config: Schema<...>：这是运行时校验规则。它告诉Cordis：“我期望的配置长这样，如果不符合，就别加载我。”

基本类型：string()、number()、boolean()

复合类型：object({ ... })、array(...)

默认值：.default('Hello')

验证条件：.required()、.min(0)

02

PART

在 cordis.yml 中提供配置

FEED CONFIG VIA YAML

- name: './config-demo.ts'

　　config:

　　　　targets: ['alpha', 'beta']

node --import tsx ../../vendor/cordis/bin.js

Hello, alpha!

Hello, beta!

Cordis加载插件时，会先读取YAML中的config块。

将config内容传给Schemastery验证器，与插件声明的Config进行比对。

缺少的字段（greeting）被默认值补齐。

完整的、经过验证的配置对象被传给apply(ctx, config)。

插件正常运行。

插件是“菜单”（定义了能点什么菜，比如targets是“要跟谁打招呼”）

cordis.yml是“点菜单”（选好要哪些菜，比如['alpha', 'beta']）

如果某道菜没选（比如greeting没写），餐厅会给一个“默认做法”（default('Hello')）

03

PART

配置错误时，插件不会“硬着头皮上”

VALIDATION FAILS LOUD

- name: './config-demo.ts'

　　config:

　　　　targets: 'not-an-array'

ValidationError: invalid config:

　　- $.targets expected array but got not-an-array (at targets)

04

PART

进阶用法：使用 !!js 动态计算配置值

DYNAMIC CONFIG · !!JS

- name: './config-demo.ts'

　　config:

　　　　greeting: !!js process.env.DEMO_GREETING ?? 'Hello'

　　　　targets: ['alpha', 'beta']

Hi, alpha!

Hi, beta!

05

PART

深入思考：配置与“服务”的区别

CONFIG VS SERVICE

///

LAST

写在最后

CONCLUSION

第一课：插件是什么——导出一个apply函数。

第二课：如何善后——用effect管理资源清理。

第三课：如何协作——用Service提供能力，用inject消费能力。

第四课：如何通知——用Event广播消息。

第五课：如何定制——用Config接收外部参数。