@farris/cli 2.3.1 → 2.3.3

package/templates/mobile/farris.config.mjs

@@ -1,6 +1,10 @@
 import { fileURLToPath, URL } from 'node:url';
 
 export default {
+  // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
+  base: './',
+  routerMode: 'hash',
+  // iife: IBP 微前端单文件产物（默认）；如需普通 ESM 站点产物，执行 pnpm build:es
   format: "<%= format %>",
   // 输出目录  App模式默认值 './dist' Lib模式 './lib'
   // outDir: fileURLToPath(new URL('./dist', import.meta.url)),
@@ -19,6 +23,12 @@ export default {
   ],
   // 插件 默认值 [vue(), vueJsx()] 不要重复添加
   // plugins: [],
+  // 开发期 mock 默认开启：接口数据来自工程内 mock/ 目录，未命中的请求按下方 proxy 转发
+  // mock: true,
+  // 开发代理：未命中 mock 的接口转发到真实后端；联调时执行 pnpm dev --no-mock 可整体关闭 mock
+  // proxy: {
+  //   '/api': { target: 'http://localhost:8080', changeOrigin: true }
+  // },
   // viteConfig 配置项
   viteConfig: {}
 };

package/templates/mobile/mock/README.md

@@ -0,0 +1,34 @@
+# mock 目录
+
+开发期接口数据。一个领域一个文件，命名 `*.mock.ts`，默认导出路由数组：
+
+```ts
+export default [
+  {
+    url: '/api/v1/users', // 必须与代码中的请求路径逐字一致
+    method: 'GET', // 默认 GET
+    timeout: 300, // 可选 模拟延迟毫秒
+    status: 200, // 可选 响应状态码
+    response: ({ query, params, body }) => ({
+      data: [],
+      total: 0
+    })
+  }
+];
+```
+
+规则：
+
+- url 必须与代码中的请求路径逐字一致，见 `src/api/` 下的接口模块。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`；查询参数不写进 url，在 response 的 `query` 里读取。
+- mock 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。
+- 同一 url 不允许在多个 mock 文件中重复定义，重复时开发服务启动即报错。
+- mock 只用于开发期：不进构建产物，也不要在组件里散落假数据。
+
+行为：
+
+- 命中 mock → 返回 mock 数据。
+- 未命中 → 按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径 → 返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。

package/templates/mobile/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "farris-cli dev",
     "build": "farris-cli build -ep",
+    "build:es": "farris-cli build --format es --outDir dist-es",
     "preview": "farris-cli preview",
     "test": "vitest run",
     "test:watch": "vitest",

package/templates/mobile/src/main.ts

@@ -1,13 +1,47 @@
-import { createApp } from 'vue';
+import { createApp, type App as VueApp } from 'vue';
 import FarrisVue from '@farris/mobile-ui-vue';
 import '@farris/mobile-ui-vue/style.css';
 import App from './App.vue';
 import router from './router';<%= styleImport %>
 import { localResources } from './locales';
 
-const app = createApp(App);
+let app: VueApp | null = null;
 
-app.use(FarrisVue, { basePath: '', locale: 'zh-CN', localResources });
-app.use(router);
+/** 挂载应用（微前端宿主会调用 window.mount） */
+function mount(): void {
+  if (app) {
+    return;
+  }
+  app = createApp(App);
+  app.use(FarrisVue, { basePath: '', locale: 'zh-CN', localResources });
+  app.use(router);
+  app.mount('#app');
 
-app.mount('#app');
+  // 微前端环境：按平台下发的 initialPath 定位菜单配置的页面（fullPath）
+  // hash 路由必须保留这段兜底；history 路由下平台 defaultPage 已能直接命中，这里是幂等兜底
+  if (window.__MICRO_APP_ENVIRONMENT__) {
+    const rawPath = window.microApp?.getData?.()?.initialPath;
+    if (typeof rawPath === 'string' && rawPath !== '') {
+      // 平台下发的 initialPath 通常不带前导斜杠（如 'form'），这里统一归一化
+      const initialPath = rawPath.startsWith('/') ? rawPath : '/' + rawPath;
+      if (initialPath !== '/') {
+        router.isReady().then(() => router.replace(initialPath)).catch(() => undefined);
+      }
+    }
+  }
+}
+
+/** 卸载应用（微前端宿主会调用 window.unmount） */
+function unmount(): void {
+  app?.unmount();
+  app = null;
+}
+
+// 微前端（micro-app）生命周期契约：必须暴露到 window
+window.mount = mount;
+window.unmount = unmount;
+
+// 独立运行（浏览器直接访问 / iframe 嵌入）时自动挂载
+if (!window.__MICRO_APP_ENVIRONMENT__) {
+  mount();
+}

package/templates/mobile/src/micro-app.d.ts

@@ -0,0 +1,20 @@
+export {};
+
+declare global {
+  interface Window {
+    /** micro-app 子应用环境标记（由宿主注入） */
+    __MICRO_APP_ENVIRONMENT__?: boolean;
+    /** 宿主注入的 micro-app API */
+    microApp?: {
+      addGlobalDataListener?: (callback: (data: any) => void, immediately?: boolean) => void;
+      setGlobalData?: (data: Record<string, any>) => void;
+      getData?: () => Record<string, any> | null;
+      router?: {
+        getBaseAppRouter?: () => any;
+      };
+    };
+    /** 微前端生命周期：宿主会调用这两个方法 */
+    mount?: () => void;
+    unmount?: () => void;
+  }
+}

package/templates/mobile/src/router/index.ts

@@ -1,4 +1,4 @@
-import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';
+import { createRouter, createWebHashHistory, type RouteRecordRaw } from 'vue-router';
 
 // 生成器（farris-cli generate view --with-route）依赖下面的 routes 数组赋值形式；
 // 改动结构会导致路由无法自动注册。
@@ -16,7 +16,8 @@ export const routes: RouteRecordRaw[] = [
 ];
 
 const router = createRouter({
-  history: createWebHistory(import.meta.env.BASE_URL),
+  // hash 路由：微前端（IBP）下子应用 location 由宿主接管，hash 模式最稳妥
+  history: createWebHashHistory(),
   routes
 });
 

package/templates/web/.gitignore.tpl

@@ -11,6 +11,7 @@ node_modules
 package-lock.json
 .DS_Store
 dist
+dist-es
 dist-ssr
 coverage
 *.local

package/templates/web/farris.config.mjs

@@ -1,6 +1,10 @@
 import { fileURLToPath, URL } from 'node:url';
 
 export default {
+  // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
+  base: './',
+  routerMode: 'hash',
+  // iife: IBP 微前端单文件产物（默认）；如需普通 ESM 站点产物，执行 pnpm build:es
   format: "<%= format %>",
   // 输出目录  App模式默认值 './dist' Lib模式 './lib'
   // outDir: fileURLToPath(new URL('./dist', import.meta.url)),
@@ -19,6 +23,12 @@ export default {
   ],
   // 插件 默认值 [vue(), vueJsx()] 不要重复添加
   // plugins: [],
+  // 开发期 mock 默认开启：接口数据来自工程内 mock/ 目录，未命中的请求按下方 proxy 转发
+  // mock: true,
+  // 开发代理：未命中 mock 的接口转发到真实后端；联调时执行 pnpm dev --no-mock 可整体关闭 mock
+  // proxy: {
+  //   '/api': { target: 'http://localhost:8080', changeOrigin: true }
+  // },
   // viteConfig 配置项
   viteConfig: {}
 };

package/templates/web/mock/README.md

@@ -0,0 +1,34 @@
+# mock 目录
+
+开发期接口数据。一个领域一个文件，命名 `*.mock.ts`，默认导出路由数组：
+
+```ts
+export default [
+  {
+    url: '/api/v1/users', // 必须与代码中的请求路径逐字一致
+    method: 'GET', // 默认 GET
+    timeout: 300, // 可选 模拟延迟毫秒
+    status: 200, // 可选 响应状态码
+    response: ({ query, params, body }) => ({
+      data: [],
+      total: 0
+    })
+  }
+];
+```
+
+规则：
+
+- url 必须与代码中的请求路径逐字一致，见 `src/api/` 下的接口模块。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`；查询参数不写进 url，在 response 的 `query` 里读取。
+- mock 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。
+- 同一 url 不允许在多个 mock 文件中重复定义，重复时开发服务启动即报错。
+- mock 只用于开发期：不进构建产物，也不要在组件里散落假数据。
+
+行为：
+
+- 命中 mock → 返回 mock 数据。
+- 未命中 → 按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径 → 返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。

