前端架构

技术栈

• React
• TypeScript
• Umi Max
• Ant Design
• ProComponents

这套技术栈的定位不是做营销官网，而是支撑大型 SaaS 后台的长期演进，所以工程一致性、页面骨架统一性、权限接入方式和响应式规则，会比单页视觉自由度更重要。

推荐三层结构

壳层

放在 layouts/，负责：

• 主布局
• 顶部工具区
• 侧边导航
• 用户菜单
• 全局抽屉、通知入口、主题切换

壳层负责“系统长什么样、怎么进出各模块”，而不是承载某个业务页面的细节逻辑。

基础能力层

分布在 services/、auth/、hooks/、features/、theme/ 等目录，负责：

• 请求封装
• 认证恢复
• 错误处理
• 权限快照消费
• 通用表格和抽屉能力
• 响应式和主题令牌

这一层是前端最值得沉淀的地方。做得好，后续新增页面基本是在复用系统能力；做得不好，每个页面都会偷偷长出自己的一套请求、显隐、弹窗和状态处理逻辑。

业务页面层

放在 pages/，重点只做业务表达，不重复造壳层和基础设施。

业务页应该更多关注：

• 页面字段和文案
• 查询条件
• 列表列定义
• 表单结构
• 详情展示
• 与业务 owner 模块的接口交互

页面骨架应该尽量统一

对于管理后台，统一骨架比“每个页面做一套新布局”更重要。典型列表页建议统一成：

• 页面头
• 查询区
• 操作区
• 表格区
• 抽屉或详情区

当前仓库里很多管理页已经沉淀为 ManagementPage、ManagementDrawer、权限 hooks 等通用模式，新增页面尽量复用这些模式。

请求层约定

前端请求统一走 frontend/src/services/common/request.ts。

这层会处理：

• token 注入
• requestId 注入
• JSON 与 FormData 序列化
• 超时
• 登录失效处理
• API 错误转义

因此业务页面不应该自己重复写 fetch 细节。

统一请求层的价值主要有三点：

• 环境差异统一收口
• 错误处理一致
• 权限与会话失效行为一致

权限接入

前端可以做：

• 菜单显隐
• 按钮显隐
• 页面跳转守卫

前端不能代替后端做真实权限判断。按钮隐藏只是交互控制，不是安全边界。

推荐理解方式是：

• 前端负责“用户看到什么、怎么操作更顺”
• 后端负责“用户到底有没有权做这件事”

响应式规则

• 桌面端优先完整信息密度
• 平板端应保留核心后台结构，但压缩信息密度
• 移动端优先单列和关键操作
• 不要在移动端硬塞桌面布局
• 抽屉、表格、工具栏都要考虑窄屏行为

要特别注意，响应式不是简单缩放，而是结构重组。平板端不应该退化成和手机一样的布局，尤其是在文档、管理台、列表页这类场景里。

抽屉、弹窗和全局悬浮交互

后台系统里很容易出现多个层叠交互，所以要遵守几个约束：

• 轻量确认用弹窗
• 中等复杂度的查看或编辑优先用抽屉
• 复杂长流程不要继续塞进小弹层
• 全局悬浮操作层级必须低于当前活跃抽屉，避免遮挡关键按钮

这也是为什么前端壳层和业务页不能各自随意管理浮层层级，否则很容易出现抽屉打开时被全局浮窗干扰操作的问题。

页面级复用建议

比较适合尽早沉淀成系统组件的包括：

• 页面容器
• 查询区
• 表格容器
• 详情抽屉
• 状态标签
• 权限按钮
• 上传组件
• 空态与错误态

当一个交互模式已经出现在两个以上页面时，就应该开始考虑抽象，而不是继续复制。

一个重要约束

前端始终调用 /api/** 的相对路径，而不是某个具体服务地址。这样未来后端无论继续聚合运行，还是重新拆成物理微服务，前端服务层都不用整体重写。

开发时最常见的前端误区

误区 1：业务页自己处理所有请求细节

这样会让 token、超时、错误提示、重试、上传等行为越来越不一致。

误区 2：权限只做前端裁剪

这会导致页面看似安全，实际接口可以被直接调用。

误区 3：桌面端布局强行压到移动端

这样通常会得到“看似响应式，实际不可用”的页面，尤其在表格、查询区、抽屉这类场景里最明显。

误区 4：页面自己发明一套交互容器

如果管理页已经有 ManagementPage、ManagementDrawer、表格工具栏等模式，就优先复用，不要为了一个页面重新造一套壳子。