@ice/mf-runtime 1.0.2 → 1.0.3-beta.2

package/README.md

@@ -1,12 +1,18 @@
 # @ice/mf-runtime
 
-基于 Module Federation 的运行时工具，用于在 ice.js 应用中加载和管理远程模块。支持跨版本 React 组件加载
+基于 Module Federation 的运行时工具，用于在 ice.js 应用中加载和管理远程模块。支持跨版本 React 组件加载，并提供增强的插件机制。
 
 ## 特性
 
 - 基于 [Module Federation 2.0](https://module-federation.io/index.html)
 - 支持跨版本 React 组件加载
 - 内置冲突检测和降级渲染
+- 🔌 **增强插件机制**: 完全兼容标准 MF 运行时插件
+- 🎯 **组件增强**: 支持 HOC、Props 注入等组件扩展机制  
+- 🛡️ **错误边界**: 内置错误处理和恢复机制
+- 📊 **性能监控**: 支持组件加载和渲染性能追踪
+- 🔄 **热插拔**: 运行时动态注册和移除插件
+- 📝 **TypeScript**: 完整的类型定义支持
 
 ## 安装
 
@@ -14,6 +20,220 @@
 $ npm i @ice/mf-runtime --save
 ```
 
+## 插件机制
+
+从 v1.0.1 开始，`@ice/mf-runtime` 支持强大的插件机制，允许在运行时动态扩展微前端功能。
+
+### 插件类型
+
+#### 1. 标准 MF 插件 (FederationRuntimePlugin)
+标准 MF 插件使用原生的 `@module-federation/runtime` API 进行管理：
+
+```typescript
+import { registerPlugins } from '@module-federation/runtime';
+import type { FederationRuntimePlugin } from '@ice/mf-runtime';
+
+const mfPlugin: FederationRuntimePlugin = {
+  name: 'my-mf-plugin',
+  beforeRequest: (args) => {
+    console.log('模块请求前:', args);
+    return args;
+  },
+  onLoad: (args) => {
+    console.log('模块加载后:', args);
+    return args;
+  },
+  afterResolve: (args) => {
+    console.log('模块解析后:', args);
+    return args;
+  }
+};
+
+// 使用原生 API 注册标准 MF 插件
+registerPlugins([mfPlugin]);
+```
+
+#### 2. 增强插件 (EnhancedRuntimePlugin)
+增强插件使用新的 API 进行管理，提供组件级别的扩展能力：
+
+```typescript
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+import type { EnhancedRuntimePlugin } from '@ice/mf-runtime';
+
+const enhancedPlugin: EnhancedRuntimePlugin = {
+  name: 'my-enhanced-plugin',
+  
+  // 组件包装器 - 支持 HOC 模式
+  wrapComponent: (WrappedComponent, context) => {
+    return function Enhanced(props) {
+      console.log(`渲染组件: ${context.remoteName}/${context.moduleName}`);
+      return <WrappedComponent {...props} />;
+    };
+  },
+  
+  // 属性注入器
+  injectProps: (props, context) => {
+    return {
+      ...props,
+      injectedProp: `来自 ${context.remoteName} 的数据`
+    };
+  }
+};
+
+// 使用新的 API 注册增强插件
+registerEnhancedPlugins([enhancedPlugin]);
+```
+
+### 注册和使用插件
+
+#### 基本用法
+
+```typescript
+import { init, registerEnhancedPlugins, RemoteModule } from '@ice/mf-runtime';
+import { registerPlugins } from '@module-federation/runtime';
+
+// 注册标准 MF 插件
+registerPlugins([mfPlugin]);
+
+// 注册增强插件
+registerEnhancedPlugins([enhancedPlugin]);
+
+// 初始化运行时
+init({
+  remotes: [
+    {
+      name: 'remote-app',
+      entry: 'http://localhost:3001/remoteEntry.js'
+    }
+  ]
+});
+
+// 使用远程模块（插件会自动应用）
+function App() {
+  return (
+    <RemoteModule
+      scope="remote-app"
+      module="Button"
+      componentProps={{ text: '点击我' }}
+    />
+  );
+}
+```
+
+#### 使用示例插件包
+
+我们提供了一个示例插件包 `@ice/mf-plugin-example`，包含常用的插件：
+
+```bash
+npm install @ice/mf-plugin-example
+```
+
+```typescript
+import { registerPlugins } from '@module-federation/runtime';
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+import { 
+  errorBoundaryPlugin, 
+  commonPropsPlugin, 
+  developmentMFLoggingPlugin,
+  developmentEnhancedLoggingPlugin 
+} from '@ice/mf-plugin-example';
+
+// 注册标准 MF 插件
+registerPlugins([
+  developmentMFLoggingPlugin  // MF 日志插件
+]);
+
+// 注册增强插件
+registerEnhancedPlugins([
+  developmentEnhancedLoggingPlugin,  // 增强日志插件
+  errorBoundaryPlugin,               // 错误边界插件  
+  commonPropsPlugin                  // 通用属性注入插件
+]);
+```
+
+### 插件开发指南
+
+#### 错误边界插件示例
+
+```typescript
+import { ErrorBoundary } from 'react-error-boundary';
+
+const errorBoundaryPlugin: EnhancedRuntimePlugin = {
+  name: 'error-boundary',
+  wrapComponent: (WrappedComponent, context) => {
+    return function ErrorBoundaryWrapper(props) {
+      return (
+        <ErrorBoundary
+          fallback={<div>组件 {context.remoteName} 加载失败</div>}
+          onError={(error) => {
+            console.error(`组件错误:`, error);
+          }}
+        >
+          <WrappedComponent {...props} />
+        </ErrorBoundary>
+      );
+    };
+  }
+};
+```
+
+#### 属性注入插件示例
+
+```typescript
+const themePlugin: EnhancedRuntimePlugin = {
+  name: 'theme-injector',
+  injectProps: (props, context) => {
+    return {
+      ...props,
+      theme: {
+        mode: 'light',
+        primaryColor: '#1890ff'
+      }
+    };
+  }
+};
+```
+
+### 插件 API
+
+#### EnhancedPluginManager
+
+```typescript
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+
+const manager = getEnhancedPluginManager();
+
+// 注册增强插件
+manager.register(enhancedPlugin);
+
+// 获取插件信息
+const info = manager.getPluginInfo();
+// 返回: [{ name: 'plugin-name', hasWrapper: true, hasInjector: false }]
+
+// 移除插件
+manager.removePlugin('plugin-name');
+
+// 清空所有插件
+manager.clear();
+```
+
+#### React Hook
+
+```typescript
+import { useEnhancedPluginManager } from '@ice/mf-runtime';
+
+function MyComponent() {
+  const enhancedPluginManager = useEnhancedPluginManager();
+  
+  // 动态操作插件
+  const handleAddPlugin = () => {
+    enhancedPluginManager.register(newEnhancedPlugin);
+  };
+  
+  return <div>...</div>;
+}
+```
+
 ## 使用
 
 ### 1. 初始化配置

package/docs/PLUGIN_SYSTEM_GUIDE.md

@@ -0,0 +1,294 @@
+# 微前端插件系统使用指南
+
+## 概述
+
+`@ice/mf-runtime` 提供了一套增强插件系统，允许开发者对远程组件进行功能扩展，如错误边界、日志记录、性能监控等。
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install @ice/mf-runtime
+```
+
+### 2. 基本使用
+
+```tsx
+import { RemoteModule, registerEnhancedPlugins } from '@ice/mf-runtime';
+import { createEnhancedLoggingPlugin } from '@ice/mf-plugin-example';
+
+// 注册插件
+registerEnhancedPlugins([createEnhancedLoggingPlugin()]);
+
+// 使用远程组件
+function App() {
+  return (
+    <RemoteModule
+      scope="remote-app"
+      module="Button"
+    />
+  );
+}
+```
+
+## 插件开发
+
+### 插件接口
+
+```typescript
+export interface EnhancedRuntimePlugin {
+  name: string;
+  wrapComponent?: ComponentWrapper;
+  injectProps?: PropInjector;
+}
+
+export interface ComponentWrapper {
+  (
+    WrappedComponent: React.ComponentType<any>, 
+    context: WrapperContext
+  ): React.ComponentType<any>;
+}
+
+export interface PropInjector {
+  (
+    props: Record<string, any>, 
+    context: InjectionContext
+  ): Record<string, any>;
+}
+```
+
+### 上下文信息
+
+```typescript
+export interface WrapperContext {
+  remoteName: string;
+  moduleName: string;
+  props: Record<string, any>;
+  React: typeof import('react');        // 正确的 React 实例
+  ReactDOM?: typeof import('react-dom'); // 正确的 ReactDOM 实例
+}
+
+export interface InjectionContext {
+  remoteName: string;
+  moduleName: string;
+}
+```
+
+### 创建插件
+
+```typescript
+import type { EnhancedRuntimePlugin, WrapperContext } from '@ice/mf-runtime';
+
+export function createMyPlugin(options = {}): EnhancedRuntimePlugin {
+  return {
+    name: 'my-plugin',
+    
+    wrapComponent: (WrappedComponent, context: WrapperContext) => {
+      // 🔑 使用上下文提供的 React 实例
+      const { React: ContextReact } = context;
+      
+      const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
+        ContextReact.useEffect(() => {
+          console.log(`Component ${context.remoteName}/${context.moduleName} mounted`);
+        }, []);
+        
+        return ContextReact.createElement(WrappedComponent, { ...props, ref });
+      });
+      
+      MyWrapper.displayName = `MyWrapper(${WrappedComponent.displayName || 'Component'})`;
+      return MyWrapper;
+    },
+    
+    injectProps: (props, context) => {
+      return {
+        ...props,
+        pluginData: 'injected by my plugin'
+      };
+    }
+  };
+}
+```
+
+## 内置插件示例
+
+### 日志记录插件
+
+```typescript
+import { 
+  createEnhancedLoggingPlugin,
+  developmentEnhancedLoggingPlugin,
+  productionEnhancedLoggingPlugin
+} from '@ice/mf-plugin-example';
+
+// 自定义配置
+registerEnhancedPlugins([createEnhancedLoggingPlugin({
+  level: 'info',
+  logComponentRender: true,
+  enablePerformanceMonitoring: true
+})]);
+
+// 或使用预定义插件
+registerEnhancedPlugins([
+  process.env.NODE_ENV === 'development' 
+    ? developmentEnhancedLoggingPlugin 
+    : productionEnhancedLoggingPlugin
+]);
+```
+
+### 属性注入插件
+
+```typescript
+import { createPropsInjectionPlugin } from '@ice/mf-plugin-example';
+
+registerEnhancedPlugins([createPropsInjectionPlugin({
+  globalProps: {
+    theme: 'dark',
+    version: '1.0.0'
+  }
+})]);
+```
+
+## 插件管理
+
+### 注册插件
+
+```typescript
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+
+// 注册多个插件（推荐方式）
+registerEnhancedPlugins([plugin1, plugin2, plugin3]);
+
+// 或通过插件管理器注册
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+const manager = getEnhancedPluginManager();
+manager.register(myPlugin);
+manager.registerPlugins([plugin1, plugin2]);
+```
+
+### 获取插件管理器
+
+```typescript
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+
+const manager = getEnhancedPluginManager();
+
+// 获取所有插件
+const plugins = manager.getPlugins();
+
+// 获取插件信息
+const info = manager.getPluginInfo();
+
+// 移除插件
+manager.removePlugin('plugin-name');
+
+// 清空所有插件
+manager.clear();
+```
+
+### 在组件中使用
+
+```typescript
+import { useEnhancedPluginManager } from '@ice/mf-runtime';
+
+function MyComponent() {
+  const pluginManager = useEnhancedPluginManager();
+  
+  // 动态注册插件
+  React.useEffect(() => {
+    pluginManager.register(createMyPlugin());
+  }, []);
+  
+  return <div>My Component</div>;
+}
+```
+
+## 远程组件配置
+
+### 基本配置
+
+```tsx
+<RemoteModule
+  scope="remote-app"
+  module="Button"
+  componentProps={{ text: 'Click me' }}
+/>
+```
+
+
+## 最佳实践
+
+### 1. React 实例一致性
+
+始终使用上下文提供的 React 实例，避免使用 JSX 语法：
+
+```typescript
+// ✅ 正确 - 使用上下文的 React 实例
+wrapComponent: (WrappedComponent, context) => {
+  const { React: ContextReact } = context;
+  return ContextReact.forwardRef((props, ref) => {
+    // 使用 createElement 确保实例一致性
+    return ContextReact.createElement(WrappedComponent, { ...props, ref });
+  });
+}
+
+// ❌ 错误 - 使用导入的 React 实例
+import React from 'react';
+wrapComponent: (WrappedComponent, context) => {
+  return React.forwardRef((props, ref) => {  // 可能是错误的 React 实例
+    return <WrappedComponent {...props} ref={ref} />; // JSX 使用编译时的 React
+  });
+}
+```
+
+**为什么不能直接用 JSX？**
+
+在微前端场景中：
+- 主应用和远程模块可能使用不同版本的 React
+- JSX 编译时绑定到特定的 React 实例
+- 使用 `ContextReact.createElement` 确保运行时使用正确的实例
+
+### 2. Ref 转发
+
+确保正确转发 ref：
+
+```typescript
+const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
+  return ContextReact.createElement(WrappedComponent, { ...props, ref });
+});
+```
+
+## 故障排除
+
+### 常见问题
+
+1. **插件不生效**
+   - 确保插件已正确注册
+   - 检查插件名称是否唯一
+   - 验证插件函数是否正确实现
+
+2. **React Hook 错误**
+   - 确保使用上下文提供的 React 实例
+   - 检查是否在条件语句中使用 Hook
+
+3. **Ref 转发失败**
+   - 确保使用 `React.forwardRef`
+   - 检查 ref 是否正确传递给底层组件
+
+4. **类型错误**
+   - 确保导入正确的类型定义
+   - 使用 `React.ComponentType<any>` 处理动态组件类型
+
+### 调试技巧
+
+```typescript
+// 启用调试日志
+registerEnhancedPlugin(createEnhancedLoggingPlugin({
+  level: 'debug',
+  logComponentRender: true
+}));
+
+// 检查插件状态
+const manager = getEnhancedPluginManager();
+console.log('Registered plugins:', manager.getPluginInfo());
+```

package/es2017/RemoteModule.js

@@ -2,10 +2,13 @@ import { _ as _object_spread } from "@swc/helpers/_/_object_spread";
 import { loadRemote } from '@module-federation/runtime';
 import * as React from 'react';
 import { useMemo, useState, useLayoutEffect, forwardRef } from 'react';
+import * as ReactDOM from 'react-dom';
 import { ErrorBoundary } from 'react-error-boundary';
 import { FallBack } from './FallBack';
 import { setFederatedModulePublicPath } from './set-public-path';
 import { getMicroMod } from './mf-global-store';
+import { useEnhancedPluginManager } from './plugin-manager';
+import { isRuntimePluginWrapper } from './types';
 const useMountNode = (mountNodeConfig)=>{
     const [resolvedNode, setResolvedNode] = useState(undefined);
     // 解析各种类型的 mountNode
@@ -35,6 +38,7 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
     var _microMod, _runtime, _runtime1;
     const microMod = getMicroMod(scope);
     const resolvedMountNode = useMountNode(mountNode);
+    const enhancedPluginManager = useEnhancedPluginManager();
     if ((_microMod = microMod) === null || _microMod === void 0 ? void 0 : _microMod.publicPath) {
         setFederatedModulePublicPath(microMod.moduleFederatedName, microMod.publicPath);
     }
@@ -45,35 +49,76 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
         if (!module || !scope) return null;
         return /*#__PURE__*/ React.lazy(async ()=>{
             var _typedRemoteModule;
+            // 使用标准 MF 加载逻辑，MF 插件自动执行
             const remoteModule = await loadRemote(`${scope}/${module}`);
-            // 检查是否是来自 runtime plugin 的包装函数（通过标记识别）
-            if (typeof remoteModule === 'function' && remoteModule.__ICE_MF_RUNTIME_WRAPPER__) {
-                // 调用包装函数并传入 mountNode 和 containerClassName
-                const ComponentFromPlugin = remoteModule(resolvedMountNode, fallbackContainerClassName);
+            // 使用清晰的对象结构检查是否为 Runtime Plugin 包装器
+            if (isRuntimePluginWrapper(remoteModule)) {
+                // 提取原始组件、运行时信息和 React 实例
+                const { originalComponent, runtimeInfo, reactInstances } = remoteModule();
+                const remoteReact = reactInstances.react;
+                const remoteReactDOM = reactInstances.reactDOM;
+                // 🔑 正确的 HOC 层级顺序：
+                // 1. 先应用增强插件（与其他情况保持一致）
+                const PluginWrappedComponent = enhancedPluginManager.wrapComponent(originalComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: remoteReact,
+                    ReactDOM: remoteReactDOM
+                });
+                // 2. 再应用 FallBack（处理不同 React 版本和 mountNode）
+                const FinalComponent = FallBack({
+                    Original: PluginWrappedComponent,
+                    remoteVersion: runtimeInfo.remoteVersion ? ()=>runtimeInfo.remoteVersion : undefined,
+                    hostVersion: runtimeInfo.hostVersion ? ()=>runtimeInfo.hostVersion : undefined,
+                    remoteReactDOM: runtimeInfo.remoteReactDOM,
+                    remoteReact: runtimeInfo.remoteReact,
+                    mountNode: resolvedMountNode,
+                    containerClassName: fallbackContainerClassName
+                });
                 return {
-                    default: ComponentFromPlugin
+                    default: FinalComponent
                 };
             }
             const typedRemoteModule = remoteModule;
+            let BaseComponent;
             if (!((_typedRemoteModule = typedRemoteModule) === null || _typedRemoteModule === void 0 ? void 0 : _typedRemoteModule.default)) {
-                return {
-                    default: remoteModule
-                };
+                BaseComponent = remoteModule;
+            } else {
+                BaseComponent = typedRemoteModule.default;
             }
+            let FinalComponent;
+            // 如果需要 runtime 处理（不同 React 版本或 mountNode）
             if (runtime) {
                 const { react, reactDOM } = runtime;
-                return {
-                    default: FallBack({
-                        Original: typedRemoteModule.default,
-                        remoteReact: ()=>react,
-                        remoteReactDOM: ()=>reactDOM,
-                        mountNode: resolvedMountNode,
-                        containerClassName: fallbackContainerClassName
-                    })
-                };
+                // 先应用增强插件的组件包装器，然后传给 FallBack
+                const PluginWrappedComponent = enhancedPluginManager.wrapComponent(BaseComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: react,
+                    ReactDOM: reactDOM
+                });
+                FinalComponent = FallBack({
+                    Original: PluginWrappedComponent,
+                    remoteReact: ()=>react,
+                    remoteReactDOM: ()=>reactDOM,
+                    mountNode: resolvedMountNode,
+                    containerClassName: fallbackContainerClassName
+                });
+            } else {
+                // 没有 runtime 需求时，直接应用插件包装器
+                FinalComponent = enhancedPluginManager.wrapComponent(BaseComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: React,
+                    ReactDOM: ReactDOM
+                });
             }
+            console.log('FinalComponent', FinalComponent);
             return {
-                default: typedRemoteModule.default
+                default: FinalComponent
             };
         });
     }, [
@@ -82,11 +127,18 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
         (_runtime = runtime) === null || _runtime === void 0 ? void 0 : _runtime.react,
         (_runtime1 = runtime) === null || _runtime1 === void 0 ? void 0 : _runtime1.reactDOM,
         resolvedMountNode,
-        fallbackContainerClassName
+        fallbackContainerClassName,
+        enhancedPluginManager,
+        componentProps
     ]);
     const Loading = LoadingComponent || /*#__PURE__*/ React.createElement("div", null, "Loading...");
     const ErrorFallback = ({ error })=>ErrorComponent || /*#__PURE__*/ React.createElement("div", null, "远程模块加载失败: ", error.message);
     if (!Component) return Loading;
+    // 应用增强插件的属性注入
+    const injectedProps = enhancedPluginManager.injectProps(componentProps || {}, {
+        remoteName: scope,
+        moduleName: module
+    });
     return /*#__PURE__*/ React.createElement(ErrorBoundary, {
         resetKeys: [
             module,
@@ -98,8 +150,8 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
     }, /*#__PURE__*/ React.createElement(React.Suspense, {
         fallback: Loading
     }, /*#__PURE__*/ React.createElement(Component, _object_spread({
-        ref: ref
-    }, componentProps), children)));
+        ref
+    }, injectedProps), children)));
 };
 // 使用 forwardRef 包装组件以支持 ref
 export const RemoteModule = /*#__PURE__*/ forwardRef(RemoteModuleInner);

package/es2017/__tests__/plugin-manager.test.d.ts

@@ -0,0 +1 @@
+export {};