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

package/src/multi-bundle/ModuleRegistry.ts

@@ -0,0 +1,295 @@
+/**
+ * ModuleRegistry - 模块生命周期管理器
+ * 负责管理模块的加载、状态、依赖关系
+ */
+
+import { NativeModules } from 'react-native';
+import { ModuleLoader as ModuleLoaderMock } from './ModuleLoaderMock';
+
+type ModuleState = 'idle' | 'loading' | 'loaded' | 'failed';
+
+interface ModuleMeta {
+  file: string;
+  version: string;
+  dependencies: string[];
+  lazy: boolean;
+}
+
+interface ModuleLoadPromise {
+  promise: Promise<void>;
+  resolveRegister: () => void;
+  rejectRegister: (error: Error) => void;
+}
+
+interface BundleManifest {
+  formatVersion: number;
+  main: {
+    file: string;
+    version: string;
+  };
+  modules: Array<{
+    id: string;
+    file: string;
+    version: string;
+    dependencies?: string[];
+    lazy?: boolean;
+  }>;
+}
+
+const REGISTER_TIMEOUT_MS = 5000;
+
+// 内部闭包数据（不暴露给业务方）
+// 允许外部注入 ModuleLoader（主要用于测试）
+let injectedModuleLoader: any = null;
+
+const moduleMeta: Record<string, ModuleMeta> = {};
+const moduleState: Record<string, ModuleState> = {};
+const moduleExports: Record<string, any> = {};
+const moduleLoadPromises: Record<string, ModuleLoadPromise> = {};
+
+// 循环依赖检测
+function checkCircularDependency(
+  moduleId: string,
+  visited: Set<string>,
+  path: string[]
+): void {
+  if (visited.has(moduleId)) {
+    const cycle = [...path, moduleId].join(' -> ');
+    throw new Error(`Circular dependency detected: ${cycle}`);
+  }
+
+  visited.add(moduleId);
+  path.push(moduleId);
+
+  const deps = moduleMeta[moduleId]?.dependencies || [];
+  deps.forEach((depId) => {
+    if (moduleMeta[depId]) {
+      checkCircularDependency(depId, new Set(visited), [...path]);
+    }
+  });
+}
+
+/**
+ * 设置 ModuleLoader（仅供测试使用）
+ * 注意：实际接口是 CodePush.loadBusinessBundle，但为了兼容性保留此方法名
+ */
+function setModuleLoader(loader: any) {
+  injectedModuleLoader = loader;
+}
+
+function resetInternalState() {
+  injectedModuleLoader = injectedModuleLoader; // 保留注入的 loader
+
+  for (const key of Object.keys(moduleMeta)) delete moduleMeta[key];
+  for (const key of Object.keys(moduleState)) delete moduleState[key];
+  for (const key of Object.keys(moduleExports)) delete moduleExports[key];
+  for (const key of Object.keys(moduleLoadPromises))
+    delete moduleLoadPromises[key];
+}
+
+/**
+ * 初始化 ModuleRegistry
+ * 
+ * @param manifest - Bundle manifest，包含所有模块的元数据
+ * 
+ * 注意：
+ * - rootPath 不需要传入，Native 层会自己处理路径查找
+ * - manifest 只在初始化时使用，初始化后会被丢弃（信息已提取到 moduleMeta）
+ */
+function init(options: { manifest: BundleManifest }): void {
+  // 每次 init 先 reset，避免残留状态
+  resetInternalState();
+  
+  const { manifest } = options;
+
+  // 校验
+  if (!manifest) {
+    throw new Error('ModuleRegistry init failed: missing manifest');
+  }
+
+  // 解析 meta
+  manifest.modules.forEach((m) => {
+    const id = m.id;
+    moduleMeta[id] = {
+      file: m.file,
+      version: m.version,
+      dependencies: m.dependencies || [],
+      lazy: !!m.lazy,
+    };
+    moduleState[id] = 'idle';
+    moduleExports[id] = undefined;
+  });
+
+  // 检测循环依赖
+  manifest.modules.forEach((m) => {
+    checkCircularDependency(m.id, new Set(), []);
+  });
+}
+
+const map = {};
+
+/**
+ * 注册模块（供模块 bundle 调用）
+ */
+function registerModule(moduleId: string, exportsObj: any): void {
+  if (!moduleMeta[moduleId]) {
+    console.warn(`registerModule: unknown moduleId=${moduleId}`);
+    return;
+  }
+
+  map[moduleId] = 1;
+
+  moduleExports[moduleId] = exportsObj;
+  moduleState[moduleId] = 'loaded';
+
+  const pending = moduleLoadPromises[moduleId];
+  if (pending?.resolveRegister) {
+    pending.resolveRegister();
+  }
+}
+
+/**
+ * 获取模块状态
+ */
+function getModuleState(moduleId: string): ModuleState {
+  return moduleState[moduleId] || 'idle';
+}
+
+/**
+ * 获取模块导出对象
+ */
+function getModuleExports(moduleId: string): any {
+  if (moduleState[moduleId] !== 'loaded') {
+    throw new Error(`Module ${moduleId} not loaded yet`);
+  }
+  return moduleExports[moduleId];
+}
+
+/**
+ * 加载模块（核心逻辑）
+ */
+async function loadModule(moduleId: string): Promise<void> {
+  // 1. 非法模块
+  if (!moduleMeta[moduleId]) {
+    throw new Error(`Unknown module: ${moduleId}`);
+  }
+
+  // 2. 已加载完成
+  if (moduleState[moduleId] === 'loaded') {
+    return;
+  }
+
+  // 3. 并发加载处理
+  if (moduleLoadPromises[moduleId]) {
+    return moduleLoadPromises[moduleId].promise;
+  }
+
+  // 4. 创建一个加载 Promise（缓存）
+  let resolveRegister!: () => void;
+  let rejectRegister!: (error: Error) => void;
+  
+  const registerPromise = new Promise<void>((resolve, reject) => {
+    resolveRegister = resolve;
+    rejectRegister = reject;
+  });
+
+  const loadPromise = (async () => {
+    try {
+      // Step 1：递归加载依赖
+      const deps = moduleMeta[moduleId].dependencies;
+      for (const depId of deps) {
+        await loadModule(depId);
+        if (moduleState[depId] !== 'loaded') {
+          throw new Error(
+            `Dependency ${depId} failed for module ${moduleId}. State: ${moduleState[depId]}`
+          );
+        }
+      }
+
+      // Step 2：设置加载状态
+      moduleState[moduleId] = 'loading';
+
+      // Step 3：选择 ModuleLoader
+      let loader: any = injectedModuleLoader;
+      
+      if (!loader) {
+        // 开发环境：优先使用 ModuleLoaderMock（HTTP 模式）
+        if (__DEV__) {
+          loader = ModuleLoaderMock;
+        } else {
+          // 生产环境：使用 Native CodePush 模块
+          if (NativeModules?.ModuleLoader.loadBusinessBundle) {
+            loader = NativeModules.ModuleLoader;
+          } else {
+            throw new Error(
+              'ModuleLoader not available: Native CodePush module not found in production'
+            );
+          }
+        }
+      }
+
+      // 传入 bundleId（即 moduleId）和 bundlePath（从 manifest 中获取）
+      const bundlePath = moduleMeta[moduleId].file;
+      const result = await loader.loadBusinessBundle(moduleId, bundlePath);
+      if (!result?.success) {
+        moduleState[moduleId] = 'failed';
+        const err = new Error(result?.errorMessage || 'LOAD_FAILED');
+        rejectRegister(err); // 提前结束 registerPromise
+        throw err;
+      }
+
+      // Step 4：等待 registerModule 执行
+      await Promise.race([
+        registerPromise,
+        new Promise<void>((_, reject) =>
+          setTimeout(
+            () => reject(new Error('REGISTER_TIMEOUT')),
+            REGISTER_TIMEOUT_MS
+          )
+        ),
+      ]);
+
+      // 验证模块确实已注册
+      // 注意：TypeScript 可能无法正确推断状态，但运行时检查是必要的
+      const finalState = moduleState[moduleId] as ModuleState;
+      if (finalState !== 'loaded') {
+        throw new Error(`registerModule not called: ${moduleId}, state: ${finalState}`);
+      }
+    } catch (err) {
+      moduleState[moduleId] = 'failed';
+      const error =
+        err instanceof Error ? err : new Error(String(err));
+      console.error(`[ModuleRegistry] load failed: ${moduleId}`, error);
+      throw error;
+    } finally {
+      delete moduleLoadPromises[moduleId];
+    }
+  })();
+
+  moduleLoadPromises[moduleId] = {
+    promise: loadPromise,
+    resolveRegister,
+    rejectRegister,
+  };
+
+  return loadPromise;
+}
+
+export const ModuleRegistry = {
+  init,
+  loadModule,
+  registerModule,
+  getModuleState,
+  getModuleExports,
+  setModuleLoader,
+  map,
+};
+
+// 将 ModuleRegistry 挂载到全局作用域，以便模块 bundle 可以访问
+// 这在开发环境中特别重要，因为模块 bundle 和主 bundle 共享同一个 JS 上下文
+if (typeof globalThis !== 'undefined') {
+  globalThis.__ModuleRegistry = ModuleRegistry;
+}
+
+export type { BundleManifest, ModuleState };
+

