主题
九、前端实现(后台 + 门户)
本章速览:读完后你会知道 —— ① 后台 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 的三个细节:
- 拆包:响应拦截器把
{code,message,data}拆成data,业务码非 0 统一抛错并提示; - 并发 401 去重:多个请求同时 401 时只清一次令牌、只跳一次登录;"旧请求携带旧 token" 不会误清新令牌(避免竞态把用户踢下线);
- 令牌存储:
localStorage(vite-cosmos-token),请求拦截器统一加Authorization。
路由守卫:beforeEach 检查令牌,无令牌跳 /login?redirect=...;登录后回跳。 权限模型是"单管理员":后端所有 /api/admin 都要求登录,前端不做细粒度按钮权限 (阻止越权靠后端,前端只做体验)。
Markdown 编辑器(utils/mdEditor.ts + 本地 vendor):
- md-editor-v3 默认从 unpkg 懒加载
cropperjs/screenfull/prettier,被生产 CSPscript-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:check9.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本地时间字符串;前端展示直接用,不再二次时区转换。