schema-dsl 1.2.4 → 2.0.0

package/docs/plugin-system.md

@@ -1,494 +1,316 @@
 # 插件系统
 
-
-> **更新**: 2025-12-26  
+> **更新**: 2026-05-01  
 > **状态**: ✅ 稳定
 
 ---
 
-## 📑 目录
-
-- [概述](#概述)
-- [快速开始](#快速开始)
-- [插件开发](#插件开发)
-- [钩子系统](#钩子系统)
-- [官方插件](#官方插件)
-- [最佳实践](#最佳实践)
-- [API 参考](#api-参考)
-
----
-
 ## 概述
 
-SchemaI-DSL 插件系统允许你扩展核心功能，添加自定义验证器、格式化器、导出器等。
-
-### 特性
+`PluginManager` 是一个独立的插件管理器，负责：
 
-✅ **动态加载** - 运行时注册/卸载插件  
-✅ **生命周期钩子** - 在关键时刻执行自定义逻辑  
-✅ **事件驱动** - 基于 EventEmitter 的事件系统  
-✅ **依赖管理** - 插件间通信和依赖注入  
-✅ **TypeScript 支持** - 完整的类型定义
+- 注册 / 安装 / 卸载插件
+- 管理插件钩子
+- 提供 `EventEmitter` 兼容事件系统
+- 通过 `context` 暴露插件注册表和钩子表
 
-### 架构
-
-```
-PluginManager
-├── 插件注册表 (Map)
-├── 钩子系统 (Hooks)
-├── 事件系统 (EventEmitter)
-└── 上下文 (Context)
-```
+> **重要说明**  
+> `PluginManager` 本身不会自动接入 `dsl()`、`Validator`、各类 Exporter 的执行流程。  
+> 如果你希望在验证、编译或导出阶段运行某些 hook，需要由你的集成代码显式调用 `pluginManager.runHook(...)`。
 
 ---
 
 ## 快速开始
 
-### 1. 创建插件管理器
-
 ```javascript
 const { PluginManager } = require('schema-dsl');
+const schemaDsl = require('schema-dsl');
 
 const pluginManager = new PluginManager();
-```
-
-### 2. 注册插件
 
-```javascript
 const myPlugin = {
   name: 'my-plugin',
   version: '1.0.0',
   description: '我的自定义插件',
 
-  install(schemaDsl, options, context) {
-    console.log('插件安装成功！');
+  install(core, options, context) {
+    console.log('installed:', !!core, options);
+    console.log('registered plugins:', context.plugins.size);
+  },
+
+  uninstall(core, context) {
+    console.log('cleanup:', !!core, context.hooks.size);
   }
 };
 
 pluginManager.register(myPlugin);
+pluginManager.install(schemaDsl, 'my-plugin', { enabled: true });
+pluginManager.uninstall('my-plugin', schemaDsl);
 ```
 
-### 3. 安装插件
-
-```javascript
-const schemaDsl = require('schema-dsl');
-
-pluginManager.install(schemaDsl, 'my-plugin');
-```
-
-### 4. 使用插件
-
-插件安装后，自动生效，无需额外配置。
-
 ---
 
-## 插件开发
-
-### 插件结构
-
-一个标准的插件对象包含以下字段：
+## 插件对象结构
 
 ```javascript
 module.exports = {
-  // ========== 必填 ==========
-  name: 'plugin-name',          // 插件名称（唯一）
-  install: function(schemaDsl, options, context) {
+  // 必填
+  name: 'plugin-name',
+  install(core, options, context) {
     // 安装逻辑
   },
 
-  // ========== 可选 ==========
-  version: '1.0.0',            // 插件版本
-  description: '插件描述',      // 插件描述
-  uninstall: function(schemaDsl, context) {
+  // 可选
+  version: '1.0.0',
+  description: '插件描述',
+  uninstall(core, context) {
     // 卸载逻辑
   },
-  hooks: {                      // 生命周期钩子
-    onBeforeValidate: function() {},
-    onAfterValidate: function() {}
+  hooks: {
+    onBeforeValidate(schema, data) {},
+    onAfterValidate(result) {}
   },
-  options: {                    // 默认选项
+  options: {
     enabled: true
   }
 };
 ```
 
-### 示例：自定义验证器插件
+### 参数说明
 
-```javascript
-module.exports = {
-  name: 'custom-validator',
-  version: '1.0.0',
+| 参数 | 说明 |
+|---|---|
+| `core` | 传给 `install()` / `uninstall()` 的核心对象，通常是 `require('schema-dsl')` 的结果或你自己的集成对象 |
+| `options` | 安装时的合并配置：`{ ...plugin.options, ...installOptions }` |
+| `context.plugins` | 当前已注册插件的 `Map<string, Plugin>` |
+| `context.hooks` | 当前 hook 注册表的 `Map<string, Function[]>` |
 
-  install(schemaDsl, options, context) {
-    const { Validator } = schemaDsl;
-    
-    // 添加自定义关键字
-    Validator.prototype.addKeyword('unique', {
-      async: true,
-      validate: async function(schema, data) {
-        // 验证逻辑
-        const exists = await checkDatabase(data);
-        return !exists;
-      }
-    });
-  }
-};
-```
+---
 
-### 示例：自定义格式插件
+## 钩子系统
 
-```javascript
-module.exports = {
-  name: 'custom-format',
-  version: '1.0.0',
+### 1. 自动触发的内置生命周期
 
-  install(schemaDsl, options, context) {
-    const validator = schemaDsl.getDefaultValidator();
-    const ajv = validator.getAjv();
-    
-    // 添加自定义格式
-    ajv.addFormat('phone-cn', {
-      validate: /^1[3-9]\d{9}$/
-    });
-  }
-};
-```
+这些 hook 由 `PluginManager` 自动触发：
 
----
+| 名称 | 触发时机 | 参数 |
+|---|---|---|
+| `onBeforeRegister` | `register(plugin)` 写入注册表前 | `(plugin)` |
+| `onAfterRegister` | `register(plugin)` 完成后 | `(plugin)` |
+| `onError` | 某个 hook 执行抛错后 | `(error, meta)` |
 
-## 钩子系统
+### 2. 约定式 hook 名称
+
+以下名称是常用约定，`PluginManager` 支持注册它们，但**是否执行取决于你的代码是否调用 `runHook()`**：
 
-### 可用钩子
+| 名称 | 常见用途 |
+|---|---|
+| `onBeforeValidate` / `onAfterValidate` | 验证前后 |
+| `onBeforeCompile` / `onAfterCompile` | 编译前后 |
+| `onBeforeExport` / `onAfterExport` | 导出前后 |
+| `beforeParse` / `afterParse` | 解析阶段 |
+| `beforeValidate` / `afterValidate` | v2 风格命名 |
+| `beforeCompile` / `afterCompile` | v2 风格命名 |
 
-| 钩子名称 | 触发时机 | 参数 |
-|---------|---------|------|
-| `onBeforeRegister` | 插件注册前 | `(plugin)` |
-| `onAfterRegister` | 插件注册后 | `(plugin)` |
-| `onBeforeValidate` | 验证前 | `(schema, data)` |
-| `onAfterValidate` | 验证后 | `(result)` |
-| `onBeforeExport` | 导出前 | `(schema, options)` |
-| `onAfterExport` | 导出后 | `(result)` |
-| `onError` | 错误发生时 | `(error, context)` |
+> `hook()` / `runHook()` 支持任意字符串名称，不限于上表。
 
-### 注册钩子
+### 3. 注册与运行 hook
 
 ```javascript
 pluginManager.hook('onBeforeValidate', (schema, data) => {
   console.log('验证前:', schema, data);
 });
-```
-
-### 运行钩子
 
-```javascript
 const results = await pluginManager.runHook('onBeforeValidate', schema, data);
 ```
 
-### 插件中定义钩子
+### 4. 在插件中声明 hook
 
 ```javascript
-module.exports = {
-  name: 'my-plugin',
-  
+const loggingPlugin = {
+  name: 'logging',
+  install() {},
   hooks: {
     onBeforeValidate(schema, data) {
-      // 在这里修改 schema 或 data
+      console.log('before validate', schema, data);
     },
-    
     onAfterValidate(result) {
-      // 在这里修改验证结果
+      console.log('after validate', result);
     }
   }
 };
-```
-
----
 
-## 官方插件
-
-### 1. custom-validator
-
-添加业务特定的验证规则。
-
-```javascript
-const customValidator = require('schema-dsl/plugins/custom-validator');
-
-pluginManager.register(customValidator);
-pluginManager.install(schema-dsl);
+pluginManager.register(loggingPlugin);
+await pluginManager.runHook('onBeforeValidate', schema, data);
 ```
 
-**功能**:
-- `unique` - 唯一性验证（异步）
-- `passwordStrength` - 密码强度验证
-- `idCard` - 身份证号验证
-
-### 2. custom-format
-
-添加常用的格式验证。
-
-```javascript
-const customFormat = require('schema-dsl/plugins/custom-format');
-
-pluginManager.register(customFormat);
-pluginManager.install(schema-dsl);
-```
-
-**格式**:
-- `phone-cn` - 中国手机号
-- `postal-code-cn` - 邮政编码
-- `wechat` - 微信号
-- `qq` - QQ号
-- `bank-card` - 银行卡号
-- `license-plate` - 车牌号
-
 ---
 
-## 最佳实践
-
-### 1. 插件命名
-
-使用 `kebab-case` 命名：
-
-```javascript
-// ✅ 推荐
-name: 'custom-validator'
-name: 'mongodb-plugin'
-
-// ❌ 不推荐
-name: 'CustomValidator'
-name: 'mongodb_plugin'
-```
-
-### 2. 版本管理
-
-使用语义化版本：
-
-```javascript
-version: '1.0.0'   // 主版本.次版本.修订版本
-```
+## 事件系统
 
-### 3. 错误处理
+`PluginManager` 继承自 `EventEmitter`，因此可以使用：
 
-插件应该优雅地处理错误：
+- `on()`
+- `once()`
+- `off()`
+- `emit()`
+- `removeListener()`
+- `removeAllListeners()`
 
-```javascript
-install(schema-dsl, options, context) {
-  try {
-    // 安装逻辑
-  } catch (error) {
-    console.error(`[${this.name}] 安装失败:`, error.message);
-    throw error; // 重新抛出，让调用者知道
-  }
-}
-```
+### 可用事件
 
-### 4. 清理资源
+| 事件名 | 触发时机 | 参数 |
+|---|---|---|
+| `plugin:registered` | 插件注册成功 | `(plugin)` |
+| `plugin:installed` | 插件安装成功 | `(plugin)` |
+| `plugin:uninstalled` | 插件卸载成功 | `(plugin)` |
+| `plugin:error` | 插件安装 / 卸载失败 | `({ plugin, error })` |
+| `hook:error` | hook 执行失败 | `({ hookName, handler, error })` |
+| `plugins:cleared` | `clear()` 完成后 | `()` |
 
-提供 `uninstall` 方法：
+### 示例
 
 ```javascript
-uninstall(schema-dsl, context) {
-  // 清理注册的验证器、格式、钩子等
-  delete schemaDsl.myCustomMethod;
-}
-```
+pluginManager.on('plugin:registered', (plugin) => {
+  console.log('插件已注册:', plugin.name);
+});
 
-### 5. 文档
+pluginManager.on('plugin:installed', (plugin) => {
+  console.log('插件已安装:', plugin.name);
+});
 
-为你的插件编写清晰的文档：
+pluginManager.on('plugin:error', ({ plugin, error }) => {
+  console.error('插件错误:', plugin.name, error.message);
+});
 
-```javascript
-/**
- * 我的自定义插件
- * 
- * @description 添加业务特定的验证规则
- * 
- * @example
- * ```javascript
- * pluginManager.register(myPlugin);
- * pluginManager.install(schema-dsl);
- * ```
- */
-module.exports = { /* ... */ };
+pluginManager.on('hook:error', ({ hookName, error }) => {
+  console.error('Hook 错误:', hookName, error.message);
+});
 ```
 
 ---
 
 ## API 参考
 
-### PluginManager
-
-#### `register(plugin)`
+### `register(plugin)`
 
-注册插件。
+注册插件，并自动触发：
 
-**参数**:
-- `plugin` (Object) - 插件配置
+1. `onBeforeRegister`
+2. 写入注册表 / 注册插件自带 hooks
+3. `onAfterRegister`
+4. `plugin:registered`
 
-**返回**: `this`
-
-**示例**:
-```javascript
-pluginManager.register({
-  name: 'my-plugin',
-  install(schema-dsl) {
-    // ...
-  }
-});
-```
-
-#### `install(schema-dsl, [pluginName], [options])`
+### `install(core, [pluginName], [options])`
 
 安装插件。
 
-**参数**:
-- `schema-dsl` (Object) - SchemaI-DSL 实例
-- `pluginName` (String, optional) - 插件名称
-- `options` (Object, optional) - 安装选项
-
-**返回**: `this`
+- `install(core)`：安装所有已注册插件
+- `install(core, 'name', options)`：安装指定插件
+- `install()` 时会把第三个参数 `context` 传给插件
+- 安装成功后触发 `plugin:installed`
+- 安装失败时触发 `plugin:error`，然后抛错
 
-#### `uninstall(pluginName, schema-dsl)`
+### `unregister(name, [core])`
 
-卸载插件。
+卸载插件并移除该插件注册的 hooks。
 
-**参数**:
-- `pluginName` (String) - 插件名称
-- `schema-dsl` (Object) - SchemaI-DSL 实例
+- `plugin.uninstall(core, context)` 成功后才会真正移除插件
+- 卸载成功后触发 `plugin:uninstalled`
+- 卸载失败时触发 `plugin:error`，然后抛错
 
-**返回**: `this`
+### `uninstall(name, [core])`
 
-#### `hook(hookName, handler)`
+`unregister()` 的别名，兼容 v1。
 
-注册钩子。
+### `hook(name, handler)`
 
-**参数**:
-- `hookName` (String) - 钩子名称
-- `handler` (Function) - 钩子处理函数
+注册一个 hook 处理器。
 
-**返回**: `this`
+### `unhook(name, handler)`
 
-#### `runHook(hookName, ...args)`
+移除指定 hook 处理器。
 
-运行钩子。
+### `runHook(name, ...args)`
 
-**参数**:
-- `hookName` (String) - 钩子名称
-- `...args` (any) - 钩子参数
+异步运行某个 hook 下的全部处理器，返回结果数组。
 
-**返回**: `Promise<any[]>`
+- 单个 handler 抛错不会中断后续 handler
+- 抛错时会触发 `hook:error`
+- 同时会执行 `onError`
 
-#### `list()`
+### `has(name)`
 
-获取插件列表。
+检查插件是否已注册。
 
-**返回**: `Array<{name, version, description}>`
+### `get([name])`
 
-#### `has(pluginName)`
+- `get(name)`：获取单个插件
+- `get()`：获取全部插件 `Map`
 
-检查插件是否存在。
+### `list()`
 
-**参数**:
-- `pluginName` (String) - 插件名称
+返回插件元数据数组：
 
-**返回**: `Boolean`
+```javascript
+[{ name, version, description }]
+```
 
-#### `clear(schema-dsl)`
+### `clear([core])`
 
-清空所有插件。
+逐个卸载所有插件，清空注册表和 hooks，最后触发 `plugins:cleared`。
 
-**参数**:
-- `schema-dsl` (Object) - SchemaI-DSL 实例
+### 属性
 
-**返回**: `this`
+| 属性 | 说明 |
+|---|---|
+| `pluginManager.plugins` | 插件注册表 `Map<string, Plugin>` |
+| `pluginManager.hooks` | hook 注册表 `Map<string, Function[]>` |
+| `pluginManager.context` | `{ plugins, hooks }` |
+| `pluginManager.size` | 已注册插件数量 |
+| `pluginManager.pluginCount` | 已注册插件数量（别名） |
 
 ---
 
-## 事件系统
+## 最佳实践
 
-PluginManager 继承自 EventEmitter，支持事件监听：
+### 1. 命名
 
-```javascript
-pluginManager.on('plugin:registered', (plugin) => {
-  console.log('插件已注册:', plugin.name);
-});
-
-pluginManager.on('plugin:installed', (plugin) => {
-  console.log('插件已安装:', plugin.name);
-});
+使用 `kebab-case`：
 
-pluginManager.on('plugin:error', ({ plugin, error }) => {
-  console.error('插件错误:', plugin.name, error.message);
-});
+```javascript
+name: 'custom-validator'
+name: 'mongodb-plugin'
 ```
 
-**可用事件**:
-- `plugin:registered` - 插件注册成功
-- `plugin:installed` - 插件安装成功
-- `plugin:uninstalled` - 插件卸载成功
-- `plugin:error` - 插件错误
-- `hook:error` - 钩子执行错误
-- `plugins:cleared` - 所有插件已清空
-
----
-
-## 进阶话题
-
-### 1. 插件间通信
-
-通过 `context` 参数访问其他插件：
+### 2. 错误处理
 
 ```javascript
-install(schema-dsl, options, context) {
-  // 检查依赖插件
-  if (!context.plugins.has('dependency-plugin')) {
-    throw new Error('需要先安装 dependency-plugin');
+install(core, options, context) {
+  try {
+    // 安装逻辑
+  } catch (error) {
+    throw error;
   }
-  
-  // 获取其他插件实例
-  const depPlugin = context.plugins.get('dependency-plugin');
 }
 ```
 
-### 2. 插件配置
-
-通过 `options` 参数传递配置：
+### 3. 资源清理
 
 ```javascript
-// 注册时设置默认配置
-module.exports = {
-  name: 'my-plugin',
-  options: {
-    strict: false,
-    maxRetries: 3
-  },
-  
-  install(schema-dsl, options) {
-    const config = { ...this.options, ...options };
-    console.log('配置:', config);
-  }
-};
-
-// 安装时覆盖配置
-pluginManager.install(schema-dsl, 'my-plugin', {
-  strict: true
-});
+uninstall(core, context) {
+  // 清理注册的资源
+}
 ```
 
-### 3. 异步安装
-
-插件安装函数可以是异步的：
+### 4. 插件间通信
 
 ```javascript
-module.exports = {
-  name: 'async-plugin',
-  
-  async install(schema-dsl, options) {
-    // 异步初始化
-    await this.loadConfig();
-    await this.connectDatabase();
+install(core, options, context) {
+  if (!context.plugins.has('dependency-plugin')) {
+    throw new Error('需要先安装 dependency-plugin');
   }
-};
+}
 ```
 
 ---
@@ -497,46 +319,63 @@ module.exports = {
 
 ### 插件未生效
 
-1. 检查插件是否已注册：
 ```javascript
-console.log(pluginManager.has('my-plugin')); // true?
+pluginManager.has('my-plugin');
+pluginManager.list();
 ```
 
-2. 检查插件是否已安装：
-```javascript
-pluginManager.list(); // 是否在列表中?
-```
+确认插件已注册、已安装，并且 `install()` 确实执行到了你的逻辑。
 
-3. 检查 `install` 函数是否正确执行。
+### hook 未触发
 
-### 钩子未触发
+检查两件事：
 
-1. 确认钩子名称拼写正确。
-2. 使用 `pluginManager.hooks.get('hookName')` 查看已注册的钩子。
+1. hook 名称是否一致
+2. 你的代码是否真的调用了 `pluginManager.runHook('hookName', ...)`
 
-### 插件冲突
+### 当前仓库的发布方式
 
-如果两个插件修改同一个方法，后安装的会覆盖前一个。解决方案：
-- 使用不同的方法名
-- 在插件中保存原始方法的引用
+当前仓库已恢复 v1 风格的官方插件子路径入口，可直接使用：
 
----
+- `schema-dsl/plugins/custom-format`
+- `schema-dsl/plugins/custom-validator`
+- `schema-dsl/plugins/custom-type-example`
 
-## 完整示例
+```javascript
+const { PluginManager } = require('schema-dsl');
+const schemaDsl = require('schema-dsl');
+const customFormat = require('schema-dsl/plugins/custom-format');
+
+const pluginManager = new PluginManager();
+pluginManager.register(customFormat);
+pluginManager.install(schemaDsl, 'custom-format');
+```
+
+```typescript
+import { PluginManager } from 'schema-dsl';
+import * as schemaDsl from 'schema-dsl';
+import customTypeExample from 'schema-dsl/plugins/custom-type-example';
+
+const pluginManager = new PluginManager();
+pluginManager.register(customTypeExample);
+pluginManager.install(schemaDsl, 'custom-type-example');
+```
 
-见 [examples/plugin-system.examples.js](../examples/plugin-system.examples.js)
+> ⚠️ 注意：官方插件子路径只补齐了 v1 已存在的三个示例插件入口；
+> `PluginManager` 仍然不会自动接入 `validate()` / `compile()` / exporter 流程，hook 是否执行仍取决于你的集成代码是否显式调用 `runHook()`。
 
 ---
 
 ## 相关文档
 
 - [API 参考](api-reference.md)
-- [最佳实践](best-practices.md)
-- [故障排查](troubleshooting.md)
+- [验证指南](validate.md)
+- [DSL 语法](dsl-syntax.md)
 
 ---
 
-**贡献**
+## 对应示例文件
 
-欢迎提交你的插件到官方插件库！请提交 PR 到 `plugins/` 目录。
+**示例入口**: [plugin-system.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/plugin-system.ts)  
+**说明**: 覆盖自定义插件的注册 / 安装 / 卸载、`runHook()` 执行结果，以及官方 `custom-format` 子路径插件的安装效果。