Skip to content

九、前端实现(后台 + 门户) ​

本章速览:读完后你会知道 —— ① 后台 51 条路由、89 个页面如何组织,请求层如何处理 401 与业务错误;② 门户 17 条路由与 PWA 缓存策略;③ 两个前端各自的构建、测试与验证命令。

9.1 后台(vite-cosmos-admin) ​

技术栈:Vue 3 + TypeScript + Vite + Element Plus + Pinia + vue-router + axios + md-editor-v3; 测试用 Vitest(组件/工具)+ Playwright(端到端,跑在真实生产只读数据上)。

目录与职责:

目录内容说明
src/api/26 个 API 模块(auth.ts、blog.ts、daily.ts、extensions.ts、ops.ts…)与后端端点一一对应,统一走 request.ts
src/router/路由表 + 守卫51 条路由(附录 A);meta.titleKey 驱动菜单与面包屑
src/layout/侧栏 + 顶栏 + 内容区菜单由路由表生成;移动端折叠
src/views/89 个页面组件附录 G 全量清单
src/components/通用组件(分页、上传、Markdown 预览、确认框等)与业务解耦
src/stores/Pinia 状态(登录用户、主题、侧栏)不缓存业务数据,页面各自请求
src/i18n/菜单/页面标题键(page.*)npm run i18n:check 校验路由 titleKey 与键表一致
src/utils/mdEditor.ts、格式化、下载等mdEditor.ts 见下文

请求层 request.ts 的三个细节:

  1. 拆包:响应拦截器把 {code,message,data} 拆成 data,业务码非 0 统一抛错并提示;
  2. 并发 401 去重:多个请求同时 401 时只清一次令牌、只跳一次登录;"旧请求携带旧 token" 不会误清新令牌(避免竞态把用户踢下线);
  3. 令牌存储:localStorage(vite-cosmos-token),请求拦截器统一加 Authorization。

路由守卫:beforeEach 检查令牌,无令牌跳 /login?redirect=...;登录后回跳。 权限模型是"单管理员":后端所有 /api/admin 都要求登录,前端不做细粒度按钮权限 (阻止越权靠后端,前端只做体验)。

Markdown 编辑器(utils/mdEditor.ts + 本地 vendor):

  • md-editor-v3 默认从 unpkg 懒加载 cropperjs/screenfull/prettier,被生产 CSP script-src 'self' 拦截(表现为"裁剪/全屏按钮没反应");
  • 方案:构建前 scripts/vendor-md-editor.mjs 把 cropperjs/screenfull 复制到 public/vendor/md-editor/,mdEditor.ts 用 config() 指向同源路径;prettier 直接禁用 (格式化不是刚需,不值得多塞 1MB)。高亮/KaTeX/Mermaid 在后台预览中关闭(见 13 已知缺口)。

构建与验证:

bash
npm run build     # prebuild: vendor-md-editor → vue-tsc -b → vite build → touch .tsc-pass
npm test          # Vitest:request 拆包/401 去重、sanitize、日期/重复规则工具、daily 组件
npm run test:e2e  # Playwright:53 passed / 1 skipped(生产只读,覆盖登录/关键页面)
npm run i18n:check

9.2 门户(vite-cosmos-web) ​

技术栈:Vue 3 + TypeScript + Vite + vue-router + Pinia + axios; Markdown 渲染本地打包 highlight.js + katex(不依赖 CDN,符合 CSP)。

路由(17 条,附录 B):/、/article/:id、/archive、/categories、/tags、/talk、 /album、/message、/links、/page/:slug、/favorites、/search、/series、 /series/:slug、/history、/sitemap。

主要页面与实现:

页面关键实现
首页站点信息 + 导航 + 精选/最新文章 + 说说 + 相册入口;一个聚合请求拿首屏数据
文章详情Markdown 渲染(代码高亮/公式/目录/图片灯箱);阅读计数、系列导航、上下篇、评论
归档/分类/标签后端 Meta 聚合接口;按年月/分类/标签分组
说说/相册时间线/瀑布流;懒加载图片;灯箱
留言板/友链表单 + 验证码 + 敏感词(后端四层防线);友链申请状态回显
搜索文章+页面+说说三类结果;关键词高亮;空结果引导
收藏/历史纯前端 localStorage,不上报服务端(隐私优先)
数字分身右下角浮层:访客身份(localStorage 匿名 id)→ /api/portal/ai/avatar;流式回复;额度提示
站点地图页全部页面/文章/系列的 HTML 版导航(与后端 sitemap.xml 互补)

PWA(public/sw.js):发版即失效、断网可读旧文 ——

请求类型策略
导航(HTML)网络优先,断网回退缓存的应用外壳(SPA 仍能打开)
带指纹静态资源 /assets/**缓存优先 + 后台更新(指纹变化天然不脏读)
上传图片 /uploads/**缓存优先,最多 60 张,防撑爆配额
/api/**不缓存(数据实时性优先,离线由页面自身降级)

缓存版本 __SW_VERSION__ 由构建插件注入(package 版本 + 时间戳),activate 清理旧版本缓存; vite dev 不注册 SW。manifest.webmanifest 提供图标/启动色/显示模式。

工程脚本:lint:styles(设计 token 一致)、i18n:check、config:check(配置键台账)、 ui:audit/visual-baseline(视觉审计/基线)、smoke.mjs(对生产做页面级 smoke)。

9.3 前后端契约 ​

  • 统一响应 {code,message,data,success};分页 {records,total,current,size};
  • 大整数 ID 一律字符串(后端 Jackson 配置),前端不转 Number;
  • 错误码语义见附录 D;401 统一跳登录、业务错误统一 toast;
  • 时间:接口返回 Asia/Shanghai 本地时间字符串;前端展示直接用,不再二次时区转换。

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。