15 KiB
v6 Monorepo 架构
Ray Template v6 使用同一个 pnpm workspace 管理 Ray Admin、VitePress 文档站和 10 个共享包。Ray Admin 负责登录、业务页面和应用状态。文档站用同一份组件源码运行示例,共享包通过公开入口提供可复用的实现。
工作区总览
ray-template/
├─ apps/
│ ├─ admin/ Ray Admin
│ │ ├─ index.html 后台入口
│ │ ├─ example.html 文档示例入口
│ │ └─ src/
│ │ ├─ main.ts 应用启动
│ │ ├─ App.tsx 全局服务
│ │ ├─ app-config/ 应用配置
│ │ ├─ app-components/ 宿主组件
│ │ ├─ locales/ 中英文资源
│ │ ├─ router/ 路由与守卫
│ │ │ └─ config/ 配置源与视图表
│ │ ├─ store/ Pinia 状态
│ │ │ ├─ modules/ 会话/菜单/偏好
│ │ │ └─ hooks/ 状态读写入口
│ │ ├─ layout/ 外壳适配
│ │ ├─ views/ 业务和演示页面
│ │ ├─ api/ 业务端点
│ │ │ ├─ admin/ 管理端点
│ │ │ └─ demo/ 示例查询
│ │ ├─ axios/ 请求和拦截器
│ │ └─ mocks/ MSW 与演示状态
│ └─ docs/ VitePress
│ ├─ .vitepress/
│ │ ├─ config.mts 站点配置
│ │ ├─ sidebar.mts 文档侧栏
│ │ ├─ legacy.mts 旧链接映射
│ │ └─ theme/ 主题和样式
│ ├─ guide/ 开发指南
│ ├─ reference/ API 参考
│ ├─ examples/ Vue 交互示例
│ └─ playground/ 布局预览页面
├─ packages/
│ ├─ admin-shell/ 布局外壳
│ ├─ routing/ 路由与导航
│ ├─ ui/ 组件与主题
│ ├─ icons/ SVG 图标
│ ├─ http/ 请求与取消
│ ├─ api-contracts/ API 与路由契约
│ ├─ demo-data/ 演示数据与查询
│ ├─ composables/ Vue Hooks
│ ├─ directives/ Vue 指令
│ └─ utils/ 工具函数
├─ harness/ 任务索引与检查
└─ pnpm-lock.yaml 工作区锁文件
Ray Admin 使用图中的全部共享包。文档站直接引入组件、布局、路由等示例所需的包,需要完整后台上下文时通过 iframe 打开独立的示例入口。各应用在自己的 package.json 声明依赖,共用一份锁文件。 工作区配置 · 完整工程地图
全栈源码还包含独立运行的 apps/server。 服务端架构
Ray Admin 怎么组装
启动与全局服务
index.html → main.ts
↓
安装 Pinia 和中英文语言包
↓
恢复会话 → 初始化 Vue Router
↓
安装 Day.js 和指令 → 挂载 App
↓
App.tsx → 全局 Provider
↓
RouterView → 当前路由页面
独立运行和无界子应用使用同一套插件安装流程。启动时先恢复会话,再决定是否加载账户路由。src/app-config/ 集中提供主题、路由、请求和缓存配置。 启动入口 · 应用配置
App.tsx 装配 Naive UI、全局样式、水印和加载状态,通过 @ray-template/ui/services 注入主题、翻译、图标地址、消息回调和列偏好存储。共享 UI 组件通过 UiServices 读取这些能力,因此文档示例也可以按自己的上下文使用组件。 App 源码
从路由配置到菜单和页面
内置 JSON / 本地配置 / 远端配置
↓
router/config/source.ts 选择配置源
↓
api-contracts 校验路由结构
↓
routing + config/views.ts
将 view ID 绑定到页面加载函数
↓
Vue Router + 应用守卫
├─→ store/menu → 菜单、标签、面包屑
└─→ RLayout → AdminShell → 页面
router/负责注册登录页、系统页和当前账户的路由。内置配置来自demo-data,应用在router/config/views.ts登记可加载的views/页面。导航守卫根据已核验的会话和路由权限判断能否进入页面。 路由、菜单与权限store/按职责维护状态。signing管理会话,menu根据权限生成菜单并随路由同步标签和面包屑,keep-alive维护页面缓存名单。setting持久化选定的偏好字段,runtime中的加载、抽屉和最大化状态随应用重新挂载而重建。应用通过 Store Hooks 读写这些状态。 Store 参考layout/是后台对共享外壳的适配层。RLayout将布局偏好和导航、内容等插槽交给AdminShell。默认内容槽装配请求取消和路由过渡,过渡组件根据缓存配置和名单渲染KeepAlive。 应用布局与状态
一次业务请求经过哪些层
views/ 或 store/
↓ 调用业务接口
api/admin/ 或 api/demo/
↓
axios/ 应用拦截器
↓
@ray-template/http Axios 实例
├─→ MSW → mocks/ → 演示数据
└─→ HTTP → 接入的 API
api/ 封装端点,管理端客户端处理会话传输,并用 api-contracts 校验响应。axios/ 根据应用配置装配请求、响应和错误拦截器。http 为每个实例创建取消器,调用方可传入自己的 AbortSignal。 接口、取消与 Mock
本地开发和静态在线演示可走同一套 MSW HTTP Mock。mocks/handlers.ts 实现接口,mocks/database.ts 管理演示会话、用户和路由的读写,demo-data 提供初始数据和查询辅助。接入真实 API 后,由服务端核验会话并授权资源访问。 服务端接入与标准契约
文档怎样运行组件
文档页面
├─ 直接渲染 examples/*.vue
│ └─ 共享包入口(如 ui/table-pro)
└─ 通过 AdminExample.vue 嵌入页面
└─ admin/example.html
└─ documentation-example.tsx
└─ 允许展示的后台示例路由
- 直接运行。 精度运算、条形码和 TablePro 等 Vue 示例导入共享包,Markdown 引用同一份
.vue文件展示源码。TablePro 由示例传入本地行数据或可取消的模拟查询。布局实验使用单独的预览页面和内存路由。 精度运算 · 条形码 · TablePro 示例 · 布局实验 - 嵌入后台示例。 依赖后台布局或应用上下文的例子使用
AdminExample.vue。后台的example.html有独立启动入口、受限的示例路由和独立 Pinia 实例,普通应用缓存走内存,表格列显隐走单独的会话存储命名空间。 文档站源码说明
可选服务端怎样分层
apps/server/src/main.ts 启动独立的 NestJS HTTP 服务。app.ts 注册业务模块、平台中间件以及全局响应拦截器和异常过滤器。
浏览器 /api 请求
↓
platform/ ─────────→ Redis
↓ 限流、演示缓存
NestJS 守卫与控制器
├─ auth / users / routes
│ └─ Prisma → PostgreSQL
└─ demo(按配置启用)
└─ @ray-template/demo-data
modules/auth/管理认证与会话,并安装全局权限守卫。modules/users/负责账户管理和部门、角色选项,modules/routes/读取、过滤和保存路由配置。业务模块通过共享的api-contracts定义和校验 HTTP 数据。infrastructure/database.ts封装 Prisma 访问。prisma/下的 schema 和迁移定义 PostgreSQL 中的用户、凭据、权限、会话、路由配置和操作审计。会话及权限以数据库为准。platform/管理 Redis、请求 ID、日志、安全中间件与健康检查。Redis 用于限流和部分可重建的演示读请求缓存。演示端点按部署配置启用,共用demo-data。
apps/server 独立构建,包含在全栈源码发行包中。 服务端源码说明 · 发行版本与快速启动
各包负责什么
下图只画共享包之间的直接依赖,箭头从使用方指向被依赖方。图中的短目录名对应 @ray-template/<包名>。
admin-shell
├─→ ui ───────┬─→ composables
│ ├─→ icons
│ └─→ utils
├─→ routing ──┬─→ api-contracts
│ ├─→ icons
│ └─→ utils
├─→ composables
└─→ icons
directives ──┬─→ composables
└─→ utils
composables ───→ utils
http ──────────→ utils
demo-data ─────→ api-contracts
包通过 package.json#exports 声明可导入的入口。跨工作区优先按功能导入,例如 @ray-template/ui/table-pro 或 @ray-template/utils/precision。rayTemplate.runtime 区分 browser、server 与 universal。api-contracts 和 demo-data 是通用包,可供浏览器端和服务端使用,且只依赖同为通用的工作区。应用位于依赖图的消费端,各自通过公开入口组装功能。pnpm packages:check 检查工作区依赖、公开入口和循环依赖。 包边界检查
界面、布局与路由
@ray-template/admin-shell以AdminShell.tsx实现布局模式和插槽位置,TopNavigation.tsx、ShellTab.tsx和menu-keyboard.ts封装导航、标签和键盘交互。LayoutSettings.tsx提供布局选项,RouteTransition.vue负责过渡与缓存渲染。宿主传入布局状态、菜单项、导航动作和页面内容。 外壳公开入口@ray-template/routing通过/contract接收宿主注册的视图、保留路径和权限规则,把可序列化配置转换为 Vue Router 记录,并支持导出。/expand-routes、/order-routes和/navigation提供展开、排序和菜单树遍历。/schema和/json-schema保留兼容入口,对应实现来自api-contracts。 路由包公开入口@ray-template/ui按组件组织实现、类型和样式,提供/table-pro、/form、/chart、/barcode等入口。/theme.css和/theme-presets提供设计变量与主题预设,/services把宿主的主题、翻译、消息和存储适配接入组件。 组件参考@ray-template/icons按目录组织 SVG,由生成的/manifest提供完整图标名、类型和分组资源地址。后台构建按组生成精灵图。RIcon和路由配置复用同一套名称,例如navigation/table。 SVG 图标
以 TablePro 为例,TablePro.tsx 组合筛选、分页、查询和实例 API,useTableSearch 管理搜索草稿与提交条件,useTableRequest 管理远端请求状态和取消,TablePanel 负责 Naive UI 表格、列设置与表格工具。宿主决定查询实现和列偏好存储。 TablePro 参考 · 组件源码入口
搜索提交 / 切换分页
↓
TablePro → useTableRequest
↓
宿主 request(params, signal)
↓
本页 data + 筛选后的 total
↓
TablePanel → Naive UI NDataTable
HTTP、契约与演示数据
@ray-template/http通过client.ts的createHttpClient装配独立的 Axios 实例。实例解析并返回 HTTP 响应体,RequestCanceler跟踪和清理待处理请求。宿主配置地址、请求头和拦截策略。 请求客户端源码@ray-template/api-contracts在/admin定义通用响应、会话和管理接口模型,在/demo定义演示查询和响应。routes.ts是路由 Schema 的源文件,/route-validation提供结构校验,/route-json-schema和/openapi生成供编辑器和 API 集成使用的描述。前端、Mock 和服务端共用这套 Valibot 契约。 契约包说明@ray-template/demo-data在routes.json提供内置路由,并提供初始选项、图表、订单和人员数据,以及搜索、筛选和分页辅助函数。调用方决定何时启用演示,并负责自己的会话和写入。 演示数据包说明
Hooks、指令与工具
@ray-template/composables在/vue提供 Vue 生命周期与元素引用等辅助函数,功能 Hook 按入口拆分,例如/useDevice、/useElementFullscreen、/useDomToImage和/usePrint。后台特有的导航、布局和状态 Hooks 由apps/admin/src/hooks/template/维护。 Hooks 参考@ray-template/directives在src/modules/按指令组织实现和类型。宿主可按需导入/copy、/debounce、/throttle等入口,Ray Admin 的src/directives/index.ts统一注册模板所用指令。 指令参考@ray-template/utils通过/precision提供精度运算,/core、/files和/types提供对象、文件和类型工具。/storage接收宿主提供的存储实现后执行带命名空间的 JSON 读写,应用负责选择存储位置与缓存键。 工具函数参考
构建与部署
pnpm dev 启动后台,pnpm docs:dev 启动文档。pnpm build 输出后台,pnpm docs:build 输出文档,pnpm pages:build 组装两者到 dist/pages。官方部署路径分别是 /ray-template/ 和 /ray-template/docs/。 构建与部署指南
如果当前项目基于 v5,请先查看兼容范围和接入方式。 版本分界