package/templates/web/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "farris-cli dev",
     "build": "farris-cli build -ep",
+    "build:es": "farris-cli build --format es --outDir dist-es",
     "preview": "farris-cli preview",
     "test": "vitest run",
     "test:watch": "vitest",

package/templates/web/src/App.vue

@@ -1,5 +1,9 @@
 <script setup lang="ts">
 import { RouterLink, RouterView } from 'vue-router';
+import { setupMicroAppContext } from './micro/context';
+
+// 微前端环境：订阅主应用下发的上下文（语言 / 主题）
+setupMicroAppContext();
 </script>
 
 <template>

package/templates/web/src/main.ts

@@ -1,13 +1,47 @@
-import { createApp } from 'vue';
+import { createApp, type App as VueApp } from 'vue';
 import FarrisVue from '@farris/ui-vue';
 import '@farris/ui-vue/index.css';
 import App from './App.vue';
 import router from './router';<%= styleImport %>
 import { localResources } from './locales';
 
-const app = createApp(App);
+let app: VueApp | null = null;
 
-app.use(FarrisVue, { basePath: '', locale: 'zh-CN', localResources });
-app.use(router);
+/** 挂载应用（微前端宿主会调用 window.mount） */
+function mount(): void {
+  if (app) {
+    return;
+  }
+  app = createApp(App);
+  app.use(FarrisVue, { basePath: '', locale: 'zh-CN', localResources });
+  app.use(router);
+  app.mount('#app');
 
-app.mount('#app');
+  // 微前端环境：按平台下发的 initialPath 定位菜单配置的页面（fullPath）
+  // hash 路由必须保留这段兜底；history 路由下平台 defaultPage 已能直接命中，这里是幂等兜底
+  if (window.__MICRO_APP_ENVIRONMENT__) {
+    const rawPath = window.microApp?.getData?.()?.initialPath;
+    if (typeof rawPath === 'string' && rawPath !== '') {
+      // 平台下发的 initialPath 通常不带前导斜杠（如 'form'），这里统一归一化
+      const initialPath = rawPath.startsWith('/') ? rawPath : '/' + rawPath;
+      if (initialPath !== '/') {
+        router.isReady().then(() => router.replace(initialPath)).catch(() => undefined);
+      }
+    }
+  }
+}
+
+/** 卸载应用（微前端宿主会调用 window.unmount） */
+function unmount(): void {
+  app?.unmount();
+  app = null;
+}
+
+// 微前端（micro-app）生命周期契约：必须暴露到 window
+window.mount = mount;
+window.unmount = unmount;
+
+// 独立运行（浏览器直接访问 / iframe 嵌入）时自动挂载
+if (!window.__MICRO_APP_ENVIRONMENT__) {
+  mount();
+}

