目录
背景
目前存在的问题:
- 打包发布流程
- 全量打包静态站点,打镜像,发布部署,即便只改一个标点符号大约已经一小时
- 打包占用 CI 服务器资源内存超过 12G,经常失败(且需要手动调整参数禁止并行任务)
- 纯静态站点,却部署在 k8s 服务上,还需要额外打 Docker 镜像(占用镜像仓库、CDN 、编排资源和时间)
- 设计及交互
- 没有设计规范,未遵守响应式优先
-
- 每个组件单独手写样式,冗余代码多且容易产生样式污染
- 组件排布不统一,比如 ScrollSpy 随页面滚动的导航菜单有的在左侧边栏有的在右侧边栏
- 相同功能组件样式过多(如链接、Typography 等)
- 有的页面有面包屑导航,有的没有
- 有的页面有最近更新时间,有的没有
- 文章反馈点赞和意见
-
- 机器人消息没有办法汇总和统计
- 系统配置
- 边栏手动配置
- 国际化配置非动态
- 文档内容及结构
- 包含自定义的 Markdown 语法
- 包含自定义的 Vue 组件,如:
-
- SDK 切换组件: 使用账号密码认证 | Authing 文档
- 相关文档: Express 集成 OIDC 单点登录指南 | Authing 文档
- Include 另一个 md 文档:什么是认证 | Authing 文档
- 特殊化的页面、文档,如:
-
- Step 步长引导: 接入微信扫码登录 | Authing 文档
- 含有资源的指南: Spring Security 集成 Authing OAuth 2.0 快速开始 | Authing 文档
- 以及 APN 等特殊页面
- 图片引用方式
- 内链引用方式
- 中英文文档内部的跨语言相互引用
- 以上这些均会影响文档导出成 PDF
系统架构
主要调整:
- 由纯静态站点改为动态站点
- 主要文档内容、图片及生成的 PDF 资源通过 CDN(OSS) 托管
- Git 提交判断文档变化,进行增量生成并覆盖上传 CDN
-
- 退而求其次还是依然全量,去优化打包生成的性能
- 动态配置选项:私有化部署方案将 CDN 资源路径改为本地资源路径去进行访问
入口
- 域名后负载均衡器(或者 K8s 配置)部分暂不关注
- 应用服务器应当为后期弹性伸缩做预留
- 应用服务器不用特别高的性能,主要为 IO 操作和内网请求
应用服务
为显著提升打包性能,避免使用 Webpack 传统应用框架。有两类方案。
带本地缓存的 ISR
典型且唯一具备该功能的框架 Next.js (基于 SWC 打包)。
参考: Data Fetching: Incremental Static Regeneration | Next.js
特点:
- 对于 CDN 资源的请求会稍有减少
- 本地资源可以在打包发布时构建,更新的话会稍微麻烦一点(有点类似于原有项目需要打包、打镜像、部署发布)
现代化嵌套式路由全栈框架
- 推荐 Remix,官网: Remix - Build Better Websites (基于 ESBuild 打包)
- Nuxt.js 3 RC (基于 Vite 打包)
- 站点与文档内容隔离(如果不用 MDX 或者动态组件的话)
特点:
- 更高的性能(打包及运行)
- 也可以实现类似于 Next.js 的本地缓存(如利用 LRU 等,需要额外开发)
文档增量更新
手动触发
- 在 App Server 提供一个接口
-
- 传入一个 URL Path 参数,指定更新某一篇文档 (暂不考虑数组)
- 请求接口时(同步,暂不考虑队列)
-
- HTTP + Secret Token 访问指定仓库下载文档
- 渲染生成对应的 MDX 组件或其他静态资源
- 将生成的文档和文档中的图片一并上传至 CDN(OSS)(暂不考虑图片资源删除)
CI/CD 流水线自动触发
- 提供一个脚本
-
- 检查发生的文档
- 遍历改动文件
-
- 渲染生成对应的 MDX 组件或其他静态资源
- 将生成的文档和文档中的图片一并上传至 CDN(OSS)(暂不考虑图片资源删除)
注意事项
如 Github Contributor 贡献名单、全文检索索引创建等情况也需要一并考虑。
或者预留一定扩展的能力
需求设计
建议做减法。参考多年前的文章: 需求分析-团队领袖计划
在添加产品功能需求之前,思考以下两个问题:
- 什么样的需求该忽略
- 什么样的需求该重视
原则
核心思想原则
安全 > 并发性能 > 用户体验(UE) > 用户界面(UI)
该原则适用于所有项目。
最简化可实行产品(MVP)原则
专注一个突破点。不盲目搞大。
冰冻三尺非一日之寒,一口吃不成胖子。所有庞大的系统,都是由一个个小的子系统逐步演化而来。
明确受众用户,明确核心功能,快速迭代。
其他参考
UI 设计
原则
- 响应式优先
- 设计要尊重组件,比如说 React Router Link 相关的 Class Name 是自动化添加的,不要有很奇怪的样式需要手动改动组件(体验怎么样先不说,这种无意义的工作量应当严令禁止,把 80% 的精力放在 20% 最有意义的事情上)
- 尊重已有的成熟设计规范,不做发明创造,简约即可,避免无效设计
- 规范、统一
-
- 避免使用图标字体(IconFont)、图标图片素材避免使用 png,统一使用 svg,统一使用 1024px viewbox,图标统一正方形(避免出现 15px 20px 这种不适合 ppi 缩放的尺寸, 推荐统一 2^n, 如 16px 32px 这样的单位)
- 避免使用固定值宽高、避免使用 px 绝对单位(参考 Tailwind 或 Ant Design 设计规范,避免特殊尺寸元素,如 button 可以定义 small、normal、large 尺寸,建议直接采用成熟的设计组件和元素规则)
- 文档内容(如指南、SDK 说明、集成等)尽量统一样式,不搞特殊化(即使按步骤操作的,也尽量上下平铺标题上面加第 N 步即可,方便脚本代码导出 PDF)
- 相同功能不要重复出现(如点赞按钮同时出现在顶部和底部)
- 相同功能不要出现在不同的位置(如 ScrollSpy 导航只出现在右侧边栏,不要某个特殊页面冒出在左边)
方法
Color Palette
Color Palettes for Designers and Artists - Color Hunt
主色调 4 色为佳,配合 5 个延展辅色调(可直接用 Daisy UI 提供的 20 余配色主题)。
Typography
参考上图右侧,创建一个画布,设置背景色、罗列所有元素及配色的排列组合。页面和组件均从这张完整速查表中抽取组合拼接而成。
传统设计框架
如我们官网风格基本来自于 Ant Design - 一套企业级 UI 设计语言和 React 组件库, 可以严格使用样式框架的风格和组件。
避免把精力花费在反复的样式和组件细节调整上。其他可参考的样式框架有:
- Bootstrap
- Material UI
- Element UI
- 等等
现代化设计框架
Tailwind CSS,官网:Tailwind CSS - Rapidly build modern websites without ever leaving your HTML.
配合 DaisyUI 来进行主题切换和一些常用组件设计规范定义,参考: daisyUI — Tailwind CSS Components ,包含 Typography 可以直接使用。
模块功能实现
项目拆分
- App Server 项目
- 文档拆分项目(独立管理)
-
- 中文文档项目
- 英文文档项目
应用服务
全站内容动态可配置,如站点语言、首页顶部导航菜单、各特殊页面上的内容数据、每个页面的边栏配置等
框架页面
需要特殊处理的页面模板包括不限于:
- 主页
- 开发集成
- APN
框架组件封装
包括不限于:
- 顶部菜单导航
- 底部统一链接及版权
- 语言切换组件
- 边栏导航
- ScrollSpy 页内 TOC 导航
- 最后更新时间
- Github 贡献者
- 点赞、反馈组件
- 搜索组件*
静态化资源生成
Markdown、MDX 渲染处理
参考资料:
-
- Next.js 核心开发者,谢扬多次推荐过
- Next.js 纯静态本地内容,通过 ContentLayer Contentlayer makes content easy for developers 缓存内容
- MDX 解析
-
- Remix + CDN(Cloudflare KV)远程内容数据
- 提供了 API 接口动态更新内容缓存 willin.wang/statistics.server.ts at main · willin/willin.wang
- MDX 解析
PDF Generate
注意点:
- 避免使用无头浏览器方式生成 pdf
- 避免使用 Canvas 渲染图片再生成 pdf
Github 贡献者名单获取
参考之前的知识库: 开源贡献
第三方服务集成
全文检索
全站范围全文检索,推荐使用成熟服务进行集成。
动态网站也可以通过接口搜索,但由于资源都在 CDN 中,效率较低且会产生流量