package/src/multi-bundle/README.md

@@ -0,0 +1,343 @@
+# React Native 多 Bundle 系统
+
+多 Bundle 系统提供了模块化的代码分割方案，支持将 React Native 应用拆分为多个独立的 bundle，实现按需加载和独立更新。
+
+## 快速接入
+
+### 1. 初始化多 Bundle 系统
+
+在应用入口（通常是 `App.tsx`）中调用 `initMultiBundle`：
+
+```typescript
+import { initMultiBundle } from './src/multi-bundle/init';
+import { LocalBundleManager } from './src/multi-bundle/LocalBundleManager';
+import { Platform } from 'react-native';
+
+function App() {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    async function bootstrap() {
+      const result = await initMultiBundle({
+        // 模块路径规则（glob 模式）
+        modulePaths: ['src/modules/**'],
+        
+        // 共享依赖路径（这些代码会被打包到主 bundle）
+        sharedDependencies: ['src/multi-bundle/**', 'src/navigation/**'],
+        
+        // Manifest 提供者（可选，默认使用 LocalBundleManager）
+        manifestProvider: async () => {
+          return await LocalBundleManager.getCurrentBundleManifest();
+        },
+        
+        // 预加载模块列表（可选）
+        preloadModules: ['settings'],
+        
+        // 开发服务器配置（可选）
+        devServer: {
+          host: Platform.OS === 'android' ? '10.0.2.2' : 'localhost',
+          port: 8081,
+        },
+        
+        // 错误处理回调（可选）
+        onError: (error) => {
+          console.error('MultiBundle error:', error);
+        },
+      });
+
+      if (result.success) {
+        setReady(true);
+      }
+    }
+
+    bootstrap();
+  }, []);
+
+  if (!ready) {
+    return <LoadingScreen />;
+  }
+
+  // ... 其余代码
+}
+```
+
+### 2. 使用模块路由
+
+#### 方式一：使用 `createModuleRouteLoader` + `getComponent`（推荐，React Navigation v7+）
+
+这是推荐的方式，支持真正的懒加载，组件只在导航到该路由时才被创建：
+
+```typescript
+import { createModuleRouteLoader } from './src/multi-bundle/createModuleRouteLoader';
+
+// 创建路由加载器函数
+export const createHomeScreen = createModuleRouteLoader('home', 'Home');
+export const createDetailScreen = createModuleRouteLoader('details', 'Details');
+```
+
+在 React Navigation 中使用：
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { createHomeScreen, createDetailScreen } from './src/navigation/moduleRoutes';
+
+const Stack = createNativeStackNavigator();
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name="Home" getComponent={createHomeScreen} />
+      <Stack.Screen name="Details" getComponent={createDetailScreen} />
+    </Stack.Navigator>
+  );
+}
+```
+
+**优势**：
+- 真正的懒加载：组件只在导航到该路由时才创建
+- 减少初始内存占用
+- 符合 React Navigation 最佳实践
+
+#### 方式二：使用路由注册系统
+
+```typescript
+import { registerModuleRoute, getModuleRoute } from './src/multi-bundle/routeRegistry';
+
+// 注册路由
+registerModuleRoute('home', 'Home');
+registerModuleRoute('details', 'Details');
+
+// 获取路由组件
+const HomeScreen = getModuleRoute('home', 'Home');
+```
+
+### 3. 配置 Metro
+
+确保 `metro.config.js` 已正确配置。系统会自动从环境变量读取配置，或使用默认值。
+
+如果需要自定义配置，可以通过环境变量传递：
+
+```bash
+RN_MULTI_BUNDLE_MODULE_PATHS='["src/modules/**"]' \
+RN_MULTI_BUNDLE_SHARED_DEPS='["src/multi-bundle/**","src/navigation/**"]' \
+npx react-native start
+```
+
+## 配置选项
+
+### MultiBundleConfig
+
+| 选项 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `modulePaths` | `string[]` | 否 | `['src/modules/**']` | 模块路径规则（glob 模式） |
+| `sharedDependencies` | `string[]` | 否 | `['src/multi-bundle/**', 'src/navigation/**']` | 共享依赖路径 |
+| `manifestProvider` | `ManifestProvider` | 否 | 使用 `LocalBundleManager` | Manifest 获取方式 |
+| `moduleLoader` | `ModuleLoader` | 否 | 自动选择 | 自定义 ModuleLoader |
+| `preloadModules` | `string[]` | 否 | `[]` | 预加载模块列表 |
+| `devServer` | `DevServerConfig` | 否 | 根据平台自动选择 | 开发服务器配置 |
+| `onError` | `(error: Error) => void` | 否 | - | 错误处理回调 |
+
+### ManifestProvider
+
+支持两种方式提供 manifest：
+
+1. **函数方式**（推荐）：
+```typescript
+manifestProvider: async () => {
+  // 自定义获取逻辑
+  return await fetchManifestFromCustomSource();
+}
+```
+
+2. **URL 方式**：
+```typescript
+manifestProvider: 'http://localhost:8081/bundle-manifest.json'
+```
+
+### DevServerConfig
+
+```typescript
+{
+  host: string;        // 服务器地址
+  port: number;        // 端口号
+  protocol?: 'http' | 'https';  // 协议（默认 'http'）
+}
+```
+
+## 模块开发规范
+
+### 模块入口文件
+
+每个模块需要在入口文件中注册：
+
+```typescript
+// src/modules/Home/index.ts
+import HomeScreen from './HomeScreen';
+
+const exports = {
+  routes: {
+    Home: HomeScreen,
+  },
+  components: {
+    HomeScreen,
+  },
+};
+
+// 注册模块
+const ModuleRegistry = globalThis.__ModuleRegistry;
+if (ModuleRegistry) {
+  ModuleRegistry.registerModule('home', exports);
+}
+
+export default exports;
+```
+
+### 模块导出结构
+
+建议使用统一的导出结构：
+
+```typescript
+{
+  routes: {
+    [routeKey]: React.ComponentType;
+  };
+  components: {
+    [componentName]: React.ComponentType;
+  };
+  services?: {
+    [serviceName]: any;
+  };
+  constants?: {
+    [constantName]: any;
+  };
+}
+```
+
+## API 参考
+
+### initMultiBundle
+
+初始化多 Bundle 系统。
+
+```typescript
+function initMultiBundle(config?: MultiBundleConfig): Promise<InitResult>
+```
+
+**返回值**：
+```typescript
+{
+  success: boolean;
+  error?: Error;
+  manifest?: BundleManifest;
+}
+```
+
+### createModuleRouteLoader
+
+创建模块路由加载器函数（推荐，用于 React Navigation `getComponent` API）。
+
+```typescript
+function createModuleRouteLoader(
+  moduleId: string,
+  routeKey: string
+): () => React.ComponentType<any>
+```
+
+**使用示例**：
+```typescript
+const createHomeScreen = createModuleRouteLoader('home', 'Home');
+
+// 在 React Navigation 中使用
+<Stack.Screen name="Home" getComponent={createHomeScreen} />
+```
+
+### createModuleLoader
+
+创建通用的模块加载器函数（用于自定义组件提取逻辑）。
+
+```typescript
+function createModuleLoader(
+  moduleId: string,
+  pickComponent: (exports: any) => React.ComponentType<any>,
+  options?: CreateModuleLoaderOptions
+): () => React.ComponentType<any>
+```
+
+**使用示例**：
+```typescript
+const createCustomScreen = createModuleLoader(
+  'my-module',
+  (exports) => exports.components.MyComponent
+);
+```
+
+
+### registerModuleRoute
+
+注册模块路由。
+
+```typescript
+function registerModuleRoute(
+  moduleId: string,
+  routeKey: string,
+  component?: React.ComponentType<any>
+): void
+```
+
+### getModuleRoute
+
+获取已注册的路由组件。
+
+```typescript
+function getModuleRoute(
+  moduleId: string,
+  routeKey: string
+): React.ComponentType<any> | undefined
+```
+
+### preloadModule
+
+预加载模块。
+
+```typescript
+function preloadModule(moduleId: string): Promise<void>
+```
+
+## 最佳实践
+
+1. **统一初始化**：在应用入口统一调用 `initMultiBundle`，避免分散的初始化逻辑。
+
+2. **配置集中管理**：将多 Bundle 配置集中管理，便于维护和修改。
+
+3. **错误处理**：始终提供 `onError` 回调，妥善处理初始化失败的情况。
+
+4. **预加载策略**：只预加载关键模块，避免影响启动性能。
+
+5. **模块设计**：保持模块独立性，避免循环依赖。
+
+## 故障排查
+
+### 模块加载失败
+
+- 检查 manifest 是否正确配置
+- 确认模块 ID 与 manifest 中的 ID 一致
+- 查看控制台错误信息
+
+### Metro 构建问题
+
+- 确认 `metro.config.js` 配置正确
+- 检查模块路径规则是否匹配实际路径
+- 清除 Metro 缓存：`npx react-native start --reset-cache`
+
+### 开发环境问题
+
+- 确认开发服务器正在运行
+- 检查 `devServer` 配置是否正确
+- 验证 manifest URL 是否可访问
+
+## 更多信息
+
+- [模块 Bundle 开发规范](../docs/模块%20Bundle%20开发规范.md)
+- [使用指南](../docs/使用指南.md)
+- [多 Bundle 架构设计](../docs/React%20Native%20多%20bundle%20技术方案.md)
+