Plugin Dependencies

插件依赖

插件可以声明对其他插件的依赖关系，包括版本约束和扩展点消费。

requires

声明插件依赖：

{
  "requires": ["store", { "id": "epay", "range": ">=1.0.0", "optional": true }]
}

支持两种格式：

字符串格式

"requires": ["store"]

等价于 { "id": "store" }，无版本约束，非可选。

对象格式

属性	类型	说明
id	string	依赖插件 ID
range	string	可选，semver 版本范围
optional	boolean	可选，是否可选依赖（默认 false）

激活时的依赖检查

插件激活时，运行时执行以下检查：

1. 循环检测 — 深度优先遍历 requires，发现循环依赖则拒绝激活
2. 存在性 — 非 optional 依赖必须已注册，否则拒绝激活
3. 版本匹配 — 如果声明了 range，依赖版本必须满足范围
4. 依赖激活 — 依赖插件会递归激活
5. consumes / inject 校验 — 见下文与扩展点；非 optional 的消费项与 inject 服务必须已满足

optional 依赖

optional: true 的依赖如果不存在或版本不匹配，不会阻止激活。插件应在 onActivate 中检查 ctx.getExtensions() 的返回值来处理可选依赖缺失的情况。

provides / consumes

provides 和 consumes 声明插件间的扩展点依赖：

{
  "provides": ["my-plugin.widget"],
  "consumes": [{ "pluginId": "store", "extensionPoint": "payment.provider", "optional": false }]
}

provides

声明本插件向其他插件提供的扩展点 ID。这些 ID 可以被其他插件在 consumes 中引用。

consumes

声明本插件需要从其他插件消费的扩展点：

属性	说明
pluginId	提供方插件 ID
extensionPoint	扩展点 ID
optional	是否可选（默认 false）

激活时，validateConsumes 检查：

• 非 optional 的 consume：提供方必须已激活且在其 provides 中包含该扩展点
• optional 的 consume：即使不满足也不阻止激活

依赖方向示例

store-wallet (requires: store ^0.3.0)
  依赖 store 已激活
store (provides: payment.settlement)
  ↑ 由内核调度（不声明 requires）
epay (provides: payment.provider)
  ↑ 由内核解析（不声明 requires）

网关插件（epay 等）通过 provides: payment.provider 向内核登记支付渠道，回调验签后调 ctx.payments.settle；store 注册 payment.settlement 处理器由内核同步调度。二者都不再 声明对对方的 requires——支付/钱包为内核服务（见 ADR-0006）。

当前声明 requires: ['store'] 的业务插件包括：store-wallet、store-product-server、 store-product-card、catalog、zjmf-upstream、zjmf-compat（多数用 { id: 'store', range: '^0.3.0' } 协调激活顺序）。

停用时的依赖保护

如果插件 A 声明了 requires: ["B"] 且 A 已激活，则 B 无法被停用。运行时会返回：

插件 B 被已启用的插件依赖：A

必须先停用 A，才能停用 B。