From 1f6f15af9daa8b5311afb9bf054ce02262cfc713 Mon Sep 17 00:00:00 2001 From: wangxuefeng Date: Mon, 24 Mar 2025 14:22:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=BF=AB=E9=80=9F?= =?UTF-8?q?=E6=8E=A5=E5=85=A5=E6=96=87=E6=A1=A3=EF=BC=8Csentry=20=E6=94=BE?= =?UTF-8?q?=E5=BC=80=E8=BF=BD=E8=B8=AA=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/docs/src/guide/integration/index.md | 102 ++++---- .../src/guide/introduction/quick-start.md | 236 ++++++++++++------ .../src/router/routes/modules/micro.ts | 63 +---- apps/renderer/src/index.ts | 8 +- apps/y-code-v1/vite.config.ts | 1 - 5 files changed, 220 insertions(+), 190 deletions(-) diff --git a/apps/docs/src/guide/integration/index.md b/apps/docs/src/guide/integration/index.md index d3ec0d0..b939529 100644 --- a/apps/docs/src/guide/integration/index.md +++ b/apps/docs/src/guide/integration/index.md @@ -45,6 +45,25 @@ pnpm i @sy/wujie-vue2-renderer-adapter@latest --save npm i @sy/wujie-vue2-renderer-adapter@latest --save ``` +```vue + + + +``` + ### vue3 项目接入 ```bash @@ -53,6 +72,25 @@ pnpm i @sy/wujie-vue3-renderer-adapter@latest --save npm i @sy/wujie-vue3-renderer-adapter@latest --save ``` +```vue + + + +``` + ### react 项目接入 ```bash @@ -61,6 +99,13 @@ pnpm i @sy/wujie-react-renderer-adapter@latest --save npm i @sy/wujie-react-renderer-adapter@latest --save ``` +```jsx +import { ref } from 'vue'; +import WujieReactRendererAdapter from '@sy/wujie-react-renderer-adapter'; + +return ; +``` + ## API 参考 - 6.1 Props 参数详解 @@ -68,58 +113,15 @@ npm i @sy/wujie-react-renderer-adapter@latest --save - 6.3 实例方法 - 6.4 拦截器使用 -## 7. 高级用法 +## 故障排除 -- 7.1 自定义主题 -- 7.2 数据交互与通信 -- 7.3 插件扩展 -- 7.4 微前端降级处理 +- 常见错误及解决方案 +- 日志与调试 +- 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记 +- 兼容性问题处理 +- renderer-adapter 是默认使用无界微应用来加载悦码渲染器应用的，这种集成方式会让悦码与你的父应用有更深的上下文结合和交互，但有一定的兼容性问题，当出现你无法解决的兼容性问题时，你可以手动设置 `degrade` 为 `false`，这将开启传统降级渲染，使用无界 iframe 加载悦码渲染器应用，若还不行，可摇人处理（王雪峰：sy3570） -## 8. 故障排除 - -- 8.1 常见错误及解决方案 -- 8.2 日志与调试 - - 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记 -- 8.3 兼容性问题处理 -- renderer-adapter 是默认使用无界降级的 iframe 加载悦码渲染器应用的，你如果希望悦码与你的页面有更深的上下文结合和交互，你可以手动设置 `degrade` 为 `false`，这将开启高级渲染，但有一定的兼容性问题，如果需要在 C 端运行业务，我建议你采用默认的渲染模式 - -```vue - - - -``` - -- 8.4 性能问题诊断 +- 性能问题诊断 - 悦码渲染器内部使用了 sentry 上报错误，你可以跟 徐川（sy0182） 申请对应警告邮箱的使用权，获取报错邮件 ![sentry 邮箱](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250320/企业微信截图_20250320192100.png) - -## 9. 最佳实践 - -- 9.1 推荐的项目结构 -- 9.2 安全性建议 -- 9.3 性能优化建议 -- 9.4 版本升级策略 - -## 10. 示例 - - - 10.1 基础示例 - - 10.2 完整应用示例 - - 10.3 实际案例展示 - -## 11. 常见问题 (FAQ) - -## 12. 联系支持与反馈渠道 diff --git a/apps/docs/src/guide/introduction/quick-start.md b/apps/docs/src/guide/introduction/quick-start.md index fcc0f28..41c16d6 100644 --- a/apps/docs/src/guide/introduction/quick-start.md +++ b/apps/docs/src/guide/introduction/quick-start.md @@ -6,107 +6,185 @@ outline: deep ## 前置准备 -::: info 环境要求 +::: info 适用项目 -在启动项目前，你需要确保你的环境满足以下要求： +- vue2 +- vue3 +- react +- 其他框架请联系伊利（sy）或王雪峰（sy3570）添加适配器 -- [Node.js](https://nodejs.org/en) 20.15.0 及以上版本，推荐使用 [fnm](https://github.com/Schniz/fnm) 、 [nvm](https://github.com/nvm-sh/nvm) 或者直接使用[pnpm](https://pnpm.io/cli/env) 进行版本管理。 -- [Git](https://git-scm.com/) 任意版本。 +## 环境要求 -验证你的环境是否满足以上要求，你可以通过以下命令查看版本： +- node >= 20 +- vue2 > 2.7.0 +- vue3 > 3.5.0 +- react > 18.0.0 + +## 准备工作 + +1. npmrc 配置文件增加镜像指定，sy 组件库走 shiyue 源，其他走淘宝镜像 ```bash -# 出现相应 node LTS版本即可 -node -v -# 出现相应 git 版本即可 -git -v +# .npmrc +registry=https://registry.npmmirror.com +@sy:registry=http://sy-registry.shiyue.com ``` +2. node 至少要升级为 20 以上的版本 + +```bash +nvm install 20 +nvm use 20 +``` + +若不可行，请查看 node 官网历代大版本的 lts 版本（长期维护），自行安装，查看是否能正常渲染，选取稳定渲染悦码的那一个 node 版本作为开发环境 + ::: - + + + + + ``` -此时，你会看到类似如下的输出，选择你需要运行的项目： +### vue3 项目接入 ```bash -│ -◆ Select the app you need to run [dev]: -│ ○ @vben/web-antd -│ ○ @vben/web-ele -│ ○ @vben/web-naive -│ ○ @vben/docs -│ ● @vben/playground -└ +pnpm i @sy/wujie-vue3-renderer-adapter@latest --save +# or 或者 +npm i @sy/wujie-vue3-renderer-adapter@latest --save ``` -现在，你可以在浏览器访问 `http://localhost:5555` 查看项目。 +#### 路由形式使用 -#### 运行指定项目 +```ts +import type { RouteRecordRaw } from 'vue-router'; -如果你不想选择项目，可以直接运行以下命令运行你需要的应用： +import RendererAdapter from '@sy/vue3-renderer-adapter'; + +import { isDevMode, LOW_CODE_PROJECT_ID, VITE_DESIGNER_URL } from '@/constants'; +import router from '@/router'; + +const routes: RouteRecordRaw[] = [ + { + path: '/micro', + name: 'Micro', + meta: { + title: '微应用容器', + icon: 'ant-design:appstore-outlined', + }, + children: [ + { + path: 'admin-designer', + name: 'AdminDesigner', + meta: { + hideInMenu: !isDevMode, + title: '平台设计器', + icon: 'ant-design:edit-outlined', + }, + component: RendererAdapter, + // 可动态注入 props,根据必要性，可以注入 route 等参数 + // 悦码里通过 ctxProps 获取，意思为上下文参数 + props: (route) => { + return { + url: `${VITE_DESIGNER_URL}`, + projectId: LOW_CODE_PROJECT_ID, + fileId: 'test123', + // 你还可以提供 父应用的 router，来实现子应用执行父应用的 router 方法来实现跳转 + router, // 悦码里通过 ctxProps.router 调用 + query: { + ...route.query, + }, + }; + }, + }, + ], + }, +]; + +export default routes; +``` + +#### 组件形式使用 + +```vue + + + +``` + +### react 项目接入 ```bash -pnpm run dev:antd -pnpm run dev:ele -pnpm run dev:naive -pnpm run dev:docs -pnpm run dev:play -``` --> +pnpm i @sy/wujie-react-renderer-adapter@latest --save +# or 或者 +npm i @sy/wujie-react-renderer-adapter@latest --save +``` + +```jsx +import { ref } from 'vue'; +import WujieReactRendererAdapter from '@sy/wujie-react-renderer-adapter'; + +return ; +``` + +## API 参考 + +- 6.1 Props 参数详解 +- 6.2 事件监听与回调 +- 6.3 实例方法 +- 6.4 拦截器使用 + +## 故障排除 + +- 常见错误及解决方案 +- 日志与调试 +- 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记 +- 兼容性问题处理 +- renderer-adapter 是默认使用无界微应用来加载悦码渲染器应用的，这种集成方式会让悦码与你的父应用有更深的上下文结合和交互，但有一定的兼容性问题，当出现你无法解决的兼容性问题时，你可以手动设置 `degrade` 为 `false`，这将开启传统降级渲染，使用无界 iframe 加载悦码渲染器应用，若还不行，可摇人处理（王雪峰：sy3570） + +- 性能问题诊断 +- 悦码渲染器内部使用了 sentry 上报错误，你可以跟 徐川（sy0182） 申请对应警告邮箱的使用权，获取报错邮件 +- 也可以加到悦码渲染器的报错沟通群，跟进自己应用的报错推送 + +![sentry.dashboard](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250324/企业微信截图_1742796499189.png) + +![报错沟通群](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250324/企业微信截图_17427961669787.png) + +![sentry 邮箱](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250320/企业微信截图_20250320192100.png) diff --git a/apps/platform/src/router/routes/modules/micro.ts b/apps/platform/src/router/routes/modules/micro.ts index a2b5883..c0fdc66 100644 --- a/apps/platform/src/router/routes/modules/micro.ts +++ b/apps/platform/src/router/routes/modules/micro.ts @@ -1,37 +1,18 @@ import type { RouteRecordRaw } from 'vue-router'; import RendererAdapter from '@sy/vue3-renderer-adapter'; -import WujieVueRendererAdapter from '@sy/wujie-vue3-renderer-adapter'; -import axios from 'axios'; import { isDevMode, LOW_CODE_PROJECT_ID, VITE_DESIGNER_URL, - VITE_RENDERER_URL, VITE_V1_URL, } from '#/constants'; -const baseAxios = axios.create({ - baseURL: 'http://localhost:3000', -}); - -const testToken = - 'Bearer eyJraWQiOiJjMzA3NjIwYi1mNzUzLTQ4NjAtYmNmMi01ZDk2NDljOWJlNjYiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJzeTM1MjIiLCJhdWQiOiIxODk3MTEwMDA3NzA1MDY3NTIwIiwibmJmIjoxNzQyNTM3OTkzLCJzY29wZSI6WyJvcGVuaWQiXSwiaXNzIjoiaHR0cDovL2F1dGgtcHJvLWFwaS5zaGl5dWUuY29tIiwiZXhwIjoxNzQyNTM5NzkzLCJpYXQiOjE3NDI1Mzc5OTMsImp0aSI6ImNmZDAyMThjLWUzMmYtNDAyZi04ZmE3LTcxYWY0YzkyODBlZCJ9.REA6izxHosUyXUixXVqwjVcQeKGuUvy5T5PT-tfoP4Qp5R6GcHO81Dd8KS0Vy1jKxpmsRUSBggKxOVkuZ1eLPdUesYfItdAn6kd-VJMJlh-6R9T2wEHc4eIobCvvNnqQVBuFUU56nr-qew9Vho8BCynGZw-FxPkhi1IbmJgJRCY85XXQdBme6gNPyTWnQqaKWPQBqqmjnq8l_zk0sYPUpRvF7b-n4hBFOmiXYXfgx90RcOki2i4dzO3PTQwCPhZzXVeG2GXGORNYTm0CFCUIZkanp0tphd40Ow-wFc7bGjwcfxzpm01lBqMpfLXDILh73R9QkG0KkKM78N1f4AFu_Q'; - -baseAxios.interceptors.request.use((config) => { - config.headers.Authorization = testToken; - return config; -}); - -const interceptors = baseAxios.interceptors; - -const moduleName = 'micro'; - const routes: RouteRecordRaw[] = [ { path: '/micro', - name: moduleName, + name: 'Micro', meta: { title: '微应用容器', icon: 'ant-design:appstore-outlined', @@ -82,42 +63,12 @@ const routes: RouteRecordRaw[] = [ icon: 'ant-design:delete-outlined', }, component: RendererAdapter, - props: { - url: `${VITE_V1_URL}`, - accessToken: localStorage.getItem('y-code-access-token'), - }, - }, - { - path: 'test', - name: `Test`, - meta: { - // hideInMenu: true, - keepAlive: false, - title: '测试', - icon: 'ant-design:delete-outlined', - }, - // - component: WujieVueRendererAdapter, - // props: { - // url: `${VITE_RENDERER_URL}`, - // fileId: '45ud9h6n3', - // projectId: LOW_CODE_PROJECT_ID, - // degrade: false, - // name: '45ud9h6n3', - // }, - props: { - url: `${VITE_RENDERER_URL}`, - fileId: '45udpmfvz', - projectId: 21, - degrade: false, - name: '45udpmfvz', - interceptors, + // component: WujieVueRendererAdapter, + props: () => { + return { + url: `${VITE_V1_URL}`, + accessToken: localStorage.getItem('y-code-access-token'), + }; }, }, ], diff --git a/apps/renderer/src/index.ts b/apps/renderer/src/index.ts index ef51838..df81222 100644 --- a/apps/renderer/src/index.ts +++ b/apps/renderer/src/index.ts @@ -21,13 +21,13 @@ Sentry.init({ dsn: 'https://5bcf1344794fea64fc5e5fe7da4821c1@o4508962650783744.ingest.de.sentry.io/4508962653143120', integrations: [ // 异常路径回放 - // Sentry.replayIntegration(), + Sentry.replayIntegration(), // 异常端信息追踪 - // Sentry.browserTracingIntegration(), + Sentry.browserTracingIntegration(), ], // Session Replay - // replaysSessionSampleRate: 0.1, // This sets the sample rate at 10%. You may want to change it to 100% while in development and then sample at a lower rate in production. - // replaysOnErrorSampleRate: 1, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur. + replaysSessionSampleRate: 0.1, // This 1sets the sample rate at 10%. You may want to change it to 100% while in development and then sample at a lower rate in production. + replaysOnErrorSampleRate: 1, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur. }); // 批量注册组件 diff --git a/apps/y-code-v1/vite.config.ts b/apps/y-code-v1/vite.config.ts index 64614d6..b441c96 100644 --- a/apps/y-code-v1/vite.config.ts +++ b/apps/y-code-v1/vite.config.ts @@ -33,7 +33,6 @@ export default defineConfig(({ mode }) => { ? { cors: true, port: Number(env.VITE_PORT), - https: isDev, // 启用 https，配合 mkcert 插件 } : undefined,