generator-mico-cli 0.2.2 → 0.2.4

package/generators/micro-react/templates/apps/layout/docs/feature-/345/276/256/345/211/215/347/253/257/346/250/241/345/274/217.md

@@ -1,6 +1,7 @@
 # 微前端模式
 
 > 创建时间：2025-12-26
+> 更新时间：2025-01-25（加载健壮性增强）
 
 ## 功能概述
 
@@ -27,14 +28,16 @@
 
 ### 核心文件
 
-| 文件路径                                   | 说明                       |
-| ------------------------------------------ | -------------------------- |
-| `src/components/MicroAppLoader/index.tsx`  | qiankun 微应用加载器组件   |
-| `src/components/MicroAppLoader/index.less` | 加载器样式                 |
-| `src/common/menu/parser.ts`                | 菜单解析，包含加载类型判断 |
-| `src/common/menu/types.ts`                 | 类型定义                   |
-| `src/layouts/index.tsx`                    | 主布局，集成微应用渲染     |
-| `config/config.ts`                         | qiankun master 配置        |
+| 文件路径                                            | 说明                             |
+| --------------------------------------------------- | -------------------------------- |
+| `src/components/MicroAppLoader/index.tsx`           | qiankun 微应用加载器组件         |
+| `src/components/MicroAppLoader/container-manager.ts`| 容器生命周期管理、会话 ID 机制   |
+| `src/components/MicroAppLoader/index.less`          | 加载器样式                       |
+| `src/common/menu/parser.ts`                         | 菜单解析，包含加载类型判断       |
+| `src/common/menu/types.ts`                          | 类型定义                         |
+| `src/layouts/index.tsx`                             | 主布局，集成微应用渲染           |
+| `src/app.tsx`                                       | qiankun 全局错误处理             |
+| `config/config.ts`                                  | qiankun master 配置              |
 
 ## API / 组件接口
 
