schema-dsl 1.2.5 → 2.0.1

package/docs/plugin-system.md

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