扩展开发指南

本文面向准备基于商业版前端继续扩展业务项目的研发人员。重点不是说明是否可以修改，而是明确如何在不破坏底座的前提下完成可维护的扩展开发。

扩展开发的推荐原则

原则一：优先复用底座，不要先重写底座

商业版已经有：

登录链路
站点配置
动态菜单
权限控制
通用列表和表单能力
布局与主题能力

如果尚未理解这些基础能力，就直接大规模重写，后续维护成本通常会显著增加。

原则二：把项目定制和平台化区分开

建议你在开始开发前，先判断当前需求属于哪一类：

平台通用能力：适合沉淀到 components/core、hooks/core、utils
项目专属业务：适合放在独立业务模块目录，不要污染全局

原则三：保持“页面、接口、菜单、权限”同步设计

在商业版里，一个功能通常不只是加页面，还要同步考虑：

页面
路由
接口
菜单
按钮权限

最常见的开发场景

场景一：新增一个标准业务页面

推荐顺序：

在 src/views/<module> 新建页面
在 src/api 新增接口方法
在 src/router/modules 增加路由模板
在后端菜单中新增菜单和按钮权限
补文案、类型、必要测试

场景二：新增一个整模块

建议准备下面几层：

业务页面目录
路由模块
接口文件
通用组件
菜单与权限

如果模块未来会持续扩展，不建议把所有页面都塞到一个文件夹里无结构增长。

场景三：改登录、用户和权限体验

重点文件通常在：

src/utils/http/index.ts
src/api/auth.ts
src/router/guards/beforeEach.ts
用户、菜单相关 store

这类修改风险较高，建议先理解原流程再动。

推荐的改造顺序

如果你做的是业务项目，比较稳妥的节奏通常是：

先确认品牌、菜单、权限、部署方式
再替换或新增业务页面
最后再调整布局、主题和通用交互

原因很简单：前两步决定项目是否能使用，第三步更多是体验优化。

哪些能力更适合做成可配置

如果同一套项目需要复用于多个项目，建议优先把这些内容做成可配置项，而不是硬编码：

品牌名称与欢迎文案
首页默认内容
顶部栏功能开关
站点级配置
接口域名和上传域名
菜单权限和按钮权限

高风险改法

跳过 HTTP 层，页面里直接散落手写请求
不理解动态菜单链路就直接大改守卫
只做前端按钮隐藏，不做后端权限控制
把项目专属逻辑直接写进全局组件和全局 store

扩展开发时的自检清单

在一个功能开发完成后，建议至少自查：

页面是否已加入正确菜单
按钮权限是否已配置
接口异常时是否有合理反馈
刷新页面后是否仍然工作正常
是否有逻辑值得抽到组件、hooks 或 utils

检查清单

完成一个扩展开发功能后，建议确认：

页面、接口、菜单、按钮权限和后端权限配置已同步。
项目专属逻辑保留在业务模块内，没有污染全局组件、全局 store 或路由守卫。
新增可复用能力已沉淀到合适的组件、hooks 或 utils 层。