generator-mico-cli 0.1.24 → 0.1.26

package/generators/micro-react/templates/apps/layout/docs/arch-/350/257/267/346/261/202/346/250/241/345/235/227.md

@@ -0,0 +1,133 @@
+# 请求模块架构
+
+## 功能概述
+
+HTTP 请求层模块化架构，将请求逻辑拆分为 6 个职责单一的模块，遵循 SRP 原则。
+
+## 模块结构
+
+```
+src/common/request/
+├── index.ts          # 模块入口，导出统一 API
+├── types.ts          # 类型定义
+├── config.ts         # 客户端配置管理
+├── interceptors.ts   # 拦截器管理
+├── url-resolver.ts   # URL 解析工具
+├── token-refresh.ts  # Token 刷新逻辑
+└── sso.ts            # SSO 认证逻辑
+```
+
+## 模块职责
+
+| 模块               | 职责                                                  |
+| ------------------ | ----------------------------------------------------- |
+| `types.ts`         | 定义 `UnifiedRequestOptions`、`RequestContext` 等接口 |
+| `config.ts`        | 管理 API baseUrl、代理前缀、认证端点配置              |
+| `interceptors.ts`  | 请求/响应拦截器，Header 构建，401 处理                |
+| `url-resolver.ts`  | URL 拼接、代理路径处理、参数移除                      |
+| `token-refresh.ts` | Token 过期刷新，请求队列管理                          |
+| `sso.ts`           | SSO ticket 交换，认证重定向                           |
+
+## API
+
+```typescript
+import { request } from '@/common/request';
+
+// 标准请求（开发环境使用相对路径）
+const data = await request<UserInfo>('/api/user');
+```
+
+## URL 灵活配置
+
+`request` 函数支持灵活的 URL 配置选项，满足不同场景需求。
+
+### 配置选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `skipProxy` | `boolean` | `false` | 跳过 proxySuffix 拼接 |
+| `baseURL` | `string` | 全局配置 | 自定义 baseURL，覆盖全局配置 |
+| `rawUrl` | `boolean` | `false` | 使用原始 URL，跳过所有 URL 处理 |
+
+### 配置优先级
+
+```
+rawUrl: true  →  直接返回原始 url
+     ↓
+绝对 URL      →  直接返回
+     ↓
+开发环境       →  返回相对路径
+     ↓
+生产环境       →  baseURL + (skipProxy ? '' : proxySuffix) + url
+```
+
+### 使用示例
+
+```typescript
+import { request } from '@/common/request';
+
+// 1. 默认行为：baseURL + proxySuffix + url
+request('/api/users');
+// 生产环境 => https://api.example.com/proxy-suffix/api/users
+
+// 2. 跳过 proxySuffix（直接请求后端，不经过代理）
+request('/api/users', { skipProxy: true });
+// 生产环境 => https://api.example.com/api/users
+
+// 3. 自定义 baseURL（请求其他服务）
+request('/api/data', { baseURL: 'https://other-service.com' });
+// 生产环境 => https://other-service.com/proxy-suffix/api/data
+
+// 4. 自定义 baseURL + 跳过 proxy（请求第三方 API）
+request('/api/data', {
+  baseURL: 'https://third-party.com',
+  skipProxy: true
+});
+// 生产环境 => https://third-party.com/api/data
+
+// 5. 完全使用原始 URL（微应用场景，URL 已处理好）
+request('/custom/path', { rawUrl: true });
+// 任何环境 => /custom/path（原样返回）
+
+// 6. 覆盖默认 proxySuffix
+request('/api/users', { proxySuffix: '/other-proxy' });
+// 生产环境 => https://api.example.com/other-proxy/api/users
+```
+
+### 典型场景
+
+| 场景 | 配置 |
+|------|------|
+| 请求主后端 API | 默认，无需额外配置 |
+| 绕过网关直连后端 | `{ skipProxy: true }` |
+| 请求其他微服务 | `{ baseURL: 'https://xxx' }` |
+| 请求第三方 API | `{ baseURL: 'https://xxx', skipProxy: true }` |
+| 微应用已处理 URL | `{ rawUrl: true }` |
+
+## 错误处理
+
+错误配置在 `src/requestErrorConfig.ts`，使用类型守卫区分错误类型：
+
+```typescript
+// 类型守卫
+const isBizError = (error: unknown): error is BizError => {
+  return error instanceof Error && error.name === 'BizError' && 'info' in error;
+};
+
+const isAxiosLikeError = (error: unknown): error is AxiosLikeError => {
+  return error instanceof Error && ('response' in error || 'request' in error);
+};
+```
+
+## 相关文件
+
+| 文件                                 | 说明           |
+| ------------------------------------ | -------------- |
+| `src/requestErrorConfig.ts`          | 错误处理配置   |
+| `src/common/auth/cs-auth-manager.ts` | Token 存储管理 |
+
+## 注意事项
+
+- 外部导入路径不变：`@/common/request`
+- 开发环境使用相对路径，生产环境自动拼接 baseUrl
+- 401 响应自动触发 Token 刷新或 SSO 重定向

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

