@bm-fe/react-native-multi-bundle 1.0.0-beta.0

package/src/multi-bundle/config.ts

@@ -0,0 +1,141 @@
+/**
+ * MultiBundleConfig - 多 Bundle 配置系统
+ * 提供统一的配置接口，支持代码配置方式
+ */
+
+import { BundleManifest } from './ModuleRegistry';
+import { Platform } from 'react-native';
+
+/**
+ * 开发服务器配置
+ */
+export interface DevServerConfig {
+  host: string;
+  port: number;
+  protocol?: 'http' | 'https';
+}
+
+/**
+ * Manifest 提供者类型
+ * 支持函数（异步获取）或 URL 字符串
+ */
+export type ManifestProvider = (() => Promise<BundleManifest>) | string;
+
+/**
+ * ModuleLoader 接口
+ */
+export interface ModuleLoader {
+  loadBusinessBundle(moduleId: string, bundlePath: string): Promise<{ success: boolean; errorMessage?: string }>;
+}
+
+/**
+ * 多 Bundle 配置接口
+ */
+export interface MultiBundleConfig {
+  /**
+   * 模块路径规则（glob 模式）
+   * 用于 Metro 配置中识别模块 bundle
+   * 例如: ['src/modules/**']
+   */
+  modulePaths?: string[];
+
+  /**
+   * 共享依赖路径列表（glob 模式）
+   * 这些路径下的代码会被打包到主 bundle，模块 bundle 可以共享使用
+   * 例如: ['src/multi-bundle/**', 'src/navigation/**']
+   */
+  sharedDependencies?: string[];
+
+  /**
+   * Manifest 提供者
+   * - 函数：自定义获取逻辑
+   * - 字符串：manifest URL（开发环境从 HTTP 服务器获取）
+   */
+  manifestProvider?: ManifestProvider;
+
+  /**
+   * 自定义 ModuleLoader（可选）
+   * 如果不提供，将使用默认的 ModuleLoader（开发环境用 Mock，生产环境用 Native）
+   */
+  moduleLoader?: ModuleLoader;
+
+  /**
+   * 预加载模块列表
+   * 应用启动时自动预加载这些模块
+   */
+  preloadModules?: string[];
+
+  /**
+   * 开发服务器配置
+   * 用于开发环境从 HTTP 服务器获取 manifest 和 bundle
+   */
+  devServer?: DevServerConfig;
+
+  /**
+   * 错误处理回调
+   */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 默认配置
+ */
+const DEFAULT_CONFIG: Required<Omit<MultiBundleConfig, 'moduleLoader' | 'manifestProvider' | 'onError'>> & {
+  moduleLoader?: ModuleLoader;
+  manifestProvider?: ManifestProvider;
+  onError?: (error: Error) => void;
+} = {
+  modulePaths: ['src/modules/**'],
+  sharedDependencies: ['src/multi-bundle/**', 'src/navigation/**'],
+  preloadModules: [],
+  devServer: {
+    host: Platform.OS === 'android' ? '10.0.2.2' : 'localhost',
+    port: 8081,
+    protocol: 'http',
+  },
+};
+
+/**
+ * 合并配置
+ * 将用户配置与默认配置合并
+ */
+export function mergeConfig(
+  userConfig: MultiBundleConfig
+): Required<Omit<MultiBundleConfig, 'moduleLoader' | 'manifestProvider' | 'onError'>> & {
+  moduleLoader?: ModuleLoader;
+  manifestProvider?: ManifestProvider;
+  onError?: (error: Error) => void;
+} {
+  return {
+    modulePaths: userConfig.modulePaths ?? DEFAULT_CONFIG.modulePaths,
+    sharedDependencies: userConfig.sharedDependencies ?? DEFAULT_CONFIG.sharedDependencies,
+    preloadModules: userConfig.preloadModules ?? DEFAULT_CONFIG.preloadModules,
+    devServer: {
+      ...DEFAULT_CONFIG.devServer,
+      ...userConfig.devServer,
+    },
+    moduleLoader: userConfig.moduleLoader,
+    manifestProvider: userConfig.manifestProvider,
+    onError: userConfig.onError,
+  };
+}
+
+/**
+ * 全局配置实例（用于 Metro 配置等场景）
+ */
+let globalConfig: ReturnType<typeof mergeConfig> | null = null;
+
+/**
+ * 设置全局配置
+ */
+export function setGlobalConfig(config: ReturnType<typeof mergeConfig>) {
+  globalConfig = config;
+}
+
+/**
+ * 获取全局配置
+ */
+export function getGlobalConfig(): ReturnType<typeof mergeConfig> | null {
+  return globalConfig;
+}
+

package/src/multi-bundle/createModuleLoader.tsx

@@ -0,0 +1,92 @@
+/**
+ * createModuleLoader - 创建模块加载器函数
+ * 用于 React Navigation 的 getComponent API，实现真正的懒加载
+ * 组件只在导航到该路由时才被创建和加载
+ */
+
+import React, { useEffect, useState } from 'react';
+import { ModuleRegistry } from './ModuleRegistry';
+import { ModuleLoadingPlaceholder } from './ModuleLoadingPlaceholder';
+import { ModuleErrorFallback } from './ModuleErrorFallback';
+
+type ModuleState = 'idle' | 'loading' | 'success' | 'error';
+
+interface CreateModuleLoaderOptions {
+  onError?: (error: Error) => void;
+}
+
+/**
+ * 创建模块加载器函数
+ * @param moduleId 模块 ID
+ * @param pickComponent 从模块 exports 中提取组件的函数
+ * @param options 可选配置
+ * @returns 返回一个函数，该函数返回 React 组件（用于 getComponent）
+ */
+export function createModuleLoader(
+  moduleId: string,
+  pickComponent: (exports: any) => React.ComponentType<any>,
+  options: CreateModuleLoaderOptions = {}
+): () => React.ComponentType<any> {
+  return function getModuleComponent() {
+    function ModuleWrappedScreen(props: any) {
+      const [state, setState] = useState<ModuleState>('idle');
+      const [InnerComponent, setInnerComponent] =
+        useState<React.ComponentType<any> | null>(null);
+      const [error, setError] = useState<Error | null>(null);
+
+      useEffect(() => {
+        let isMounted = true;
+
+        async function load() {
+          try {
+            setState('loading');
+
+            await ModuleRegistry.loadModule(moduleId);
+            if (!isMounted) return;
+
+            const exports = ModuleRegistry.getModuleExports(moduleId);
+            const Comp = pickComponent(exports);
+
+            setInnerComponent(() => Comp);
+            setState('success');
+          } catch (e) {
+            if (!isMounted) return;
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            setState('error');
+            options.onError?.(err);
+          }
+        }
+
+        load();
+
+        return () => {
+          isMounted = false;
+        };
+      }, [moduleId]);
+
+      if (state === 'error') {
+        return (
+          <ModuleErrorFallback
+            moduleId={moduleId}
+            error={error}
+            onRetry={() => {
+              setState('idle');
+              setError(null);
+            }}
+          />
+        );
+      }
+
+      if (state === 'loading' || !InnerComponent) {
+        return <ModuleLoadingPlaceholder moduleId={moduleId} />;
+      }
+
+      return <InnerComponent {...props} />;
+    }
+
+    (ModuleWrappedScreen as any).displayName = `ModuleLoader(${moduleId})`;
+
+    return ModuleWrappedScreen;
+  };
+}

package/src/multi-bundle/createModuleRouteLoader.tsx

@@ -0,0 +1,31 @@
+/**
+ * createModuleRouteLoader - 创建路由模块加载器函数
+ * 简化路由定义的辅助函数，自动从模块 exports.routes 中提取组件
+ * 用于 React Navigation 的 getComponent API
+ */
+
+import React from 'react';
+import { createModuleLoader } from './createModuleLoader';
+
+/**
+ * 创建路由模块加载器函数
+ * @param moduleId 模块 ID
+ * @param routeKey 路由 key（对应模块 exports.routes[routeKey]）
+ * @returns 返回一个函数，该函数返回 React 组件（用于 getComponent）
+ */
+export function createModuleRouteLoader(
+  moduleId: string,
+  routeKey: string
+): () => React.ComponentType<any> {
+  return createModuleLoader(
+    moduleId,
+    (exports: any) => {
+      if (!exports || !exports.routes || !exports.routes[routeKey]) {
+        throw new Error(
+          `Route "${routeKey}" not found in module "${moduleId}"`
+        );
+      }
+      return exports.routes[routeKey];
+    }
+  );
+}

package/src/multi-bundle/devUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * devUtils - 开发工具函数
+ * 提供开发模式下的调试和工具函数
+ */
+
+import { ModuleRegistry } from './ModuleRegistry';
+
+/**
+ * 获取所有模块的状态信息
+ */
+export function getAllModuleStates() {
+  // 这里需要访问 ModuleRegistry 的内部状态
+  // 为了不暴露内部实现，我们可以通过 ModuleRegistry 添加一个调试方法
+  // 当前简化实现
+  return {
+    // 可以通过 ModuleRegistry 暴露的方法获取
+  };
+}
+
+/**
+ * 开发模式下的日志
+ */
+export function logModuleLoad(moduleId: string, event: string, data?: any) {
+  if (__DEV__) {
+    console.log(`[ModuleRegistry:${moduleId}] ${event}`, data || '');
+  }
+}
+
+/**
+ * 重置模块状态（仅开发环境）
+ */
+export function resetModule(moduleId: string) {
+  if (__DEV__) {
+    console.warn(`[devUtils] resetModule is not implemented yet for: ${moduleId}`);
+    // 实际实现需要 ModuleRegistry 暴露 reset 方法
+  }
+}
+
+/**
+ * 重新加载模块（仅开发环境）
+ */
+export function reloadModule(moduleId: string) {
+  if (__DEV__) {
+    console.warn(`[devUtils] reloadModule is not implemented yet for: ${moduleId}`);
+    // 实际实现需要 ModuleRegistry 暴露 reload 方法
+  }
+}
+

package/src/multi-bundle/init.ts

@@ -0,0 +1,131 @@
+/**
+ * initMultiBundle - 多 Bundle 统一初始化入口
+ * 封装所有初始化逻辑，业务代码只需调用一次即可完成所有初始化
+ */
+
+import { ModuleRegistry, BundleManifest } from './ModuleRegistry';
+import { preloadModule } from './preloadModule';
+import { mergeConfig, setGlobalConfig, MultiBundleConfig } from './config';
+import { LocalBundleManager } from './LocalBundleManager';
+import { HMRClient } from './HMRClient';
+
+/**
+ * 初始化结果
+ */
+export interface InitResult {
+  success: boolean;
+  error?: Error;
+  manifest?: BundleManifest;
+}
+
+/**
+ * 从 manifestProvider 获取 manifest
+ */
+async function getManifestFromProvider(
+  provider: MultiBundleConfig['manifestProvider']
+): Promise<BundleManifest> {
+  if (!provider) {
+    // 如果没有提供 provider，使用默认的 LocalBundleManager
+    return await LocalBundleManager.getCurrentBundleManifest();
+  }
+
+  if (typeof provider === 'string') {
+    // URL 模式：从 HTTP 服务器获取
+    try {
+      const response = await fetch(provider);
+      if (response.ok) {
+        return await response.json();
+      }
+      throw new Error(`Failed to fetch manifest from ${provider}: ${response.statusText}`);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.warn(`[initMultiBundle] Failed to fetch manifest from URL: ${err.message}`);
+      // 降级到默认方式
+      return await LocalBundleManager.getCurrentBundleManifest();
+    }
+  } else {
+    // 函数模式：调用自定义函数
+    return await provider();
+  }
+}
+
+/**
+ * 初始化多 Bundle 系统
+ * 
+ * @param config 配置对象
+ * @returns 初始化结果
+ * 
+ * @example
+ * ```typescript
+ * const result = await initMultiBundle({
+ *   modulePaths: ['src/modules/**'],
+ *   sharedDependencies: ['src/multi-bundle/**', 'src/navigation/**'],
+ *   preloadModules: ['settings'],
+ * });
+ * ```
+ */
+export async function initMultiBundle(config: MultiBundleConfig = {}): Promise<InitResult> {
+  try {
+    // 1. 合并配置
+    const mergedConfig = mergeConfig(config);
+    
+    // 2. 设置全局配置（供 Metro 配置等使用）
+    setGlobalConfig(mergedConfig);
+
+    // 2.5 初始化 HMR Client (开发环境)
+    if (__DEV__ && mergedConfig.devServer) {
+      HMRClient.getInstance().setup(
+        mergedConfig.devServer.host,
+        mergedConfig.devServer.port
+      );
+    }
+
+    // 3. 获取 manifest
+    let manifest: BundleManifest;
+    try {
+      manifest = await getManifestFromProvider(mergedConfig.manifestProvider);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      console.error('[initMultiBundle] Failed to get manifest:', err);
+      config.onError?.(err);
+      return {
+        success: false,
+        error: err,
+      };
+    }
+
+    // 4. 设置自定义 ModuleLoader（如果提供）
+    if (mergedConfig.moduleLoader) {
+      ModuleRegistry.setModuleLoader(mergedConfig.moduleLoader);
+    }
+
+    // 5. 初始化 ModuleRegistry
+    ModuleRegistry.init({ manifest });
+
+    // 6. 预加载模块
+    if (mergedConfig.preloadModules && mergedConfig.preloadModules.length > 0) {
+      const preloadPromises = mergedConfig.preloadModules.map((moduleId) =>
+        preloadModule(moduleId).catch((error) => {
+          // 预加载失败不影响初始化，只记录日志
+          console.warn(`[initMultiBundle] Preload module ${moduleId} failed:`, error);
+          config.onError?.(error instanceof Error ? error : new Error(String(error)));
+        })
+      );
+      await Promise.allSettled(preloadPromises);
+    }
+
+    return {
+      success: true,
+      manifest,
+    };
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error('[initMultiBundle] Initialization failed:', err);
+    config.onError?.(err);
+    return {
+      success: false,
+      error: err,
+    };
+  }
+}
+

package/src/multi-bundle/metro-config-helper.js

@@ -0,0 +1,140 @@
+/**
+ * Metro 配置辅助模块
+ * 用于在 Node.js 环境中读取多 Bundle 配置
+ * 支持从环境变量或默认值读取配置
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 从环境变量读取配置
+ */
+function getConfigFromEnv() {
+  const modulePaths = process.env.RN_MULTI_BUNDLE_MODULE_PATHS
+    ? JSON.parse(process.env.RN_MULTI_BUNDLE_MODULE_PATHS)
+    : ['src/modules/**'];
+  
+  const sharedDependencies = process.env.RN_MULTI_BUNDLE_SHARED_DEPS
+    ? JSON.parse(process.env.RN_MULTI_BUNDLE_SHARED_DEPS)
+    : ['src/multi-bundle/**', 'src/navigation/**'];
+
+  return {
+    modulePaths,
+    sharedDependencies,
+  };
+}
+
+/**
+ * 检查路径是否匹配 glob 模式
+ * 简化版 glob 匹配（支持 ** 和 *）
+ */
+function matchGlob(filePath, pattern) {
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+  
+  // 将 glob 模式转换为正则表达式
+  const regexPattern = normalizedPattern
+    .replace(/\*\*/g, '___DOUBLE_STAR___')
+    .replace(/\*/g, '[^/]*')
+    .replace(/___DOUBLE_STAR___/g, '.*');
+  
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(normalizedPath);
+}
+
+/**
+ * 检查文件路径是否匹配模块路径规则
+ */
+function isModulePath(filePath, modulePaths) {
+  return modulePaths.some((pattern) => matchGlob(filePath, pattern));
+}
+
+/**
+ * 检查文件路径是否是共享依赖
+ */
+function isSharedDependencyPath(filePath, sharedDependencies) {
+  // 先检查 node_modules 中的共享依赖
+  if (filePath.includes('/node_modules/')) {
+    const sharedNodeModules = [
+      'react',
+      'react/jsx-runtime',
+      'react-native',
+      '@react-navigation',
+    ];
+    return sharedNodeModules.some((dep) =>
+      filePath.includes(`/node_modules/${dep}`)
+    );
+  }
+  
+  // 再检查本地共享依赖路径
+  return sharedDependencies.some((pattern) => matchGlob(filePath, pattern));
+}
+
+/**
+ * 从模块路径提取模块名（支持配置化的路径规则）
+ */
+function extractModuleNameFromPath(modulePath, modulePaths) {
+  const normalizedPath = modulePath.replace(/\\/g, '/');
+  
+  // 尝试从配置的模块路径中提取模块名
+  for (const pattern of modulePaths) {
+    // 将 glob 模式转换为匹配模式
+    // 例如: src/modules/** -> src/modules/([^/]+)
+    const matchPattern = pattern
+      .replace(/\*\*/g, '.*')
+      .replace(/\*/g, '[^/]*')
+      .replace(/\(\[/g, '(')
+      .replace(/\]\*\)/g, '+)');
+    
+    // 尝试提取模块名
+    // 对于 src/modules/**，我们尝试匹配 src/modules/([^/]+)/
+    const regex = new RegExp(`src/modules/([^/]+)/`, 'i');
+    const match = normalizedPath.match(regex);
+    if (match) {
+      return match[1].toLowerCase();
+    }
+  }
+  
+  // 降级到默认规则（向后兼容）
+  const defaultMatch = normalizedPath.match(/src\/modules\/([^\/]+)\//i);
+  if (defaultMatch) {
+    return defaultMatch[1].toLowerCase();
+  }
+  
+  return null;
+}
+
+/**
+ * 从模块入口路径提取模块名（支持配置化的路径规则）
+ */
+function extractModuleNameFromEntry(modulePath, modulePaths) {
+  const normalizedPath = modulePath.replace(/\\/g, '/');
+  
+  // 尝试从配置的模块路径中提取模块名
+  for (const pattern of modulePaths) {
+    // 对于入口文件，通常格式为 src/modules/ModuleName/index.ts
+    const regex = new RegExp(`src/modules/([^/]+)/index\\.(ts|tsx|js|jsx)$`, 'i');
+    const match = normalizedPath.match(regex);
+    if (match) {
+      return match[1].toLowerCase();
+    }
+  }
+  
+  // 降级到默认规则（向后兼容）
+  const defaultMatch = normalizedPath.match(/src\/modules\/([^\/]+)\/index\.(ts|tsx|js|jsx)$/i);
+  if (defaultMatch) {
+    return defaultMatch[1].toLowerCase();
+  }
+  
+  return null;
+}
+
+module.exports = {
+  getConfigFromEnv,
+  isModulePath,
+  isSharedDependencyPath,
+  extractModuleNameFromPath,
+  extractModuleNameFromEntry,
+};
+

package/src/multi-bundle/preloadModule.ts

@@ -0,0 +1,33 @@
+/**
+ * preloadModule - 模块预加载函数
+ * 静默预加载模块，失败不打断主流程
+ */
+
+import { ModuleRegistry } from './ModuleRegistry';
+
+/**
+ * 预加载模块
+ * @param moduleId 模块 ID
+ */
+export async function preloadModule(moduleId: string): Promise<void> {
+  const state = ModuleRegistry.getModuleState(moduleId);
+  
+  // 已加载就不干活
+  if (state === 'loaded') {
+    return;
+  }
+  
+  // loading 中也不重复发起
+  if (state === 'loading') {
+    return;
+  }
+
+  try {
+    await ModuleRegistry.loadModule(moduleId);
+  } catch (error) {
+    // 预加载失败对用户"无感知"，但记录日志 / 埋点
+    console.warn(`[preloadModule] failed: ${moduleId}`, error);
+    // 可以在这里上报监控
+  }
+}
+