@@ -430,3 +433,82 @@ export default function HomePage() {
 有 htmlUrl 或 jsUrls  →  microapp (使用 qiankun 加载)
 无 htmlUrl 且无 jsUrls →  internal (使用 Outlet 渲染)
 ```
+
+## 加载健壮性机制
+
+> 更新于 2025-01-25
+
+### 解决的问题
+
+| 原问题 | 风险 | 修复方案 |
+|--------|------|----------|
+| 无全局错误处理，子应用异常可能导致页面崩溃 | 高 | 添加 `addGlobalUncaughtErrorHandler` |
+| unmount 使用 rAF 时序不可靠 | 高 | 使用 `queueMicrotask` |
+| 同名应用并发加载可能冲突 | 高 | 会话 ID 锁 + `waitForUnmount` |
+| unmount 可能永久卡死 | 中 | 10 秒超时机制 |
+| 加载期间 Props 变化被跳过 | 中 | 加载完成后重新同步 Props |
+
+### 全局错误处理
+
+在 `src/app.tsx` 中注册 qiankun 全局错误处理器，捕获子应用运行时未捕获的异常：
+
+```typescript
+import { addGlobalUncaughtErrorHandler } from 'qiankun';
+
+addGlobalUncaughtErrorHandler((event: Event | string) => {
+  // 捕获子应用 JS 运行时错误
+  // 捕获子应用生命周期钩子异常
+  // 捕获资源加载失败
+  console.error('[qiankun] Global uncaught error:', event);
+});
+```
+
+### container-manager API
+
+容器管理器提供会话 ID 机制防止并发加载冲突：
+
+```typescript
+/** 开始加载会话，返回唯一会话 ID */
+function startLoadSession(appName: string): number;
+
+/** 检查会话是否仍然有效（被新加载覆盖时返回 false） */
+function isLoadSessionValid(appName: string, sessionId: number): boolean;
+
+/** 标记加载完成 */
+function markLoadComplete(appName: string, sessionId: number): boolean;
+
+/** 等待当前卸载操作完成（如果有） */
+async function waitForUnmount(appName: string): Promise<void>;
+
+/** 获取当前加载状态 */
+function getLoadingStatus(appName: string): 'idle' | 'loading' | 'mounted' | 'unmounting';
+```
+
+### 快速切换时序
+
+```
+场景：A → B → A 快速切换
+
+A1 开始加载 (sessionId=1)
+  ↓
+切换到 B，A1 cleanup 在 queueMicrotask 中执行
+  ↓
+切换回 A，A2 开始加载 (sessionId=2)
+  ↓
+A2 调用 waitForUnmount()，等待 A1 完全卸载
+  ↓
+A1 卸载完成（带 10 秒超时保护）
+  ↓
+A2 继续加载，每个异步步骤检查 isLoadSessionValid(sessionId)
+  ↓
+加载完成后立即同步最新 Props（locale/timezone 等）
+```
+
+### 设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| 卸载时机 | `queueMicrotask` | 在当前事件循环末尾执行，比 `requestAnimationFrame` 更快更可靠 |
+| 并发控制 | 会话 ID 机制 | 简单高效，无需复杂的锁机制 |
+| 超时时间 | 10 秒 | 平衡等待时间与异常检测速度 |
+| Props 同步 | 加载后立即同步 | 确保加载期间的变化不丢失 |

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -13,6 +13,7 @@ import { extractRoutes, getWindowMenus } from './common/menu';
 import { ensureSsoSession } from './common/request/sso';
 import {
   clearMicroAppProps,
+  getAppNameFromEntry,
   type IMicroAppProps,
   setMicroAppProps,
 } from './common/micro';
@@ -55,11 +56,14 @@ if (typeof window !== 'undefined') {
     });
 
     // 检查是否是子应用加载失败（资源 404 等）
+    // 只匹配明确的关键词，避免误判业务错误（如 "upload failed"）
     const isLoadError =
       errorMessage.includes('Failed to fetch') ||
       errorMessage.includes('Loading chunk') ||
-      errorMessage.includes('load') ||
-      errorMessage.includes('Script error');
+      errorMessage.includes('ChunkLoadError') ||
+      errorMessage.includes('Script error') ||
+      errorMessage.includes('Loading CSS chunk') ||
+      (event instanceof ErrorEvent && event.type === 'error');
 
     if (isLoadError) {
       console.error(
@@ -112,10 +116,11 @@ const prefetchMicroApps = () => {
     const routes = extractRoutes(menus);
 
     // 筛选出所有微应用路由
+    // 使用 getAppNameFromEntry 生成 name，与 loadMicroApp 保持一致，确保预加载缓存命中
     const microApps = routes
       .filter((route) => route.loadType === 'microapp' && route.entry)
       .map((route) => ({
-        name: route.path,
+        name: getAppNameFromEntry(route.entry!),
         entry: route.entry!,
       }));
 

package/generators/micro-react/templates/apps/layout/src/common/micro/index.ts

@@ -32,6 +32,40 @@ export type {
   MicroAppErrorSource,
 } from './types';
 
+
+// ============================================
+// 微应用名称生成
+// ============================================
+
+/**
+ * 从 entry URL 中提取微应用标识
+ * 同一个 entry 的所有路由使用相同的标识，避免频繁卸载/重载微应用
+ *
+ * 注意：使用完整的 origin + pathname 作为标识，避免同一 host 上多个子应用冲突
+ * 例如：http://localhost:8010/app1/ 和 http://localhost:8010/app2/ 会有不同的标识
+ *
+ * @param entry 微应用入口 URL
+ * @returns 微应用标识（字母数字和连字符组成）
+ */
+export const getAppNameFromEntry = (entry: string): string => {
+  try {
+    const url = new URL(entry, window.location.href);
+    // 使用 origin + pathname 作为标识，确保不同路径的子应用有不同标识
+    // 如 "localhost-8010" 或 "localhost-8010-app1"
+    const identifier = url.host + url.pathname;
+    return identifier
+      .replace(/[^a-zA-Z0-9]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  } catch {
+    // fallback：使用 entry 的 hash
+    return entry
+      .replace(/[^a-zA-Z0-9]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+};
+
 // ============================================
 // 环境检测
 // ============================================

package/generators/micro-react/templates/apps/layout/src/common/route-guard.ts

@@ -0,0 +1,316 @@
+/**
+ * 路由守卫 - 自动检测用户意图
+ *
+ * 核心问题：
+ * 当用户快速切换微应用（A→B→A）时，子应用 B 的代码可能在后台继续执行，
+ * 并调用 history.pushState('/route-b') 试图修改路由，导致用户界面混乱。
+ *
+ * 解决方案：
+ * 自动检测"用户触发的导航"和"程序触发的导航"：
+ * - 用户触发：在 click/keydown 等交互事件的同步调用栈中
+ * - 程序触发：在异步回调、定时器、微应用生命周期中
+ *
+ * 对于程序触发的导航，如果目标路径与当前用户意图不匹配，则拦截。
+ *
+ * 使用方式：
+ * 1. 在应用入口处导入此文件（import '@/common/route-guard'）
+ * 2. 业务代码无需任何改动，正常使用 history.push、react-router、<a> 标签等
+ */
+
+import { microAppLogger } from './logger';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+interface UserIntent {
+  /** 用户意图的目标路径 */
+  path: string;
+  /** 意图设置时间 */
+  timestamp: number;
+  /** 是否来自用户交互（点击/键盘） */
+  fromInteraction: boolean;
+}
+
+// ============================================================================
+// 配置常量
+// ============================================================================
+
+/** 用户意图有效期（毫秒） */
+const INTENT_TTL = 5000;
+
+/** 交互事件结束后的保护窗口期（毫秒）
+ * 用于处理 click → setTimeout(() => navigate(), 0) 这种微延迟情况
+ */
+const INTERACTION_GRACE_PERIOD = 100;
+
+// ============================================================================
+// 状态
+// ============================================================================
+
+/** 当前用户意图 */
+let currentIntent: UserIntent | null = null;
+
+/** 是否正在用户交互中（click/keydown 事件处理期间） */
+let isInUserInteraction = false;
+
+/** 交互结束时间（用于 grace period） */
+let interactionEndTime = 0;
+
+/** 调试模式 */
+const DEBUG = true;
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+function log(...args: unknown[]): void {
+  if (DEBUG) {
+    console.log('🛡️[RouteGuard]', ...args);
+  }
+}
+
+function warn(...args: unknown[]): void {
+  console.warn('🛡️[RouteGuard]', ...args);
+}
+
+/**
+ * 获取路径的基础部分（第一级路径）
+ * /lineup/list → /lineup
+ * /permission/role → /permission
+ */
+function getBasePath(path: string): string {
+  const normalized = path.startsWith('/') ? path : '/' + path;
+  const segments = normalized.split('/').filter(Boolean);
+  return '/' + (segments[0] || '');
+}
+
+/**
+ * 解析 URL 获取 pathname
+ */
+function parsePathname(url: string | URL | null | undefined): string | null {
+  if (!url) return null;
+
+  if (typeof url === 'string') {
+    // 相对路径
+    if (url.startsWith('/')) return url.split('?')[0].split('#')[0];
+    // 绝对 URL
+    try {
+      return new URL(url, window.location.origin).pathname;
+    } catch {
+      return null;
+    }
+  }
+
+  return url.pathname;
+}
+
+/**
+ * 检查意图是否有效
+ */
+function isIntentValid(): boolean {
+  if (!currentIntent) return false;
+  return Date.now() - currentIntent.timestamp < INTENT_TTL;
+}
+
+/**
+ * 是否在用户交互上下文中
+ * 包括：正在交互 或 刚刚结束交互（grace period 内）
+ */
+function isInInteractionContext(): boolean {
+  if (isInUserInteraction) return true;
+  if (Date.now() - interactionEndTime < INTERACTION_GRACE_PERIOD) return true;
+  return false;
+}
+
+// ============================================================================
+// 公开 API
+// ============================================================================
+
+/**
+ * 设置用户意图（供 MicroAppManager 内部调用）
+ * 业务代码不需要调用此函数，路由守卫会自动检测用户交互
+ */
+export function setUserIntent(path: string): void {
+  log('设置意图:', path);
+  currentIntent = {
+    path,
+    timestamp: Date.now(),
+    fromInteraction: false,
+  };
+}
+
+/**
+ * 刷新意图时间戳（供 MicroAppManager 内部调用）
+ * 在长时间操作（如加载微应用）过程中保持意图有效
+ */
+export function refreshUserIntent(): void {
+  if (currentIntent) {
+    currentIntent.timestamp = Date.now();
+    log('刷新意图:', currentIntent.path);
+  }
+}
+
+/**
+ * 清除用户意图
+ */
+export function clearUserIntent(): void {
+  log('清除意图');
+  currentIntent = null;
+}
+
+/**
+ * 获取当前意图信息（调试用）
+ */
+export function getIntentDebugInfo(): object {
+  return {
+    intent: currentIntent,
+    isValid: isIntentValid(),
+    isInInteraction: isInUserInteraction,
+    interactionEndTime,
+    isInContext: isInInteractionContext(),
+  };
+}
+
+// ============================================================================
+// 路由守卫核心逻辑
+// ============================================================================
+
+/**
+ * 判断是否应该拦截此次导航
+ */
+function shouldIntercept(targetPath: string): boolean {
+  // 1. 在用户交互上下文中，允许导航并更新意图
+  if (isInInteractionContext()) {
+    log('用户交互触发导航:', targetPath);
+    currentIntent = {
+      path: targetPath,
+      timestamp: Date.now(),
+      fromInteraction: true,
+    };
+    return false;
+  }
+
+  // 2. 没有有效意图，允许导航
+  if (!isIntentValid()) {
+    log('无有效意图，允许导航:', targetPath);
+    return false;
+  }
+
+  // 3. 有有效意图，检查目标路径是否匹配
+  const targetBase = getBasePath(targetPath);
+  const intentBase = getBasePath(currentIntent!.path);
+
+  if (targetBase === intentBase) {
+    log('目标匹配意图，允许导航:', { targetPath, intentPath: currentIntent!.path });
+    return false;
+  }
+
+  // 4. 不匹配，拦截
+  warn('❌ 拦截程序触发的导航:', {
+    targetPath,
+    targetBase,
+    intentPath: currentIntent!.path,
+    intentBase,
+    intentAge: Date.now() - currentIntent!.timestamp + 'ms',
+  });
+  return true;
+}
+
+// ============================================================================
+// 初始化
+// ============================================================================
+
+if (typeof window !== 'undefined') {
+  // 保存原始方法
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+
+  // 拦截 pushState
+  window.history.pushState = function (
+    state: unknown,
+    unused: string,
+    url?: string | URL | null,
+  ) {
+    const targetPath = parsePathname(url);
+    log('pushState 被调用:', { url, targetPath, isInInteraction: isInUserInteraction });
+
+    if (targetPath && shouldIntercept(targetPath)) {
+      // 拦截，不执行导航
+      return;
+    }
+
+    return originalPushState(state, unused, url);
+  };
+
+  // 拦截 replaceState
+  window.history.replaceState = function (
+    state: unknown,
+    unused: string,
+    url?: string | URL | null,
+  ) {
+    const targetPath = parsePathname(url);
+    log('replaceState 被调用:', { url, targetPath, isInInteraction: isInUserInteraction });
+
+    if (targetPath && shouldIntercept(targetPath)) {
+      // 拦截，不执行导航
+      return;
+    }
+
+    return originalReplaceState(state, unused, url);
+  };
+
+  // 监听用户交互事件
+  // 使用 capture 阶段确保在任何其他处理器之前执行
+  const markInteractionStart = (event: Event) => {
+    // 只处理可能触发导航的交互
+    if (event.type === 'click' || event.type === 'keydown') {
+      const keyEvent = event as KeyboardEvent;
+      // 只有 Enter 键可能触发导航
+      if (event.type === 'keydown' && keyEvent.key !== 'Enter') {
+        return;
+      }
+
+      log('用户交互开始:', event.type);
+      isInUserInteraction = true;
+
+      // 在当前事件循环结束后重置标记
+      // 使用 setTimeout 0 确保同步代码执行完毕
+      setTimeout(() => {
+        isInUserInteraction = false;
+        interactionEndTime = Date.now();
+        log('用户交互结束');
+      }, 0);
+    }
+  };
+
+  document.addEventListener('click', markInteractionStart, { capture: true });
+  document.addEventListener('keydown', markInteractionStart, { capture: true });
+
+  // 监听 popstate 事件（浏览器前进/后退）
+  window.addEventListener('popstate', () => {
+    // 浏览器前进后退是用户行为，更新意图
+    const newPath = window.location.pathname;
+    log('popstate 事件:', newPath);
+    currentIntent = {
+      path: newPath,
+      timestamp: Date.now(),
+      fromInteraction: true,
+    };
+  });
+
+  microAppLogger.log('RouteGuard initialized');
+
+  // 暴露调试接口
+  (window as unknown as Record<string, unknown>).__ROUTE_GUARD__ = {
+    getDebugInfo: getIntentDebugInfo,
+    setIntent: setUserIntent,
+    clearIntent: clearUserIntent,
+  };
+}
+
+export default {
+  setUserIntent,
+  clearUserIntent,
+  getIntentDebugInfo,
+};