package/templates/web/src/micro/context.ts

@@ -0,0 +1,26 @@
+import { LocaleService } from '@farris/ui-vue';
+
+/**
+ * 订阅主应用通过 microApp.setGlobalData 下发的运行上下文（语言 / 主题）。
+ * 仅在微前端（micro-app）环境中生效，独立运行时不做任何处理。
+ */
+export function setupMicroAppContext(): void {
+    if (!window.__MICRO_APP_ENVIRONMENT__) {
+        return;
+    }
+
+    window.microApp?.addGlobalDataListener?.((data) => {
+        if (!data) {
+            return;
+        }
+        // 语言：主应用下发 language，同步 Farris 组件库语言
+        const i18n = (LocaleService as any)?.i18n;
+        if (typeof data.language === 'string' && i18n?.global?.locale) {
+            i18n.global.locale.value = data.language;
+        }
+        // 主题：主应用下发 theme，写入根元素供主题样式使用
+        if (typeof data.theme === 'string') {
+            document.documentElement.setAttribute('data-theme', data.theme);
+        }
+    }, true);
+}

package/templates/web/src/micro-app.d.ts

@@ -0,0 +1,20 @@
+export {};
+
+declare global {
+  interface Window {
+    /** micro-app 子应用环境标记（由宿主注入） */
+    __MICRO_APP_ENVIRONMENT__?: boolean;
+    /** 宿主注入的 micro-app API */
+    microApp?: {
+      addGlobalDataListener?: (callback: (data: any) => void, immediately?: boolean) => void;
+      setGlobalData?: (data: Record<string, any>) => void;
+      getData?: () => Record<string, any> | null;
+      router?: {
+        getBaseAppRouter?: () => any;
+      };
+    };
+    /** 微前端生命周期：宿主会调用这两个方法 */
+    mount?: () => void;
+    unmount?: () => void;
+  }
+}

package/templates/web/src/router/index.ts

@@ -1,4 +1,4 @@
-import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router';
+import { createRouter, createWebHashHistory, type RouteRecordRaw } from 'vue-router';
 
 // 生成器（farris-cli generate view --with-route）依赖下面的 routes 数组赋值形式；
 // 改动结构会导致路由无法自动注册。
@@ -16,7 +16,8 @@ export const routes: RouteRecordRaw[] = [
 ];
 
 const router = createRouter({
-  history: createWebHistory(import.meta.env.BASE_URL),
+  // hash 路由：微前端（IBP）下子应用 location 由宿主接管，hash 模式最稳妥
+  history: createWebHashHistory(),
   routes
 });