ray-template/apps/docs/guide/architecture.md
2026-11-19 15:17:29 +08:00

15 KiB
Raw Blame History

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,请先查看兼容范围和接入方式。 版本分界