wangxuefeng/low-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新快速接入文档，sentry 放开追踪模块

Browse Source
This commit is contained in:
wangxuefeng 2025-03-24 14:22:48 +08:00
parent feadd95c4f
commit 1f6f15af9d
5 changed files with 220 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
apps/docs/src/guide/integration/index.md
View File

@ -45,6 +45,25 @@ pnpm i @sy/wujie-vue2-renderer-adapter@latest --save
npm i @sy/wujie-vue2-renderer-adapter@latest --save npm i @sy/wujie-vue2-renderer-adapter@latest --save
``` ```
```vue
<script>
import { ref } from 'vue';
import WujieVueRendererAdapter from '@sy/wujie-vue2-renderer-adapter';
</script>
<template>
<!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
<WujieVueRendererAdapter fileId="test123" projectId="test123" />
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
<WujieVueRendererAdapter
fileId="test123"
projectId="test123"
degrade="true"
/>
</template>
```
### vue3 项目接入 ### vue3 项目接入
```bash ```bash
@ -53,6 +72,25 @@ pnpm i @sy/wujie-vue3-renderer-adapter@latest --save
npm i @sy/wujie-vue3-renderer-adapter@latest --save npm i @sy/wujie-vue3-renderer-adapter@latest --save
``` ```
```vue
<script setup>
import { ref } from 'vue';
import WujieVueRendererAdapter from '@sy/wujie-vue3-renderer-adapter';
</script>
<template>
<!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
<WujieVueRendererAdapter fileId="test123" projectId="test123" />
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
<WujieVueRendererAdapter
fileId="test123"
projectId="test123"
degrade="true"
/>
</template>
```
### react 项目接入 ### react 项目接入
```bash ```bash
@ -61,6 +99,13 @@ pnpm i @sy/wujie-react-renderer-adapter@latest --save
npm 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 <WujieReactRendererAdapter fileId="test123" projectId="test123" />;
```
## API 参考 ## API 参考
- 6.1 Props 参数详解 - 6.1 Props 参数详解
@ -68,58 +113,15 @@ npm i @sy/wujie-react-renderer-adapter@latest --save
- 6.3 实例方法 - 6.3 实例方法
- 6.4 拦截器使用 - 6.4 拦截器使用
## 7. 高级用法 ## 故障排除
- 7.1 自定义主题 - 常见错误及解决方案
- 7.2 数据交互与通信 - 日志与调试
- 7.3 插件扩展 - 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记
- 7.4 微前端降级处理 - 兼容性问题处理
- renderer-adapter 是默认使用无界微应用来加载悦码渲染器应用的，这种集成方式会让悦码与你的父应用有更深的上下文结合和交互，但有一定的兼容性问题，当出现你无法解决的兼容性问题时，你可以手动设置 `degrade` 为 `false`，这将开启传统降级渲染，使用无界 iframe 加载悦码渲染器应用，若还不行，可摇人处理（王雪峰：sy3570）
## 8. 故障排除 - 性能问题诊断
- 8.1 常见错误及解决方案
- 8.2 日志与调试
- 悦码的日志输出一般在控制台中有 `console.ts 40` 的源码位置标记
- 8.3 兼容性问题处理
- renderer-adapter 是默认使用无界降级的 iframe 加载悦码渲染器应用的，你如果希望悦码与你的页面有更深的上下文结合和交互，你可以手动设置 `degrade` 为 `false`，这将开启高级渲染，但有一定的兼容性问题，如果需要在 C 端运行业务，我建议你采用默认的渲染模式
```vue
<script setup>
import { ref } from 'vue';
import { WujieVue3RendererAdapter } from '@sy/wujie-vue3-renderer-adapter';
</script>
<template>
<!-- 高级渲染模式，与原页面深度共享 document 与内存上下文 -->
<WujieVue3RendererAdapter
:degrade="false"
fileId="test123"
projectId="test123"
/>
<!-- 默认降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
<WujieVue3RendererAdapter fileId="test123" projectId="test123" />
</template>
```
- 8.4 性能问题诊断
- 悦码渲染器内部使用了 sentry 上报错误，你可以跟 徐川（sy0182） 申请对应警告邮箱的使用权，获取报错邮件 - 悦码渲染器内部使用了 sentry 上报错误，你可以跟 徐川（sy0182） 申请对应警告邮箱的使用权，获取报错邮件
![sentry 邮箱](https://cms-1256453865.cos.ap-shanghai.myqcloud.com/y-code/20250320/企业微信截图_20250320192100.png) ![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. 联系支持与反馈渠道

236
apps/docs/src/guide/introduction/quick-start.md
View File

@ -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 ```bash
# 出现相应 node LTS版本即可 # .npmrc
node -v registry=https://registry.npmmirror.com
# 出现相应 git 版本即可 @sy:registry=http://sy-registry.shiyue.com
git -v
``` ```
2. node 至少要升级为 20 以上的版本
```bash
nvm install 20
nvm use 20
```
若不可行，请查看 node 官网历代大版本的 lts 版本（长期维护），自行安装，查看是否能正常渲染，选取稳定渲染悦码的那一个 node 版本作为开发环境
::: :::
<!-- ## 接入方式
## 启动项目
### 获取源码 ### vue2 项目接入
::: code-group
```sh [GitHub]
# clone 代码
git clone https://github.com/vbenjs/vue-vben-admin.git
```
```sh [Gitee]
# clone 代码
# Gitee 的代码可能不是最新的
git clone https://gitee.com/annsion/vue-vben-admin.git
```
:::
::: danger 注意
注意存放代码的目录及所有父级目录不能存在中文、韩文、日文以及空格，否则安装依赖后启动会出错。
:::
### 安装依赖
在你的代码目录内打开终端，并执行以下命令:
```bash ```bash
# 进入项目目录 pnpm i @sy/wujie-vue2-renderer-adapter@latest --save
cd vue-vben-admin # or 或者
npm i @sy/wujie-vue2-renderer-adapter@latest --save
# 使用项目指定的pnpm版本进行依赖安装
corepack enable
# 安装依赖
pnpm install
``` ```
::: tip 注意 ```vue
<script>
import { ref } from 'vue';
import WujieVueRendererAdapter from '@sy/wujie-vue2-renderer-adapter';
</script>
- 项目只支持使用 `pnpm` 进行依赖安装，默认会使用 `corepack` 来安装指定版本的 `pnpm`。: <template>
- 如果你的网络环境无法访问npm源，你可以设置系统的环境变量`COREPACK_NPM_REGISTRY=https://registry.npmmirror.com`，然后再执行`pnpm install`。 <!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
- 如果你不想使用`corepack`，你需要禁用`corepack`，然后使用你自己的`pnpm`进行安装。 <WujieVueRendererAdapter fileId="test123" projectId="test123" />
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
::: <!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
<WujieVueRendererAdapter
### 运行项目 fileId="test123"
projectId="test123"
#### 选择项目 degrade="true"
/>
执行以下命令运行项目: </template>
```bash
# 启动项目
pnpm dev
``` ```
此时，你会看到类似如下的输出，选择你需要运行的项目： ### vue3 项目接入
```bash ```bash
│ pnpm i @sy/wujie-vue3-renderer-adapter@latest --save
◆ Select the app you need to run [dev]: # or 或者
│ ○ @vben/web-antd npm i @sy/wujie-vue3-renderer-adapter@latest --save
│ ○ @vben/web-ele
│ ○ @vben/web-naive
│ ○ @vben/docs
│ ● @vben/playground
└
``` ```
现在，你可以在浏览器访问 `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
<script setup>
import { ref } from 'vue';
import WujieVueRendererAdapter from '@sy/wujie-vue3-renderer-adapter';
</script>
<template>
<!-- 默认使用高级渲染模式，与原页面深度共享 document 与内存上下文 -->
<WujieVueRendererAdapter fileId="test123" projectId="test123" />
<!-- 降级渲染模式，使用无界 iframe 加载悦码渲染器应用 -->
<!-- 缺点在于弹窗与遮罩层会约束在 iframe 空间内，无法与原页面共享 document，但无界的 iframe 可以与原页面共享内存上下文 ，这是比传统 iframe 更优的解决方案 -->
<WujieVueRendererAdapter
fileId="test123"
projectId="test123"
degrade="true"
/>
</template>
```
### react 项目接入
```bash ```bash
pnpm run dev:antd pnpm i @sy/wujie-react-renderer-adapter@latest --save
pnpm run dev:ele # or 或者
pnpm run dev:naive npm i @sy/wujie-react-renderer-adapter@latest --save
pnpm run dev:docs ```
pnpm run dev:play
``` --> ```jsx
import { ref } from 'vue';
import WujieReactRendererAdapter from '@sy/wujie-react-renderer-adapter';
return <WujieReactRendererAdapter fileId="test123" projectId="test123" />;
```
## 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)

63
apps/platform/src/router/routes/modules/micro.ts
View File

@ -1,37 +1,18 @@
import type { RouteRecordRaw } from 'vue-router'; import type { RouteRecordRaw } from 'vue-router';
import RendererAdapter from '@sy/vue3-renderer-adapter'; import RendererAdapter from '@sy/vue3-renderer-adapter';
import WujieVueRendererAdapter from '@sy/wujie-vue3-renderer-adapter';
import axios from 'axios';
import { import {
isDevMode, isDevMode,
LOW_CODE_PROJECT_ID, LOW_CODE_PROJECT_ID,
VITE_DESIGNER_URL, VITE_DESIGNER_URL,
VITE_RENDERER_URL,
VITE_V1_URL, VITE_V1_URL,
} from '#/constants'; } 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[] = [ const routes: RouteRecordRaw[] = [
{ {
path: '/micro', path: '/micro',
name: moduleName, name: 'Micro',
meta: { meta: {
title: '微应用容器', title: '微应用容器',
icon: 'ant-design:appstore-outlined', icon: 'ant-design:appstore-outlined',
@ -82,42 +63,12 @@ const routes: RouteRecordRaw[] = [
icon: 'ant-design:delete-outlined', icon: 'ant-design:delete-outlined',
}, },
component: RendererAdapter, component: RendererAdapter,
props: { // component: WujieVueRendererAdapter,
url: `${VITE_V1_URL}`, props: () => {
accessToken: localStorage.getItem('y-code-access-token'), return {
}, 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',
},
// <WujieVue3RendererAdapter
// fileId="45udpmfvz"
// :interceptors="interceptors"
// name="45udpmfvz"
// :degrade="false"
// projectId="21"
// />
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,
}, },
}, },
], ],

8
apps/renderer/src/index.ts
View File

@ -21,13 +21,13 @@ Sentry.init({
dsn: 'https://5bcf1344794fea64fc5e5fe7da4821c1@o4508962650783744.ingest.de.sentry.io/4508962653143120', dsn: 'https://5bcf1344794fea64fc5e5fe7da4821c1@o4508962650783744.ingest.de.sentry.io/4508962653143120',
integrations: [ integrations: [
// 异常路径回放 // 异常路径回放
// Sentry.replayIntegration(), Sentry.replayIntegration(),
// 异常端信息追踪 // 异常端信息追踪
// Sentry.browserTracingIntegration(), Sentry.browserTracingIntegration(),
], ],
// Session Replay // 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. 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. replaysOnErrorSampleRate: 1, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur.
}); });
// 批量注册组件 // 批量注册组件

1
apps/y-code-v1/vite.config.ts
View File

@ -33,7 +33,6 @@ export default defineConfig(({ mode }) => {
? { ? {
cors: true, cors: true,
port: Number(env.VITE_PORT), port: Number(env.VITE_PORT),
https: isDev, // 启用 https，配合 mkcert 插件
} }
: undefined, : undefined,