@@ -7,6 +7,12 @@ export type UnifiedRequestOptions = {
   proxySuffix?: string;
   useCache?: boolean;
   validateCache?: (url: string, options: UnifiedRequestOptions) => boolean;
+  /** 跳过 proxySuffix 拼接 */
+  skipProxy?: boolean;
+  /** 自定义 baseURL，覆盖全局配置 */
+  baseURL?: string;
+  /** 使用原始 URL，跳过所有 URL 处理 */
+  rawUrl?: boolean;
   [key: string]: unknown;
 };
 

package/generators/micro-react/templates/apps/layout/src/common/request/url-resolver.ts

@@ -43,22 +43,56 @@ export const joinProxyAndPath = (proxySuffix: string, path: string): string => {
   return `${normalizedProxy}${normalizedPath}`;
 };
 
+/**
+ * 判断是否为绝对 URL
+ */
+const isAbsoluteUrl = (url: string): boolean => {
+  return (
+    url.startsWith('http://') ||
+    url.startsWith('https://') ||
+    url.startsWith('//')
+  );
+};
+
 /**
  * 解析最终请求 URL
+ *
+ * 配置优先级：
+ * 1. rawUrl: true → 直接返回原始 url
+ * 2. 绝对 URL → 直接返回
+ * 3. 开发环境 → 返回相对路径
+ * 4. 生产环境 → baseURL + (skipProxy ? '' : proxySuffix) + url
  */
 export const resolveRequestUrl = (
   url: string,
   options?: UnifiedRequestOptions,
   isAlwaysRemote = false,
 ): string => {
-  const useRelative = process.env.NODE_ENV !== 'production' && !isAlwaysRemote;
-  const proxySuffix = getProxySuffix(options?.proxySuffix);
+  // rawUrl: 完全透传，不做任何处理
+  if (options?.rawUrl) {
+    return url;
+  }
+
+  // 绝对 URL 直接返回
+  if (isAbsoluteUrl(url)) {
+    return url;
+  }
 
+  const useRelative = process.env.NODE_ENV !== 'production' && !isAlwaysRemote;
   if (useRelative) {
     return url;
   }
 
-  return joinBaseUrl(resolveApiBaseUrl(), joinProxyAndPath(proxySuffix, url));
+  // 确定 baseURL
+  const baseURL = options?.baseURL ?? resolveApiBaseUrl();
+
+  // 确定是否拼接 proxySuffix
+  const shouldUseProxy = !options?.skipProxy;
+  const proxySuffix = shouldUseProxy ? getProxySuffix(options?.proxySuffix) : '';
+
+  // 拼接最终 URL
+  const pathWithProxy = proxySuffix ? joinProxyAndPath(proxySuffix, url) : url;
+  return joinBaseUrl(baseURL, pathWithProxy);
 };
 
 /**

package/generators/micro-react/templates/apps/layout/src/components/MicroAppLoader/index.tsx

@@ -1,5 +1,6 @@
 import { getAuthInfo } from '@/common/auth/cs-auth-manager';
 import { EEnv, getEnv } from '@/common/env';
+import { request } from '@/common/request';
 import { Spin } from '@arco-design/web-react';
 import { loadMicroApp } from 'qiankun';
 import React, { useEffect, useMemo, useRef, useState } from 'react';
@@ -68,6 +69,8 @@ const MicroAppLoader: React.FC<MicroAppLoaderProps> = ({
       nickname: authInfo.nickname,
       // 传递当前路由路径，让子应用进行内部路由切换
       routePath,
+      // 传递主应用的 request 实例，子应用可直接使用
+      request,
     };
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generator-mico-cli",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Yeoman generator for Mico CLI projects",
   "keywords": [
     "yeoman-generator",